lipengwei
2020-01-13 ea8e18fe8cc8ef08da463c82dec74e3fb918ab58
commit | author | age
ea8e18 1 //
L 2 // MQTTSession.h
3 // MQTTClient.framework
4 //
5
6 /**
7  Using MQTT in your Objective-C application
8  
9  @author Christoph Krey krey.christoph@gmail.com
10  @copyright Copyright © 2013-2016, Christoph Krey 
11  
12  based on Copyright (c) 2011, 2013, 2lemetry LLC
13     All rights reserved. This program and the accompanying materials
14     are made available under the terms of the Eclipse Public License v1.0
15     which accompanies this distribution, and is available at
16     http://www.eclipse.org/legal/epl-v10.html
17  
18  @see http://mqtt.org
19  */
20
21
22 #import <Foundation/Foundation.h>
23
24 #import "MQTTMessage.h"
25 #import "MQTTPersistence.h"
26 #import "MQTTTransport.h"
27
28 @class MQTTSession;
29 @class MQTTSSLSecurityPolicy;
30
31 /**
32  Enumeration of MQTTSession states
33  */
34 typedef NS_ENUM(NSInteger, MQTTSessionStatus) {
35     MQTTSessionStatusCreated,
36     MQTTSessionStatusConnecting,
37     MQTTSessionStatusConnected,
38     MQTTSessionStatusDisconnecting,
39     MQTTSessionStatusClosed,
40     MQTTSessionStatusError
41 };
42
43 /**
44  Enumeration of MQTTSession events
45  */
46 typedef NS_ENUM(NSInteger, MQTTSessionEvent) {
47     MQTTSessionEventConnected,
48     MQTTSessionEventConnectionRefused,
49     MQTTSessionEventConnectionClosed,
50     MQTTSessionEventConnectionError,
51     MQTTSessionEventProtocolError,
52     MQTTSessionEventConnectionClosedByBroker
53 };
54
55 /**
56  The error domain used for all errors created by MQTTSession
57  */
58 extern NSString * const MQTTSessionErrorDomain;
59
60 /**
61  The error codes used for all errors created by MQTTSession
62  */
63 typedef NS_ENUM(NSInteger, MQTTSessionError) {
64     MQTTSessionErrorConnectionRefused = -8, // Sent if the server closes the connection without sending an appropriate error CONNACK
65     MQTTSessionErrorIllegalMessageReceived = -7,
66     MQTTSessionErrorDroppingOutgoingMessage = -6, // For some reason the value is the same as for MQTTSessionErrorNoResponse
67     MQTTSessionErrorNoResponse = -6, // For some reason the value is the same as for MQTTSessionErrorDroppingOutgoingMessage
68     MQTTSessionErrorEncoderNotReady = -5,
69     MQTTSessionErrorInvalidConnackReceived = -2, // Sent if the message received from server was an invalid connack message
70     MQTTSessionErrorNoConnackReceived = -1, // Sent if first message received from server was no connack message
71     MQTTSessionErrorConnackUnacceptableProtocolVersion = 1, // Value as defined by MQTT Protocol
72     MQTTSessionErrorConnackIdentifierRejected = 2, // Value as defined by MQTT Protocol
73     MQTTSessionErrorConnackServeUnavailable = 3, // Value as defined by MQTT Protocol
74     MQTTSessionErrorConnackBadUsernameOrPassword = 4, // Value as defined by MQTT Protocol
75     MQTTSessionErrorConnackNotAuthorized = 5, // Value as defined by MQTT Protocol
76     MQTTSessionErrorConnackReserved = 6, // Should be value 6-255, as defined by MQTT Protocol
77 };
78
79 /** Session delegate gives your application control over the MQTTSession
80  @note all callback methods are optional
81  */
82
83 @protocol MQTTSessionDelegate <NSObject>
84
85 @optional
86
87 /** gets called when a new message was received
88  @param session the MQTTSession reporting the new message
89  @param data the data received, might be zero length
90  @param topic the topic the data was published to
91  @param qos the qos of the message
92  @param retained indicates if the data retransmitted from server storage
93  @param mid the Message Identifier of the message if qos = 1 or 2, zero otherwise
94  */
95 - (void)newMessage:(MQTTSession *)session
96               data:(NSData *)data
97            onTopic:(NSString *)topic
98                qos:(MQTTQosLevel)qos
99           retained:(BOOL)retained
100                mid:(unsigned int)mid;
101
102 /** gets called when a new message was received
103  @param session the MQTTSession reporting the new message
104  @param data the data received, might be zero length
105  @param topic the topic the data was published to
106  @param qos the qos of the message
107  @param retained indicates if the data retransmitted from server storage
108  @param mid the Message Identifier of the message if qos = 1 or 2, zero otherwise
109  @return true if the message was or will be processed, false if the message shall not be ack-ed
110  */
111 - (BOOL)newMessageWithFeedback:(MQTTSession *)session
112                           data:(NSData *)data
113                        onTopic:(NSString *)topic
114                            qos:(MQTTQosLevel)qos
115                       retained:(BOOL)retained
116                            mid:(unsigned int)mid;
117
118 /** for mqttio-OBJC backward compatibility
119  @param session see newMessage for description
120  @param data see newMessage for description
121  @param topic see newMessage for description
122  */
123 - (void)session:(MQTTSession*)session newMessage:(NSData*)data onTopic:(NSString*)topic;
124
125 /** gets called when a connection is established, closed or a problem occurred
126  @param session the MQTTSession reporting the event
127  @param eventCode the code of the event
128  @param error an optional additional error object with additional information
129  */
130 - (void)handleEvent:(MQTTSession *)session event:(MQTTSessionEvent)eventCode error:(NSError *)error;
131
132 /** for mqttio-OBJC backward compatibility
133  @param session the MQTTSession reporting the event
134  @param eventCode the code of the event
135  */
136 - (void)session:(MQTTSession*)session handleEvent:(MQTTSessionEvent)eventCode;
137
138 /** gets called when a connection has been successfully established
139  @param session the MQTTSession reporting the connect
140  
141  */
142 - (void)connected:(MQTTSession *)session;
143
144 /** gets called when a connection has been successfully established
145  @param session the MQTTSession reporting the connect
146  @param sessionPresent represents the Session Present flag sent by the broker
147  
148  */
149 - (void)connected:(MQTTSession *)session sessionPresent:(BOOL)sessionPresent;
150
151 /** gets called when a connection has been refused
152  @param session the MQTTSession reporting the refusal
153  @param error an optional additional error object with additional information
154  */
155 - (void)connectionRefused:(MQTTSession *)session error:(NSError *)error;
156
157 /** gets called when a connection has been closed
158  @param session the MQTTSession reporting the close
159
160  */
161 - (void)connectionClosed:(MQTTSession *)session;
162
163 /** gets called when a connection error happened
164  @param session the MQTTSession reporting the connect error
165  @param error an optional additional error object with additional information
166  */
167 - (void)connectionError:(MQTTSession *)session error:(NSError *)error;
168
169 /** gets called when an MQTT protocol error happened
170  @param session the MQTTSession reporting the protocol error
171  @param error an optional additional error object with additional information
172  */
173 - (void)protocolError:(MQTTSession *)session error:(NSError *)error;
174
175 /** gets called when a published message was actually delivered
176  @param session the MQTTSession reporting the delivery
177  @param msgID the Message Identifier of the delivered message
178  @note this method is called after a publish with qos 1 or 2 only
179  */
180 - (void)messageDelivered:(MQTTSession *)session msgID:(UInt16)msgID;
181
182 /** gets called when a subscription is acknowledged by the MQTT broker
183  @param session the MQTTSession reporting the acknowledge
184  @param msgID the Message Identifier of the SUBSCRIBE message
185  @param qoss an array containing the granted QoS(s) related to the SUBSCRIBE message
186     (see subscribeTopic, subscribeTopics)
187  */
188 - (void)subAckReceived:(MQTTSession *)session msgID:(UInt16)msgID grantedQoss:(NSArray<NSNumber *> *)qoss;
189
190 /** gets called when an unsubscribe is acknowledged by the MQTT broker
191  @param session the MQTTSession reporting the acknowledge
192  @param msgID the Message Identifier of the UNSUBSCRIBE message
193  */
194 - (void)unsubAckReceived:(MQTTSession *)session msgID:(UInt16)msgID;
195
196 /** gets called when a command is sent to the MQTT broker
197  use this for low level monitoring of the MQTT connection
198  @param session the MQTTSession reporting the sent command
199  @param type the MQTT command type
200  @param qos the Quality of Service of the command
201  @param retained the retained status of the command
202  @param duped the duplication status of the command
203  @param mid the Message Identifier of the command
204  @param data the payload data of the command if any, might be zero length
205  */
206 - (void)sending:(MQTTSession *)session type:(MQTTCommandType)type qos:(MQTTQosLevel)qos retained:(BOOL)retained duped:(BOOL)duped mid:(UInt16)mid data:(NSData *)data;
207
208 /** gets called when a command is received from the MQTT broker
209  use this for low level monitoring of the MQTT connection
210  @param session the MQTTSession reporting the received command
211  @param type the MQTT command type
212  @param qos the Quality of Service of the command
213  @param retained the retained status of the command
214  @param duped the duplication status of the command
215  @param mid the Message Identifier of the command
216  @param data the payload data of the command if any, might be zero length
217  */
218 - (void)received:(MQTTSession *)session type:(MQTTCommandType)type qos:(MQTTQosLevel)qos retained:(BOOL)retained duped:(BOOL)duped mid:(UInt16)mid data:(NSData *)data;
219
220 /** gets called when a command is received from the MQTT broker
221  use this for low level control of the MQTT connection
222  @param session the MQTTSession reporting the received command
223  @param type the MQTT command type
224  @param qos the Quality of Service of the command
225  @param retained the retained status of the command
226  @param duped the duplication status of the command
227  @param mid the Message Identifier of the command
228  @param data the payload data of the command if any, might be zero length
229  @return true if the sessionmanager should ignore the received message
230  */
231 - (BOOL)ignoreReceived:(MQTTSession *)session type:(MQTTCommandType)type qos:(MQTTQosLevel)qos retained:(BOOL)retained duped:(BOOL)duped mid:(UInt16)mid data:(NSData *)data;
232
233 /** gets called when the content of MQTTClients internal buffers change
234  use for monitoring the completion of transmitted and received messages
235  @param session the MQTTSession reporting the change
236  @param queued for backward compatibility only: MQTTClient does not queue messages anymore except during QoS protocol
237  @param flowingIn the number of incoming messages not acknowledged by the MQTTClient yet
238  @param flowingOut the number of outgoing messages not yet acknowledged by the MQTT broker
239  */
240 - (void)buffered:(MQTTSession *)session
241           queued:(NSUInteger)queued
242        flowingIn:(NSUInteger)flowingIn
243       flowingOut:(NSUInteger)flowingOut;
244
245 /** gets called when the content of MQTTClients internal buffers change
246  use for monitoring the completion of transmitted and received messages
247  @param session the MQTTSession reporting the change
248  @param flowingIn the number of incoming messages not acknowledged by the MQTTClient yet
249  @param flowingOut the number of outgoing messages not yet acknowledged by the MQTT broker
250  */
251 - (void)buffered:(MQTTSession *)session
252        flowingIn:(NSUInteger)flowingIn
253       flowingOut:(NSUInteger)flowingOut;
254
255 @end
256
257 typedef void (^MQTTConnectHandler)(NSError *error);
258 typedef void (^MQTTDisconnectHandler)(NSError *error);
259 typedef void (^MQTTSubscribeHandler)(NSError *error, NSArray<NSNumber *> *gQoss);
260 typedef void (^MQTTUnsubscribeHandler)(NSError *error);
261 typedef void (^MQTTPublishHandler)(NSError *error);
262
263 /** Session implements the MQTT protocol for your application
264  *
265  */
266
267 @interface MQTTSession : NSObject
268
269 /** set this member variable to receive delegate messages
270  @code
271  #import "MQTTClient.h"
272  
273  @interface MyClass : NSObject <MQTTSessionDelegate>
274  ...
275  @end
276  
277  ...
278  MQTTSession *session = [[MQTTSession alloc] init];
279  session.delegate = self;
280  ...
281  - (void)handleEvent:(MQTTSession *)session
282         event:(MQTTSessionEvent)eventCode
283         error:(NSError *)error {
284     ...
285  }
286  - (void)newMessage:(MQTTSession *)session
287         data:(NSData *)data
288         onTopic:(NSString *)topic
289         qos:(MQTTQosLevel)qos
290         retained:(BOOL)retained
291         mid:(unsigned int)mid {
292     ...
293  }
294  @endcode
295  
296  */
297 @property (weak, nonatomic) id<MQTTSessionDelegate> delegate;
298
299 /** Control MQTT persistence by setting the properties of persistence before connecting to an MQTT broker.
300     The settings are specific to a clientId.
301  
302     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
303         for this session.
304  
305     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
306         stored and transmitted later.
307  
308     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.
309  
310     persistence.maxMessages (a positive number, default is 1024) to limit the number of messages stored. Additional messages published are dropped.
311  
312     Messages are deleted after they have been acknowledged.
313 */
314 @property (strong, nonatomic) id<MQTTPersistence> persistence;
315
316 /** block called once when connection is established
317  */
318 @property (copy, nonatomic) MQTTConnectHandler connectHandler;
319
320 /** block called when connection is established
321  */
322 @property (strong) void (^connectionHandler)(MQTTSessionEvent event);
323
324 /** block called when message is received
325  */
326 @property (strong) void (^messageHandler)(NSData* message, NSString* topic);
327
328 /** Session status
329  */
330 @property (nonatomic, readonly) MQTTSessionStatus status;
331
332 /** Indicates if the broker found a persistent session when connecting with cleanSession:FALSE
333  */
334 @property (nonatomic, readonly) BOOL sessionPresent;
335
336 /** see initWithClientId for description
337  * @param clientId The Client Identifier identifies the Client to the Server. If nil, a random clientId is generated.
338
339  */
340 @property (strong, nonatomic) NSString *clientId;
341
342 /** see userName an NSString object containing the user's name (or ID) for authentication. May be nil. */
343 @property (strong, nonatomic) NSString *userName;
344
345 /** see password an NSString object containing the user's password. If userName is nil, password must be nil as well.*/
346 @property (strong, nonatomic) NSString *password;
347
348 /** see keepAliveInterval The Keep Alive is a time interval measured in seconds.
349  * The MQTTClient ensures that the interval between Control Packets being sent does not exceed
350  * the Keep Alive value. In the  absence of sending any other Control Packets, the Client sends a PINGREQ Packet.
351  */
352 @property (nonatomic) UInt16 keepAliveInterval;
353
354 /** leanSessionFlag specifies if the server should discard previous session information. */
355 @property (nonatomic) BOOL cleanSessionFlag;
356
357 /** willFlag If the Will Flag is set to YES this indicates that
358  * a Will Message MUST be published by the Server when the Server detects
359  * that the Client is disconnected for any reason other than the Client flowing a DISCONNECT Packet.
360  */
361 @property (nonatomic) BOOL willFlag;
362
363 /** willTopic If the Will Flag is set to YES, the Will Topic is a string, nil otherwise. */
364 @property (strong, nonatomic) NSString *willTopic;
365
366 /** willMsg If the Will Flag is set to YES the Will Message must be specified, nil otherwise. */
367 @property (strong, nonatomic) NSData *willMsg;
368
369 /** willQoS specifies the QoS level to be used when publishing the Will Message.
370  * If the Will Flag is set to NO, then the Will QoS MUST be set to 0.
371  * If the Will Flag is set to YES, the Will QoS MUST be a valid MQTTQosLevel.
372  */
373 @property (nonatomic) MQTTQosLevel willQoS;
374
375 /** willRetainFlag indicates if the server should publish the Will Messages with retainFlag.
376  * If the Will Flag is set to NO, then the Will Retain Flag MUST be set to NO .
377  * If the Will Flag is set to YES: If Will Retain is set to NO, the Serve
378  * MUST publish the Will Message as a non-retained publication [MQTT-3.1.2-14].
379  * If Will Retain is set to YES, the Server MUST publish the Will Message as a retained publication [MQTT-3.1.2-15].
380  */
381 @property (nonatomic) BOOL willRetainFlag;
382
383 /** protocolLevel specifies the protocol to be used */
384 @property (nonatomic) MQTTProtocolVersion protocolLevel;
385
386 /** runLoop The runLoop where the streams are scheduled. If nil, defaults to [NSRunLoop currentRunLoop]. */
387 @property (strong, nonatomic) NSRunLoop *runLoop;
388
389 /** runLoopMode The runLoopMode where the streams are scheduled. If nil, defaults to NSRunLoopCommonModes. */
390 @property (strong, nonatomic) NSString *runLoopMode;
391
392
393 /** The security policy used to evaluate server trust for secure connections.
394  * (see MQTTSSLSecurityPolicy.h for more detail).
395  */
396 @property (strong, nonatomic) MQTTSSLSecurityPolicy *securityPolicy;
397
398 /** for mqttio-OBJC backward compatibility
399  the connect message used is stored here
400  */
401 @property (strong, nonatomic) MQTTMessage *connectMessage;
402
403 /** the transport provider for MQTTClient
404  *
405  * assign an in instance of a class implementing the MQTTTransport protocol e.g.
406  * MQTTCFSocketTransport before connecting.
407  */
408 @property (strong, nonatomic) id <MQTTTransport> transport;
409
410 /** certificates an NSArray holding client certificates or nil */
411 @property (strong, nonatomic) NSArray *certificates;
412
413 /** connect to the given host through the given transport with the given
414  *  MQTT session parameters asynchronously
415  *
416  *  @exception NSInternalInconsistencyException if the parameters are invalid
417  *
418  */
419
420
421 - (void)connect;
422
423 /** connects to the specified MQTT server
424  
425  @param connectHandler identifies a block which is executed on successfull or unsuccessfull connect. Might be nil
426  error is nil in the case of a successful connect
427  sessionPresent indicates in MQTT 3.1.1 if persistent session data was present at the server
428  
429  @return nothing and returns immediately. To check the connect results, register as an MQTTSessionDelegate and
430  - watch for events
431  - watch for connect or connectionRefused messages
432  - watch for error messages
433  or use the connectHandler block
434  
435  @code
436  #import "MQTTClient.h"
437  
438  MQTTSession *session = [[MQTTSession alloc] init];
439  ...
440  [session connectWithConnectHandler:^(NSError *error, BOOL sessionPresent) {
441  if (error) {
442  NSLog(@"Error Connect %@", error.localizedDescription);
443  } else {
444  NSLog(@"Connected sessionPresent:%d", sessionPresent);
445  }
446  }];
447  @endcode
448  
449  */
450
451 - (void)connectWithConnectHandler:(MQTTConnectHandler)connectHandler;
452
453
454 /** disconnect gracefully
455  *
456  */
457 - (void)disconnect;
458
459 /** initialises the MQTT session with default values
460  @return the initialised MQTTSession object
461  @code
462  #import "MQTTClient.h"
463  
464  MQTTSession *session = [[MQTTSession alloc] init];
465  @endcode
466  */
467 - (MQTTSession *)init;
468
469
470
471 /** subscribes to a topic at a specific QoS level
472  
473  @param topic see subscribeToTopic:atLevel:subscribeHandler: for description
474  @param qosLevel  see subscribeToTopic:atLevel:subscribeHandler: for description
475  @return the Message Identifier of the SUBSCRIBE message.
476  
477  @note returns immediately. To check results, register as an MQTTSessionDelegate and watch for events.
478  
479  @code
480  #import "MQTTClient.h"
481  
482  MQTTSession *session = [[MQTTSession alloc] init];
483  ...
484  [session connect];
485  ...
486  [session subscribeToTopic:@"example/#" atLevel:2];
487  
488  @endcode
489  
490  */
491
492 - (UInt16)subscribeToTopic:(NSString *)topic atLevel:(MQTTQosLevel)qosLevel;
493 /** subscribes to a topic at a specific QoS level
494  
495  @param topic the Topic Filter to subscribe to.
496  
497  @param qosLevel specifies the QoS Level of the subscription.
498  qosLevel can be 0, 1, or 2.
499  @param subscribeHandler identifies a block which is executed on successfull or unsuccessfull subscription.
500  Might be nil. error is nil in the case of a successful subscription. In this case gQoss represents an
501  array of grantes Qos
502  
503  
504  @return the Message Identifier of the SUBSCRIBE message.
505  
506  @note returns immediately. To check results, register as an MQTTSessionDelegate and watch for events.
507  
508  @code
509  #import "MQTTClient.h"
510  
511  MQTTSession *session = [[MQTTSession alloc] init];
512  ...
513  [session connect];
514  ...
515  [session subscribeToTopic:@"example/#" atLevel:2 subscribeHandler:^(NSError *error, NSArray<NSNumber *> *gQoss){
516     if (error) {
517         NSLog(@"Subscription failed %@", error.localizedDescription);
518     } else {
519         NSLog(@"Subscription sucessfull! Granted Qos: %@", gQoss);
520     }
521  }];
522  
523  @endcode
524  
525  */
526
527 - (UInt16)subscribeToTopic:(NSString *)topic atLevel:(MQTTQosLevel)qosLevel subscribeHandler:(MQTTSubscribeHandler)subscribeHandler;
528
529 /** subscribes a number of topics
530  
531  @param topics an NSDictionary<NSString *, NSNumber *> containing the Topic Filters to subscribe to as keys and
532     the corresponding QoS as NSNumber values
533  
534  @return the Message Identifier of the SUBSCRIBE message.
535  
536  @note returns immediately. To check results, register as an MQTTSessionDelegate and watch for events.
537  
538  @code
539  #import "MQTTClient.h"
540  
541  MQTTSession *session = [[MQTTSession alloc] init];
542  ...
543  [session connect];
544  
545  [session subscribeToTopics:@{
546  @"example/#": @(0),
547  @"example/status": @(2),
548  @"other/#": @(1)
549  }];
550  
551  @endcode
552  */
553
554
555 - (UInt16)subscribeToTopics:(NSDictionary<NSString *, NSNumber *> *)topics;
556
557 /** subscribes a number of topics
558  
559  @param topics an NSDictionary<NSString *, NSNumber *> containing the Topic Filters to subscribe to as keys and
560     the corresponding QoS as NSNumber values
561  @param subscribeHandler identifies a block which is executed on successfull or unsuccessfull subscription.
562     Might be nil. error is nil in the case of a successful subscription. In this case gQoss represents an
563     array of grantes Qos
564  
565  @return the Message Identifier of the SUBSCRIBE message.
566  
567  @note returns immediately. To check results, register as an MQTTSessionDelegate and watch for events.
568  
569  @code
570  #import "MQTTClient.h"
571  
572  MQTTSession *session = [[MQTTSession alloc] init];
573  ...
574  [session connect];
575  
576  [session subscribeToTopics:@{
577     @"example/#": @(0),
578     @"example/status": @(2),
579     @"other/#": @(1)
580  } subscribeHandler:^(NSError *error, NSArray<NSNumber *> *gQoss){
581     if (error) {
582         NSLog(@"Subscription failed %@", error.localizedDescription);
583     } else {
584         NSLog(@"Subscription sucessfull! Granted Qos: %@", gQoss);
585     }
586  }];
587
588  
589  @endcode
590  */
591
592
593 - (UInt16)subscribeToTopics:(NSDictionary<NSString *, NSNumber *> *)topics subscribeHandler:(MQTTSubscribeHandler)subscribeHandler;
594
595 /** unsubscribes from a topic
596  
597  @param topic the Topic Filter to unsubscribe from.
598
599  @return the Message Identifier of the UNSUBSCRIBE message.
600  
601  @note returns immediately. To check results, register as an MQTTSessionDelegate and watch for events.
602  
603  @code
604  #import "MQTTClient.h"
605  
606  MQTTSession *session = [[MQTTSession alloc] init];
607  ...
608  [session connect];
609  
610  [session unsubscribeTopic:@"example/#"];
611  
612  @endcode
613  */
614
615 - (UInt16)unsubscribeTopic:(NSString *)topic;
616
617 /** unsubscribes from a topic
618  
619  @param topic the Topic Filter to unsubscribe from.
620  @param unsubscribeHandler identifies a block which is executed on successfull or unsuccessfull subscription.
621  Might be nil. error is nil in the case of a successful subscription. In this case gQoss represents an
622  array of grantes Qos
623  
624  @return the Message Identifier of the UNSUBSCRIBE message.
625  
626  @note returns immediately.
627  
628  */
629
630
631 - (UInt16)unsubscribeTopic:(NSString *)topic unsubscribeHandler:(MQTTUnsubscribeHandler)unsubscribeHandler;
632
633 /** unsubscribes from a number of topics
634  
635  @param topics an NSArray<NSString *> of topics to unsubscribe from
636  
637  @return the Message Identifier of the UNSUBSCRIBE message.
638  
639  @note returns immediately. To check results, register as an MQTTSessionDelegate and watch for events.
640  
641  @code
642  #import "MQTTClient.h"
643  
644  MQTTSession *session = [[MQTTSession alloc] init];
645  ...
646  [session connect];
647  
648  [session unsubscribeTopics:@[
649  @"example/#",
650  @"example/status",
651  @"other/#"
652  ]];
653  
654  @endcode
655  
656  */
657
658 - (UInt16)unsubscribeTopics:(NSArray<NSString *> *)topics;
659
660 /** unsubscribes from a number of topics
661  
662  @param topics an NSArray<NSString *> of topics to unsubscribe from
663  
664  @param unsubscribeHandler identifies a block which is executed on successfull or unsuccessfull subscription.
665     Might be nil. error is nil in the case of a successful subscription. In this case gQoss represents an
666     array of grantes Qos
667  
668  @return the Message Identifier of the UNSUBSCRIBE message.
669  
670  @note returns immediately.
671  
672  */
673 - (UInt16)unsubscribeTopics:(NSArray<NSString *> *)topics unsubscribeHandler:(MQTTUnsubscribeHandler)unsubscribeHandler;
674
675 /** publishes data on a given topic at a specified QoS level and retain flag
676  
677  @param data the data to be sent. length may range from 0 to 268,435,455 - 4 - _lengthof-topic_ bytes. Defaults to length 0.
678  @param topic the Topic to identify the data
679  @param retainFlag if YES, data is stored on the MQTT broker until overwritten by the next publish with retainFlag = YES
680  @param qos specifies the Quality of Service for the publish
681  qos can be 0, 1, or 2.
682  @return the Message Identifier of the PUBLISH message. Zero if qos 0. If qos 1 or 2, zero if message was dropped
683  
684  @note returns immediately. To check results, register as an MQTTSessionDelegate and watch for events.
685  
686  @code
687  #import "MQTTClient.h"
688  
689  MQTTSession *session = [[MQTTSession alloc] init];
690  ...
691  [session connect];
692  
693  [session publishData:[@"Sample Data" dataUsingEncoding:NSUTF8StringEncoding]
694  topic:@"example/data"
695  retain:YES
696  qos:1];
697  @endcode
698  
699  */
700
701 - (UInt16)publishData:(NSData *)data onTopic:(NSString *)topic retain:(BOOL)retainFlag qos:(MQTTQosLevel)qos;
702
703 /** publishes data on a given topic at a specified QoS level and retain flag
704  
705  @param data the data to be sent. length may range from 0 to 268,435,455 - 4 - _lengthof-topic_ bytes. Defaults to length 0.
706  @param topic the Topic to identify the data
707  @param retainFlag if YES, data is stored on the MQTT broker until overwritten by the next publish with retainFlag = YES
708  @param qos specifies the Quality of Service for the publish
709  qos can be 0, 1, or 2.
710  
711  
712  @param publishHandler identifies a block which is executed on successfull or unsuccessfull connect. Might be nil
713  error is nil in the case of a successful connect
714  sessionPresent indicates in MQTT 3.1.1 if persistent session data was present at the server
715  
716
717  @return the Message Identifier of the PUBLISH message. Zero if qos 0. If qos 1 or 2, zero if message was dropped
718  
719  @note returns immediately. To check results, register as an MQTTSessionDelegate and watch for events.
720  
721  @code
722  #import "MQTTClient.h"
723  
724  MQTTSession *session = [[MQTTSession alloc] init];
725  ...
726  [session connect];
727  
728  [session publishData:[@"Sample Data" dataUsingEncoding:NSUTF8StringEncoding]
729  topic:@"example/data"
730  retain:YES
731  qos:1
732  publishHandler:^(NSError *error){
733  if (error) {
734  DDLogVerbose(@"error: %@ %@", error.localizedDescription, payload);
735  } else {
736  DDLogVerbose(@"delivered:%@", payload);
737  delivered++;
738  }
739  }];
740  @endcode
741  
742  */
743
744 - (UInt16)publishData:(NSData *)data onTopic:(NSString *)topic retain:(BOOL)retainFlag qos:(MQTTQosLevel)qos publishHandler:(MQTTPublishHandler)publishHandler;
745
746 /** closes an MQTTSession gracefully
747  
748  If the connection was successfully established before, a DISCONNECT is sent.
749  
750  @param 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
751
752  @code
753  #import "MQTTClient.h"
754  
755  MQTTSession *session = [[MQTTSession alloc] init];
756  ...
757  [session connect];
758  
759  ...
760  
761  [session closeWithDisconnectHandler^(NSError *error) {
762     if (error) {
763         NSLog(@"Error Disconnect %@", error.localizedDescription);
764     }
765     NSLog(@"Session closed");
766  }];
767
768  
769  @endcode
770  
771  */
772 - (void)closeWithDisconnectHandler:(MQTTDisconnectHandler)disconnectHandler;
773
774 /** closes an MQTTSession gracefully
775   */
776 - (void)close;
777
778 @end