| commit | author | age | ||
| 2370e0 | 1 | // |
| H | 2 | // MQTTSessionManager.h |
| 3 | // MQTTClient | |
| 4 | // | |
| 5 | // Created by Christoph Krey on 09.07.14. | |
| 6 | // Copyright © 2013-2016 Christoph Krey. All rights reserved. | |
| 7 | // | |
| 8 | ||
| 9 | #import <Foundation/Foundation.h> | |
| 10 | #if TARGET_OS_IPHONE == 1 | |
| 11 | #import <UIKit/UIKit.h> | |
| 12 | #endif | |
| 13 | #import "MQTTSession.h" | |
| 14 | #import "MQTTSessionLegacy.h" | |
| 15 | #import "MQTTSSLSecurityPolicy.h" | |
| 16 | ||
| 17 | /** delegate gives your application access to received messages | |
| 18 | */ | |
| 19 | @protocol MQTTSessionManagerDelegate <NSObject> | |
| 20 | ||
| 21 | /** | |
| 22 | Enumeration of MQTTSessionManagerState values | |
| 23 | */ | |
| 24 | typedef NS_ENUM(int, MQTTSessionManagerState) { | |
| 25 | MQTTSessionManagerStateStarting, | |
| 26 | MQTTSessionManagerStateConnecting, | |
| 27 | MQTTSessionManagerStateError, | |
| 28 | MQTTSessionManagerStateConnected, | |
| 29 | MQTTSessionManagerStateClosing, | |
| 30 | MQTTSessionManagerStateClosed | |
| 31 | }; | |
| 32 | ||
| 33 | /** gets called when a new message was received | |
| 34 | @param data the data received, might be zero length | |
| 35 | @param topic the topic the data was published to | |
| 36 | @param retained indicates if the data retransmitted from server storage | |
| 37 | */ | |
| 38 | - (void)handleMessage:(NSData *)data onTopic:(NSString *)topic retained:(BOOL)retained; | |
| 39 | ||
| 40 | @optional | |
| 41 | ||
| 42 | /** gets called when a published message was actually delivered | |
| 43 | @param msgID the Message Identifier of the delivered message | |
| 44 | @note this method is called after a publish with qos 1 or 2 only | |
| 45 | */ | |
| 46 | - (void)messageDelivered:(UInt16)msgID; | |
| 47 | @end | |
| 48 | ||
| 49 | /** SessionManager handles the MQTT session for your application | |
| 50 | */ | |
| 51 | @interface MQTTSessionManager : NSObject <MQTTSessionDelegate> | |
| 52 | ||
| 53 | /** the delegate receiving incoming messages | |
| 54 | */ | |
| 55 | @property (weak, nonatomic) id<MQTTSessionManagerDelegate> delegate; | |
| 56 | ||
| 57 | /** subscriptions is a dictionary of NSNumber instances indicating the MQTTQoSLevel. | |
| 58 | * The keys are topic filters. | |
| 59 | * The SessionManager subscribes to the given subscriptions after successfull (re-)connect | |
| 60 | * according to the cleansession parameter and the state of the session as indicated by the broker. | |
| 61 | * Setting a new subscriptions dictionary initiates SUBSCRIBE or UNSUBSCRIBE messages by SessionManager | |
| 62 | * by comparing the old and new subscriptions. | |
| 63 | */ | |
| 64 | @property (strong, nonatomic) NSDictionary<NSString *, NSNumber *> *subscriptions; | |
| 65 | ||
| 66 | /** effectiveSubscriptions s a dictionary of NSNumber instances indicating the granted MQTTQoSLevel, or 0x80 for subscription failure. | |
| 67 | * The keys are topic filters. | |
| 68 | * effectiveSubscriptions is observable and is updated everytime subscriptions change | |
| 69 | * @code | |
| 70 | ... | |
| 71 | MQTTSessionManager *manager = [[MQTTSessionManager alloc] init]; | |
| 72 | manager.delegate = self; | |
| 73 | ||
| 74 | [manager addObserver:self | |
| 75 | forKeyPath:@"effectiveSubscriptions" | |
| 76 | options:NSKeyValueObservingOptionInitial | NSKeyValueObservingOptionNew | |
| 77 | context:nil]; | |
| 78 | manager.subscriptions = [@{@"#": @(0)} mutableCopy]; | |
| 79 | [manager connectTo: ... | |
| 80 | ... | |
| 81 | [manager removeObserver:self forKeyPath:@"effectiveSubscriptions"]; | |
| 82 | ... | |
| 83 | ||
| 84 | - (void)observeValueForKeyPath:(NSString *)keyPath | |
| 85 | ofObject:(id)object | |
| 86 | change:(NSDictionary<NSString *,id> *)change | |
| 87 | context:(void *)context { | |
| 88 | if ([keyPath isEqualToString:@"effectiveSubscriptions"]) { | |
| 89 | MQTTSessionManager *manager = (MQTTSessionManager *)object; | |
| 90 | DDLogVerbose(@"effectiveSubscriptions changed: %@", manager.effectiveSubscriptions); | |
| 91 | } | |
| 92 | } | |
| 93 | * @endcode | |
| 94 | */ | |
| 95 | @property (readonly, strong, nonatomic) NSDictionary<NSString *, NSNumber *> *effectiveSubscriptions; | |
| 96 | ||
| 97 | /** SessionManager status | |
| 98 | */ | |
| 99 | @property (nonatomic, readonly) MQTTSessionManagerState state; | |
| 100 | ||
| 101 | /** SessionManager last error code when state equals MQTTSessionManagerStateError | |
| 102 | */ | |
| 103 | @property (nonatomic, readonly) NSError *lastErrorCode; | |
| 104 | ||
| 105 | /** initWithPersistence sets the MQTTPersistence properties other than default | |
| 106 | * @param persistent YES or NO (default) to establish file or in memory persistence. | |
| 107 | * @param maxWindowSize (a positive number, default is 16) to control the number of messages sent before waiting for acknowledgement in Qos 1 or 2. Additional messages are stored and transmitted later. | |
| 108 | * @param 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. | |
| 109 | * @param maxMessages (a positive number, default is 1024) to limit the number of messages stored. Additional messages published are dropped. | |
| 110 | * @return the initialized MQTTSessionManager object | |
| 111 | */ | |
| 112 | ||
| 113 | - (MQTTSessionManager *)initWithPersistence:(BOOL)persistent | |
| 114 | maxWindowSize:(NSUInteger)maxWindowSize | |
| 115 | maxMessages:(NSUInteger)maxMessages | |
| 116 | maxSize:(NSUInteger)maxSize; | |
| 117 | ||
| 118 | /** Connects to the MQTT broker and stores the parameters for subsequent reconnects | |
| 119 | * @param host specifies the hostname or ip address to connect to. Defaults to @"localhost". | |
| 120 | * @param port specifies the port to connect to | |
| 121 | * @param tls specifies whether to use SSL or not | |
| 122 | * @param keepalive The Keep Alive is a time interval measured in seconds. The MQTTClient ensures that the interval between Control Packets being sent does not exceed the Keep Alive value. In the absence of sending any other Control Packets, the Client sends a PINGREQ Packet. | |
| 123 | * @param clean specifies if the server should discard previous session information. | |
| 124 | * @param auth specifies the user and pass parameters should be used for authenthication | |
| 125 | * @param user an NSString object containing the user's name (or ID) for authentication. May be nil. | |
| 126 | * @param pass an NSString object containing the user's password. If userName is nil, password must be nil as well. | |
| 127 | * @param will indicates whether a will shall be sent | |
| 128 | * @param willTopic the Will Topic is a string, may be nil | |
| 129 | * @param willMsg the Will Message, might be zero length or nil | |
| 130 | * @param willQos specifies the QoS level to be used when publishing the Will Message. | |
| 131 | * @param willRetainFlag indicates if the server should publish the Will Messages with retainFlag. | |
| 132 | * @param clientId The Client Identifier identifies the Client to the Server. If nil, a random clientId is generated. | |
| 133 | * @param securityPolicy A custom SSL security policy or nil. | |
| 134 | * @param certificates An NSArray of the pinned certificates to use or nil. | |
| 135 | * @param protocolLevel Protocol version of the connection. | |
| 136 | */ | |
| 137 | ||
| 138 | - (void)connectTo:(NSString *)host | |
| 139 | port:(NSInteger)port | |
| 140 | tls:(BOOL)tls | |
| 141 | keepalive:(NSInteger)keepalive | |
| 142 | clean:(BOOL)clean | |
| 143 | auth:(BOOL)auth | |
| 144 | user:(NSString *)user | |
| 145 | pass:(NSString *)pass | |
| 146 | will:(BOOL)will | |
| 147 | willTopic:(NSString *)willTopic | |
| 148 | willMsg:(NSData *)willMsg | |
| 149 | willQos:(MQTTQosLevel)willQos | |
| 150 | willRetainFlag:(BOOL)willRetainFlag | |
| 151 | withClientId:(NSString *)clientId | |
| 152 | securityPolicy:(MQTTSSLSecurityPolicy *)securityPolicy | |
| 153 | certificates:(NSArray *)certificates | |
| 154 | protocolLevel:(MQTTProtocolVersion)protocolLevel; | |
| 155 | ||
| 156 | ||
| 157 | /** Connects to the MQTT broker and stores the parameters for subsequent reconnects | |
| 158 | * @param host specifies the hostname or ip address to connect to. Defaults to @"localhost". | |
| 159 | * @param port specifies the port to connect to | |
| 160 | * @param tls specifies whether to use SSL or not | |
| 161 | * @param keepalive The Keep Alive is a time interval measured in seconds. The MQTTClient ensures that the interval between Control Packets being sent does not exceed the Keep Alive value. In the absence of sending any other Control Packets, the Client sends a PINGREQ Packet. | |
| 162 | * @param clean specifies if the server should discard previous session information. | |
| 163 | * @param auth specifies the user and pass parameters should be used for authenthication | |
| 164 | * @param user an NSString object containing the user's name (or ID) for authentication. May be nil. | |
| 165 | * @param pass an NSString object containing the user's password. If userName is nil, password must be nil as well. | |
| 166 | * @param will indicates whether a will shall be sent | |
| 167 | * @param willTopic the Will Topic is a string, may be nil | |
| 168 | * @param willMsg the Will Message, might be zero length or nil | |
| 169 | * @param willQos specifies the QoS level to be used when publishing the Will Message. | |
| 170 | * @param willRetainFlag indicates if the server should publish the Will Messages with retainFlag. | |
| 171 | * @param clientId The Client Identifier identifies the Client to the Server. If nil, a random clientId is generated. | |
| 172 | * @param securityPolicy A custom SSL security policy or nil. | |
| 173 | * @param certificates An NSArray of the pinned certificates to use or nil. | |
| 174 | */ | |
| 175 | ||
| 176 | - (void)connectTo:(NSString *)host | |
| 177 | port:(NSInteger)port | |
| 178 | tls:(BOOL)tls | |
| 179 | keepalive:(NSInteger)keepalive | |
| 180 | clean:(BOOL)clean | |
| 181 | auth:(BOOL)auth | |
| 182 | user:(NSString *)user | |
| 183 | pass:(NSString *)pass | |
| 184 | will:(BOOL)will | |
| 185 | willTopic:(NSString *)willTopic | |
| 186 | willMsg:(NSData *)willMsg | |
| 187 | willQos:(MQTTQosLevel)willQos | |
| 188 | willRetainFlag:(BOOL)willRetainFlag | |
| 189 | withClientId:(NSString *)clientId | |
| 190 | securityPolicy:(MQTTSSLSecurityPolicy *)securityPolicy | |
| 191 | certificates:(NSArray *)certificates; | |
| 192 | ||
| 193 | /** Convenience alternative to full paramter connectTo | |
| 194 | * @param host see connectTo description | |
| 195 | * @param port see connectTo description | |
| 196 | * @param tls see connectTo description | |
| 197 | * @param keepalive see connectTo description | |
| 198 | * @param clean see connectTo description | |
| 199 | * @param auth see connectTo description | |
| 200 | * @param user see connectTo description | |
| 201 | * @param pass see connectTo description | |
| 202 | * @param will see connectTo description | |
| 203 | * @param willTopic see connectTo description | |
| 204 | * @param willMsg see connectTo description | |
| 205 | * @param willQos see connectTo description | |
| 206 | * @param willRetainFlag see connectTo description | |
| 207 | * @param clientId see connectTo description | |
| 208 | */ | |
| 209 | ||
| 210 | - (void)connectTo:(NSString *)host | |
| 211 | port:(NSInteger)port | |
| 212 | tls:(BOOL)tls | |
| 213 | keepalive:(NSInteger)keepalive | |
| 214 | clean:(BOOL)clean | |
| 215 | auth:(BOOL)auth | |
| 216 | user:(NSString *)user | |
| 217 | pass:(NSString *)pass | |
| 218 | will:(BOOL)will | |
| 219 | willTopic:(NSString *)willTopic | |
| 220 | willMsg:(NSData *)willMsg | |
| 221 | willQos:(MQTTQosLevel)willQos | |
| 222 | willRetainFlag:(BOOL)willRetainFlag | |
| 223 | withClientId:(NSString *)clientId; | |
| 224 | ||
| 225 | /** Convenience alternative to full paramter connectTo | |
| 226 | * @param host see connectTo description | |
| 227 | * @param port see connectTo description | |
| 228 | * @param tls see connectTo description | |
| 229 | * @param keepalive see connectTo description | |
| 230 | * @param clean see connectTo description | |
| 231 | * @param auth see connectTo description | |
| 232 | * @param user see connectTo description | |
| 233 | * @param pass see connectTo description | |
| 234 | * @param willTopic the Will Topic is a string, must not be nil | |
| 235 | * @param will the Will Message, might be zero length | |
| 236 | * @param willQos see connectTo description | |
| 237 | * @param willRetainFlag see connectTo description | |
| 238 | * @param clientId see connectTo description | |
| 239 | */ | |
| 240 | ||
| 241 | - (void)connectTo:(NSString *)host | |
| 242 | port:(NSInteger)port | |
| 243 | tls:(BOOL)tls | |
| 244 | keepalive:(NSInteger)keepalive | |
| 245 | clean:(BOOL)clean | |
| 246 | auth:(BOOL)auth | |
| 247 | user:(NSString *)user | |
| 248 | pass:(NSString *)pass | |
| 249 | willTopic:(NSString *)willTopic | |
| 250 | will:(NSData *)will | |
| 251 | willQos:(MQTTQosLevel)willQos | |
| 252 | willRetainFlag:(BOOL)willRetainFlag | |
| 253 | withClientId:(NSString *)clientId; | |
| 254 | ||
| 255 | /** Re-Connects to the MQTT broker using the parameters for given in the connectTo method | |
| 256 | */ | |
| 257 | - (void)connectToLast; | |
| 258 | ||
| 259 | /** publishes data on a given topic at a specified QoS level and retain flag | |
| 260 | ||
| 261 | @param data the data to be sent. length may range from 0 to 268,435,455 - 4 - _lengthof-topic_ bytes. Defaults to length 0. | |
| 262 | @param topic the Topic to identify the data | |
| 263 | @param retainFlag if YES, data is stored on the MQTT broker until overwritten by the next publish with retainFlag = YES | |
| 264 | @param qos specifies the Quality of Service for the publish | |
| 265 | qos can be 0, 1, or 2. | |
| 266 | @return the Message Identifier of the PUBLISH message. Zero if qos 0. If qos 1 or 2, zero if message was dropped | |
| 267 | @note returns immediately. | |
| 268 | */ | |
| 269 | - (UInt16)sendData:(NSData *)data topic:(NSString *)topic qos:(MQTTQosLevel)qos retain:(BOOL)retainFlag; | |
| 270 | ||
| 271 | /** Disconnects gracefully from the MQTT broker | |
| 272 | */ | |
| 273 | - (void)disconnect; | |
| 274 | ||
| 275 | @end | |
