MQTTClient: MQTTSession Class Reference

#import <MQTTSession.h>

Inheritance diagram for MQTTSession:

Instance Methods
(void)	- connect

(void)	- connectWithConnectHandler:

(void)	- disconnect

(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)	- 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 *	clientId

NSString *	userName

NSString *	password

UInt16	keepAliveInterval

BOOL	cleanSessionFlag

BOOL	willFlag

NSString *	willTopic

NSData *	willMsg

MQTTQosLevel	willQoS

BOOL	willRetainFlag

MQTTProtocolVersion	protocolLevel

NSRunLoop *	runLoop

NSString *	runLoopMode

MQTTSSLSecurityPolicy *	securityPolicy

MQTTMessage *	connectMessage

id< MQTTTransport >	transport

NSArray *	certificates

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");
}];

§ connect()

- (void) connect

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

Exceptions

NSInternalInconsistencyException if the parameters are invalid

§ 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

§ 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 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: 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

§ 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

see initWithClientId for description

Parameters

clientId 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 {
   ...
}

§ 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.

§ 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.

§ protocolLevel

- (MQTTProtocolVersion) protocolLevel

readwritenonatomicassign

protocolLevel specifies the protocol to be used

§ 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.

§ securityPolicy

- (MQTTSSLSecurityPolicy*) securityPolicy

readwritenonatomicstrong

The security policy used to evaluate server trust for secure connections. (see MQTTSSLSecurityPolicy.h for more detail).

§ sessionPresent

- (BOOL) sessionPresent

readnonatomicassign

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

§ status

- (MQTTSessionStatus) status

readnonatomicassign

Session status

§ 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.

§ 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:()

§ connect()

§ connectWithConnectHandler:()

§ disconnect()

§ 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

§ certificates

§ cleanSessionFlag

§ clientId

§ connectHandler

§ connectionHandler

§ connectMessage

§ delegate

§ keepAliveInterval

§ messageHandler

§ password

§ persistence

§ protocolLevel

§ runLoop

§ runLoopMode

§ securityPolicy

§ sessionPresent

§ status

§ transport

§ userName

§ willFlag

§ willMsg

§ willQoS

§ willRetainFlag

§ willTopic