| commit | author | age | ||
| 2370e0 | 1 | // |
| H | 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 | |
