MQTTClient: MQTTSession Class Reference

#import <MQTTSession.h>

Inheritance diagram for MQTTSession:

Instance Methods
(void)	- connect

(void)	- connectWithConnectHandler:

(void)	- disconnect

(void)	- disconnectWithReturnCode:sessionExpiryInterval:reasonString:userProperty:

(MQTTSession *)	- init

(UInt16)	- subscribeToTopic:atLevel:

(UInt16)	- subscribeToTopic:atLevel:subscribeHandler:

(UInt16)	- subscribeToTopics:

(UInt16)	- subscribeToTopics:subscribeHandler:

(UInt16)	- unsubscribeTopic:

(UInt16)	- unsubscribeTopic:unsubscribeHandler:

(UInt16)	- unsubscribeTopics:

(UInt16)	- unsubscribeTopics:unsubscribeHandler:

(UInt16)	- publishData:onTopic:retain:qos:

(UInt16)	- publishData:onTopic:retain:qos:publishHandler:

(void)	- closeWithDisconnectHandler:

(void)	- closeWithReturnCode:sessionExpiryInterval:reasonString:userProperty:disconnectHandler:

(void)	- close

Properties
id< MQTTSessionDelegate >	delegate

id< MQTTPersistence >	persistence

MQTTConnectHandler	connectHandler

void(^	connectionHandler )(MQTTSessionEvent event)

void(^	messageHandler )(NSData message, NSString topic)

MQTTSessionStatus	status

BOOL	sessionPresent

NSString *	host

UInt32	port

NSString *	clientId

NSString *	userName

NSString *	password

UInt16	keepAliveInterval

NSNumber *	serverKeepAlive

UInt16	effectiveKeepAlive

double	dupTimeout

BOOL	cleanSessionFlag

BOOL	willFlag

NSString *	willTopic

NSData *	willMsg

MQTTQosLevel	willQoS

BOOL	willRetainFlag

MQTTProtocolVersion	protocolLevel

NSNumber *	sessionExpiryInterval

NSString *	authMethod

NSData *	authData

NSNumber *	requestProblemInformation

NSNumber *	willDelayInterval

NSNumber *	requestResponseInformation

NSNumber *	receiveMaximum

NSNumber *	topicAliasMaximum

NSDictionary< NSString , NSString > *	userProperty

NSNumber *	maximumPacketSize

NSRunLoop *	runLoop

NSString *	runLoopMode

MQTTMessage *	connectMessage

id< MQTTTransport >	transport

NSArray *	certificates

BOOL	voip

Detailed Description

Session implements the MQTT protocol for your application

Method Documentation

◆ close()

- (void) close

closes an MQTTSession gracefully

◆ closeWithDisconnectHandler:()

- (void) closeWithDisconnectHandler: (MQTTDisconnectHandler) disconnectHandler

closes an MQTTSession gracefully

If the connection was successfully established before, a DISCONNECT is sent.

Parameters

disconnectHandler identifies a block which is executed on successfull or unsuccessfull disconnect. Might be nil. error is nil in the case of a successful disconnect

#import "MQTTClient.h"
MQTTSession *session = [[MQTTSession alloc] init];
...
[session connect];
...
[session closeWithDisconnectHandler^(NSError *error) {
   if (error) {
       NSLog(@"Error Disconnect %@", error.localizedDescription);
   }
   NSLog(@"Session closed");
}];

◆ closeWithReturnCode:sessionExpiryInterval:reasonString:userProperty:disconnectHandler:()

- (void) closeWithReturnCode:	(MQTTReturnCode)	returnCode
sessionExpiryInterval:	(NSNumber *)	sessionExpiryInterval
reasonString:	(NSString *)	reasonString
userProperty:	(NSDictionary< NSString , NSString > *)	userProperty
disconnectHandler:	(MQTTDisconnectHandler)	disconnectHandler

close V5

Parameters

returnCode	the returncode send to the broker
sessionExpiryInterval	the time in seconds before the session can be deleted
reasonString	a string explaining the reason
userProperty	additional dictionary of user key/value combinations
disconnectHandler	will be called when the disconnect finished

◆ connect()

- (void) connect

connect to the given host through the given transport with the given MQTT session parameters asynchronously

◆ connectWithConnectHandler:()

- (void) connectWithConnectHandler: (MQTTConnectHandler) connectHandler

connects to the specified MQTT server

Parameters

connectHandler

identifies a block which is executed on successfull or unsuccessfull connect. Might be nil error is nil in the case of a successful connect sessionPresent indicates in MQTT 3.1.1 if persistent session data was present at the server returns nothing and returns immediately. To check the connect results, register as an MQTTSessionDelegate and

watch for events
watch for connect or connectionRefused messages
watch for error messages or use the connectHandler block

#import "MQTTClient.h"
MQTTSession *session = [[MQTTSession alloc] init];
...
[session connectWithConnectHandler:^(NSError *error, BOOL sessionPresent) {
if (error) {
NSLog(@"Error Connect %@", error.localizedDescription);
} else {
NSLog(@"Connected sessionPresent:%d", sessionPresent);
}
}];

◆ disconnect()

- (void) disconnect

disconnect gracefully

◆ disconnectWithReturnCode:sessionExpiryInterval:reasonString:userProperty:()

- (void) disconnectWithReturnCode:	(MQTTReturnCode)	returnCode
sessionExpiryInterval:	(NSNumber *)	sessionExpiryInterval
reasonString:	(NSString *)	reasonString
userProperty:	(NSDictionary< NSString , NSString > *)	userProperty

disconnect V5

Parameters

returnCode	the returncode send to the broker
sessionExpiryInterval	the time in seconds before the session can be deleted
reasonString	a string explaining the reason
userProperty	additional dictionary of user key/value combinations

◆ init()

- (MQTTSession *) init

initialises the MQTT session with default values

Returns: the initialised MQTTSession object
#import "MQTTClient.h"
MQTTSession *session = [[MQTTSession alloc] init];

◆ publishData:onTopic:retain:qos:()

- (UInt16) publishData:	(NSData *)	data
onTopic:	(NSString *)	topic
retain:	(BOOL)	retainFlag
qos:	(MQTTQosLevel)	qos

publishes data on a given topic at a specified QoS level and retain flag

Parameters

data	the data to be sent. length may range from 0 to 268,435,455 - 4 - lengthof-topic bytes. Defaults to length 0.
topic	the Topic to identify the data
retainFlag	if YES, data is stored on the MQTT broker until overwritten by the next publish with retainFlag = YES
qos	specifies the Quality of Service for the publish qos can be 0, 1, or 2.

Returns: the Message Identifier of the PUBLISH message. Zero if qos 0. If qos 1 or 2, zero if message was dropped

Note: returns immediately. To check results, register as an MQTTSessionDelegate and watch for events.

#import "MQTTClient.h"
MQTTSession *session = [[MQTTSession alloc] init];
...
[session connect];
[session publishData:[@"Sample Data" dataUsingEncoding:NSUTF8StringEncoding]
topic:@"example/data"
retain:YES
qos:1];

◆ publishData:onTopic:retain:qos:publishHandler:()

- (UInt16) publishData:	(NSData *)	data
onTopic:	(NSString *)	topic
retain:	(BOOL)	retainFlag
qos:	(MQTTQosLevel)	qos
publishHandler:	(MQTTPublishHandler)	publishHandler

publishes data on a given topic at a specified QoS level and retain flag

Parameters

data	the data to be sent. length may range from 0 to 268,435,455 - 4 - lengthof-topic bytes. Defaults to length 0.
topic	the Topic to identify the data
retainFlag	if YES, data is stored on the MQTT broker until overwritten by the next publish with retainFlag = YES
qos	specifies the Quality of Service for the publish qos can be 0, 1, or 2.
publishHandler	identifies a block which is executed on successfull or unsuccessfull publsh. Might be nil error is nil in the case of a successful connect sessionPresent indicates in MQTT 3.1.1 if persistent session data was present at the server

Returns: the Message Identifier of the PUBLISH message. Zero if qos 0. If qos 1 or 2, zero if message was dropped

Note: returns immediately. To check results, register as an MQTTSessionDelegate and watch for events.

#import "MQTTClient.h"
MQTTSession *session = [[MQTTSession alloc] init];
...
[session connect];
[session publishData:[@"Sample Data" dataUsingEncoding:NSUTF8StringEncoding]
topic:@"example/data"
retain:YES
qos:1
publishHandler:^(NSError *error){
if (error) {
DDLogVerbose(@"error: %@ %@", error.localizedDescription, payload);
} else {
DDLogVerbose(@"delivered:%@", payload);
delivered++;
}
}];

◆ subscribeToTopic:atLevel:()

- (UInt16) subscribeToTopic:	(NSString *)	topic
atLevel:	(MQTTQosLevel)	qosLevel

subscribes to a topic at a specific QoS level

Parameters

topic	see subscribeToTopic:atLevel:subscribeHandler: for description
qosLevel	see subscribeToTopic:atLevel:subscribeHandler: for description

Returns: the Message Identifier of the SUBSCRIBE message.

Note: returns immediately. To check results, register as an MQTTSessionDelegate and watch for events.

#import "MQTTClient.h"
MQTTSession *session = [[MQTTSession alloc] init];
...
[session connect];
...
[session subscribeToTopic:@"example/#" atLevel:2];

◆ subscribeToTopic:atLevel:subscribeHandler:()

- (UInt16) subscribeToTopic:	(NSString *)	topic
atLevel:	(MQTTQosLevel)	qosLevel
subscribeHandler:	(MQTTSubscribeHandler)	subscribeHandler

subscribes to a topic at a specific QoS level

Parameters

topic	the Topic Filter to subscribe to.
qosLevel	specifies the QoS Level of the subscription. qosLevel can be 0, 1, or 2.
subscribeHandler	identifies a block which is executed on successfull or unsuccessfull subscription. Might be nil. error is nil in the case of a successful subscription. In this case gQoss represents an array of grantes Qos

Returns: the Message Identifier of the SUBSCRIBE message.

Note: returns immediately. To check results, register as an MQTTSessionDelegate and watch for events.

#import "MQTTClient.h"
MQTTSession *session = [[MQTTSession alloc] init];
...
[session connect];
...
[session subscribeToTopic:@"example/#" atLevel:2 subscribeHandler:^(NSError *error, NSArray<NSNumber *> *gQoss){
   if (error) {
       NSLog(@"Subscription failed %@", error.localizedDescription);
   } else {
       NSLog(@"Subscription sucessfull! Granted Qos: %@", gQoss);
   }
}];

◆ subscribeToTopics:()

- (UInt16) subscribeToTopics: (NSDictionary< NSString *, NSNumber * > *) topics

subscribes a number of topics

Parameters

topics an NSDictionary<NSString *, NSNumber *> containing the Topic Filters to subscribe to as keys and the corresponding QoS as NSNumber values

Returns: the Message Identifier of the SUBSCRIBE message.

Note: returns immediately. To check results, register as an MQTTSessionDelegate and watch for events.

#import "MQTTClient.h"
MQTTSession *session = [[MQTTSession alloc] init];
...
[session connect];
[session subscribeToTopics:@{
@"example/#": @(0),
@"example/status": @(2),
@"other/#": @(1)
}];

◆ subscribeToTopics:subscribeHandler:()

- (UInt16) subscribeToTopics:	(NSDictionary< NSString , NSNumber > *)	topics
subscribeHandler:	(MQTTSubscribeHandler)	subscribeHandler

subscribes a number of topics

Parameters

topics	an NSDictionary<NSString , NSNumber > containing the Topic Filters to subscribe to as keys and the corresponding QoS as NSNumber values
subscribeHandler	identifies a block which is executed on successfull or unsuccessfull subscription. Might be nil. error is nil in the case of a successful subscription. In this case gQoss represents an array of grantes Qos

Returns: the Message Identifier of the SUBSCRIBE message.

Note: returns immediately. To check results, register as an MQTTSessionDelegate and watch for events.

#import "MQTTClient.h"
MQTTSession *session = [[MQTTSession alloc] init];
...
[session connect];
[session subscribeToTopics:@{
   @"example/#": @(0),
   @"example/status": @(2),
   @"other/#": @(1)
} subscribeHandler:^(NSError *error, NSArray<NSNumber *> *gQoss){
   if (error) {
       NSLog(@"Subscription failed %@", error.localizedDescription);
   } else {
       NSLog(@"Subscription sucessfull! Granted Qos: %@", gQoss);
   }
}];

◆ unsubscribeTopic:()

- (UInt16) unsubscribeTopic: (NSString *) topic

unsubscribes from a topic

Parameters

topic the Topic Filter to unsubscribe from.

Returns: the Message Identifier of the UNSUBSCRIBE message.

Note: returns immediately. To check results, register as an MQTTSessionDelegate and watch for events.

#import "MQTTClient.h"
MQTTSession *session = [[MQTTSession alloc] init];
...
[session connect];
[session unsubscribeTopic:@"example/#"];

◆ unsubscribeTopic:unsubscribeHandler:()

- (UInt16) unsubscribeTopic:	(NSString *)	topic
unsubscribeHandler:	(MQTTUnsubscribeHandler)	unsubscribeHandler

unsubscribes from a topic

Parameters

topic	the Topic Filter to unsubscribe from.
unsubscribeHandler	identifies a block which is executed on successfull or unsuccessfull subscription. Might be nil. error is nil in the case of a successful subscription. In this case gQoss represents an array of grantes Qos

Returns: the Message Identifier of the UNSUBSCRIBE message.

Note: returns immediately.

◆ unsubscribeTopics:()

- (UInt16) unsubscribeTopics: (NSArray< NSString * > *) topics

unsubscribes from a number of topics

Parameters

topics an NSArray<NSString *> of topics to unsubscribe from

Returns: the Message Identifier of the UNSUBSCRIBE message.

Note: returns immediately. To check results, register as an MQTTSessionDelegate and watch for events.

#import "MQTTClient.h"
MQTTSession *session = [[MQTTSession alloc] init];
...
[session connect];
[session unsubscribeTopics:@[
@"example/#",
@"example/status",
@"other/#"
]];

◆ unsubscribeTopics:unsubscribeHandler:()

- (UInt16) unsubscribeTopics:	(NSArray< NSString * > *)	topics
unsubscribeHandler:	(MQTTUnsubscribeHandler)	unsubscribeHandler

unsubscribes from a number of topics

Parameters

topics	an NSArray<NSString *> of topics to unsubscribe from
unsubscribeHandler	identifies a block which is executed on successfull or unsuccessfull subscription. Might be nil. error is nil in the case of a successful subscription. In this case gQoss represents an array of grantes Qos

Returns: the Message Identifier of the UNSUBSCRIBE message.

Note: returns immediately.

Property Documentation

◆ authData

- (NSData*) authData

readwritenonatomicstrong

authData specifies the number of seconds after which a session should expire MQTT v5.0

◆ authMethod

- (NSString*) authMethod

readwritenonatomicstrong

authMethod specifies the number of seconds after which a session should expire MQTT v5.0

◆ certificates

- (NSArray*) certificates

readwritenonatomicstrong

certificates an NSArray holding client certificates or nil

◆ cleanSessionFlag

- (BOOL) cleanSessionFlag

readwritenonatomicassign

leanSessionFlag specifies if the server should discard previous session information.

◆ clientId

- (NSString*) clientId

readwritenonatomicstrong

The Client Identifier identifies the Client to the Server. If nil, a random clientId is generated.

◆ connectHandler

- (MQTTConnectHandler) connectHandler

readwritenonatomiccopy

block called once when connection is established

◆ connectionHandler

- (void(^ connectionHandler) (MQTTSessionEvent event))

readwriteatomicstrong

block called when connection is established

◆ connectMessage

- (MQTTMessage*) connectMessage

readwritenonatomicstrong

for mqttio-OBJC backward compatibility the connect message used is stored here

◆ delegate

- (id<MQTTSessionDelegate>) delegate

readwritenonatomicweak

set this member variable to receive delegate messages

#import "MQTTClient.h"
@interface MyClass : NSObject <MQTTSessionDelegate>
...
@end
...
MQTTSession *session = [[MQTTSession alloc] init];
session.delegate = self;
...
- (void)handleEvent:(MQTTSession *)session
       event:(MQTTSessionEvent)eventCode
       error:(NSError *)error {
   ...
}
- (void)newMessage:(MQTTSession *)session
       data:(NSData *)data
       onTopic:(NSString *)topic
       qos:(MQTTQosLevel)qos
       retained:(BOOL)retained
       mid:(unsigned int)mid {
   ...
}

◆ dupTimeout

- (double) dupTimeout

readwritenonatomicassign

dupTimeout If PUBACK or PUBREC not received, message will be resent after this interval

◆ effectiveKeepAlive

- (UInt16) effectiveKeepAlive

readnonatomicassign

effectiveKeepAlive is a time interval measured in seconds It indicates the effective keep alive interval after a successfull connect where keepAliveInterval might have been overridden by the broker.

◆ host

- (NSString*) host

readatomicassign

host an NSString containing the hostName or IP address of the Server

◆ keepAliveInterval

- (UInt16) keepAliveInterval

readwritenonatomicassign

see keepAliveInterval The Keep Alive is a time interval measured in seconds. The MQTTClient ensures that the interval between Control Packets being sent does not exceed the Keep Alive value. In the absence of sending any other Control Packets, the Client sends a PINGREQ Packet.

◆ maximumPacketSize

- (NSNumber*) maximumPacketSize

readwritenonatomicstrong

maximumPacketSize specifies the number of seconds after which a session should expire MQTT v5.0

◆ messageHandler

- (void(^ messageHandler) (NSData *message, NSString *topic))

readwriteatomicstrong

block called when message is received

◆ password

- (NSString*) password

readwritenonatomicstrong

see password an NSString object containing the user's password. If userName is nil, password must be nil as well.

◆ persistence

- (id<MQTTPersistence>) persistence

readwritenonatomicstrong

Control MQTT persistence by setting the properties of persistence before connecting to an MQTT broker. The settings are specific to a clientId.

persistence.persistent = YES or NO (default) to establish file or in memory persistence. IMPORTANT: set immediately after creating the MQTTSession before calling any other method. Otherwise the default value (NO) will be used for this session.

persistence.maxWindowSize (a positive number, default is 16) to control the number of messages sent before waiting for acknowledgement in Qos 1 or 2. Additional messages are stored and transmitted later.

persistence.maxSize (a positive number of bytes, default is 64 MB) to limit the size of the persistence file. Messages published after the limit is reached are dropped.

persistence.maxMessages (a positive number, default is 1024) to limit the number of messages stored. Additional messages published are dropped.

Messages are deleted after they have been acknowledged.

◆ port

- (UInt32) port

readatomicassign

port an unsigned 32 bit integer containing the IP port number of the Server

◆ protocolLevel

- (MQTTProtocolVersion) protocolLevel

readwritenonatomicassign

protocolLevel specifies the protocol to be used

◆ receiveMaximum

- (NSNumber*) receiveMaximum

readwritenonatomicstrong

receiveMaximum specifies the number of seconds after which a session should expire MQTT v5.0

◆ requestProblemInformation

- (NSNumber*) requestProblemInformation

readwritenonatomicstrong

requestProblemInformation specifies the number of seconds after which a session should expire MQTT v5.0

◆ requestResponseInformation

- (NSNumber*) requestResponseInformation

readwritenonatomicstrong

requestResponseInformation specifies the number of seconds after which a session should expire MQTT v5.0

◆ runLoop

- (NSRunLoop*) runLoop

readwritenonatomicstrong

runLoop The runLoop where the streams are scheduled. If nil, defaults to [NSRunLoop currentRunLoop].

◆ runLoopMode

- (NSString*) runLoopMode

readwritenonatomicstrong

runLoopMode The runLoopMode where the streams are scheduled. If nil, defaults to NSRunLoopCommonModes.

◆ serverKeepAlive

- (NSNumber*) serverKeepAlive

readnonatomicstrong

The serverKeepAlive is a time interval measured in seconds. This value may be set by the broker and overrides keepAliveInterval if present Zero means the broker does not perform any keep alive checks

◆ sessionExpiryInterval

- (NSNumber*) sessionExpiryInterval

readwritenonatomicstrong

sessionExpiryInterval specifies the number of seconds after which a session should expire MQTT v5.0

◆ sessionPresent

- (BOOL) sessionPresent

readnonatomicassign

Indicates if the broker found a persistent session when connecting with cleanSession:FALSE

◆ status

- (MQTTSessionStatus) status

readnonatomicassign

Session status

◆ topicAliasMaximum

- (NSNumber*) topicAliasMaximum

readwritenonatomicstrong

topicAliasMaximum specifies the number of seconds after which a session should expire MQTT v5.0

◆ transport

- (id<MQTTTransport>) transport

readwritenonatomicstrong

the transport provider for MQTTClient

assign an in instance of a class implementing the MQTTTransport protocol e.g. MQTTCFSocketTransport before connecting.

◆ userName

- (NSString*) userName

readwritenonatomicstrong

see userName an NSString object containing the user's name (or ID) for authentication. May be nil.

◆ userProperty

- (NSDictionary<NSString *, NSString*>*) userProperty

readwritenonatomicstrong

topicAliasMaximum specifies the number of seconds after which a session should expire MQTT v5.0

◆ voip

- (BOOL) voip

readwritenonatomicassign

Require for VoIP background service defaults to NO

◆ willDelayInterval

- (NSNumber*) willDelayInterval

readwritenonatomicstrong

willDelayInterval specifies the number of seconds after which a session should expire MQTT v5.0

◆ willFlag

- (BOOL) willFlag

readwritenonatomicassign

willFlag If the Will Flag is set to YES this indicates that a Will Message MUST be published by the Server when the Server detects that the Client is disconnected for any reason other than the Client flowing a DISCONNECT Packet.

◆ willMsg

- (NSData*) willMsg

readwritenonatomicstrong

willMsg If the Will Flag is set to YES the Will Message must be specified, nil otherwise.

◆ willQoS

- (MQTTQosLevel) willQoS

readwritenonatomicassign

willQoS specifies the QoS level to be used when publishing the Will Message. If the Will Flag is set to NO, then the Will QoS MUST be set to 0. If the Will Flag is set to YES, the Will QoS MUST be a valid MQTTQosLevel.

◆ willRetainFlag

- (BOOL) willRetainFlag

readwritenonatomicassign

willRetainFlag indicates if the server should publish the Will Messages with retainFlag. If the Will Flag is set to NO, then the Will Retain Flag MUST be set to NO . If the Will Flag is set to YES: If Will Retain is set to NO, the Serve MUST publish the Will Message as a non-retained publication [MQTT-3.1.2-14]. If Will Retain is set to YES, the Server MUST publish the Will Message as a retained publication [MQTT-3.1.2-15].

◆ willTopic

- (NSString*) willTopic

readwritenonatomicstrong

willTopic If the Will Flag is set to YES, the Will Topic is a string, nil otherwise.

The documentation for this class was generated from the following file:

MQTTSession.h

Instance Methods

Properties

Detailed Description

Method Documentation

◆ close()

◆ closeWithDisconnectHandler:()

◆ closeWithReturnCode:sessionExpiryInterval:reasonString:userProperty:disconnectHandler:()

◆ connect()

◆ connectWithConnectHandler:()

◆ disconnect()

◆ disconnectWithReturnCode:sessionExpiryInterval:reasonString:userProperty:()

◆ init()

◆ publishData:onTopic:retain:qos:()

◆ publishData:onTopic:retain:qos:publishHandler:()

◆ subscribeToTopic:atLevel:()

◆ subscribeToTopic:atLevel:subscribeHandler:()

◆ subscribeToTopics:()

◆ subscribeToTopics:subscribeHandler:()

◆ unsubscribeTopic:()

◆ unsubscribeTopic:unsubscribeHandler:()

◆ unsubscribeTopics:()

◆ unsubscribeTopics:unsubscribeHandler:()

Property Documentation

◆ authData

◆ authMethod

◆ certificates

◆ cleanSessionFlag

◆ clientId

◆ connectHandler

◆ connectionHandler

◆ connectMessage

◆ delegate

◆ dupTimeout

◆ effectiveKeepAlive

◆ host

◆ keepAliveInterval

◆ maximumPacketSize

◆ messageHandler

◆ password

◆ persistence

◆ port

◆ protocolLevel

◆ receiveMaximum

◆ requestProblemInformation

◆ requestResponseInformation

◆ runLoop

◆ runLoopMode

◆ serverKeepAlive

◆ sessionExpiryInterval

◆ sessionPresent

◆ status

◆ topicAliasMaximum

◆ transport

◆ userName

◆ userProperty

◆ voip

◆ willDelayInterval

◆ willFlag

◆ willMsg

◆ willQoS

◆ willRetainFlag

◆ willTopic