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 |