DEPRECATED: Diffusion iOS Classic API  5.9.4
 All Data Structures Files Functions Variables Enumerations Enumerator Properties Macros Pages
DFClient.h
Go to the documentation of this file.
1 /**
2  * \file DFClient.h
3  * \brief Defines the interfaces providing the main access to the Diffusion client library for iOS.
4  */
5 
6 // Created by dhudson on 22/05/2009 - Diffusion 5.9.4_01
7 // Copyright © 2009, 2015 Push Technology Ltd. All rights reserved.
8 
9 @class DFTransport;
10 
11 #import "DFConnectionDetails.h"
12 #import "DFClientDelegate.h"
13 #import "DFPingMessage.h"
14 #import "DFTopicMessage.h"
15 #import "DFTopicListenerDelegate.h"
16 #import "DFCredentials.h"
17 #import "DFServiceTopicHandler.h"
18 #import "DFPagedTopicHandler.h"
19 #import "DFPagedTopicDelegate.h"
20 #import "DFTopicNotifyTopicDelegate.h"
21 #import "DFTopicNotifyTopicHandler.h"
22 
23 /**
24  * The domain supplied with NSError objects created by the client library.
25  * Some errors generated by the client library will include an iOS-provided NSUnderlyingErrorKey in the error's userInfo dictionary.
26  */
27 extern NSString *const DFClientErrorDomain;
28 
29 /**
30  * The code supplied with NSError objects created by the client library.
31  * Objects conforming to DFClientDelegate that implement onConnectionFailedWithError: will see these codes.
32  */
33 typedef NS_ENUM(NSInteger, DFClientError) {
34  DFClientErrorConnectionFailed = 1, /**< Protocol negotiation with the Diffusion server failed upon initial connection. */
35  DFClientErrorConnectionLost = 2, /**< The connection to the Diffusion server was lost. */
36  DFClientErrorConnectionRejected = 3, /**< Connection to the Diffusion server was rejected. */
37  DFClientErrorCredentialsRejected = 4, /**< Connection to the Diffusion server was rejected due to invalid credentials being supplied. */
38  DFClientErrorTransportCouldNotBeCreated = 5, /**< A suitable client transport could not be created to communicate with the Diffusion server. */
39  DFClientErrorTransportFailed = 6, /*!< The client transport failed before or during communication with the Diffusion server. */
40 };
41 
42 /**
43  * The userInfo key supplied with some NSError objects by the client library when they represent an underlying NSException.
44  * The value associated with this key in the userInfo dictionary is an NSException object.
45  */
46 extern NSString *const DFClientUnderlyingExceptionKey;
47 
48 /**
49  * The main access to the Diffusion Client.
50  * An example would be to create a ConnectionDetails object and then call the connect method
51  * A DiffusionDelegate must be set on the ConnectionDetails object to receive any messages
52  */
53 
54 @interface DFClient : NSObject
55 
56 @property(nonatomic,readonly) BOOL isConnected; /**< YES if the client is connected to a Diffusion Server */
57 @property(nonatomic,readonly) BOOL isReconnected; /**< YES if the client is reconnected to a Diffusion Server */
58 @property(nonatomic,assign) BOOL isDebugging; /**< YES if the client should output debug diagnostics while interacting with Diffusion */
59 @property(nonatomic,readonly) NSString *clientID; /**< After the client has connected to Diffusion this contains the unique Client ID */
60 @property(nonatomic,strong) DFConnectionDetails *connectionDetails; /**< The DFConnectionDetails object that this client will use to connect to Diffusion */
61 @property(nonatomic,readonly) int serverProtocolVersion, clientProtocolVersion; /**< the protocol version for this client */
62 @property(nonatomic,weak) NSObject<DFClientDelegate> *delegate; /**< Delegate object to notify when interacting with Diffusion */
63 @property(nonatomic,readonly) NSTimeInterval lastInteraction; /**< Returns the time (in seconds since the epoch) of the last interaction (send or receive) with the server. Can be 0 if no interaction */
64 
65 /**
66  Close the connection
67  */
68 -(void) close;
69 
70 /**
71  Connect to Diffusion using the pre supplied ConnectionDetails
72  */
73 -(void) connect;
74 
75 /**
76  Reconnect to Diffusion and attempt to reestablish use of the previous session (if there is one)
77  */
78 -(void)reconnect;
79 
80 /**
81  * sends a ping to the connected Diffusion Server, this will result in a onPing(PingMessage) to be sent to the DFClientDelegate
82  * @return the timestamp string used
83  */
84 -(NSString *) ping;
85 
86 /**
87  * send a message to the Diffusion Server for the given topic
88  * @param topic the message topic
89  * @param message the message
90  */
91 -(void) send:(NSString *) topic message: (NSString *) message;
92 
93 /**
94  * send a TopicMessage to Diffusion
95  * @param aTopicMessage the TopicMessage to send
96  */
97 -(void) sendTopicMessage:(DFTopicMessage *) aTopicMessage;
98 
99 //DF_PRIVATE(-(void) sendTopicMessage:(DFTopicMessage *) aTopicMessage withMessageType:(char)type);
100 
101 
102 /**
103  * @param topicSet the topicSet to subscribe to
104  */
105 -(void) subscribe:(NSString *) topicSet;
106 
107 /**
108  * @param topicSet the topicSet to unsubscribe to
109  */
110 -(void) unsubscribe:(NSString *) topicSet;
111 
112 /**
113  * @param credentials send credentials to the server
114  */
115 -(void) sendCredentials:(DFCredentials *) credentials;
116 
117 /**
118  * @param delegate add a DFTopicListenerDelegate, if the delegate topic matches the message topic, then onMessage function is called. Idiomatic of Objective C this delegate is not retained.
119  */
120 -(void) addTopicListener:(__weak NSObject<DFTopicListenerDelegate>*) delegate;
121 
122 
123 /**
124  * @param delegate remove a DFTopicListenerDelegate
125  */
126 -(void) removeTopicListener:(NSObject<DFTopicListenerDelegate>*) delegate;
127 
128 /**
129  * Remove all topic listeners
130  */
132 
133 /**
134  * Get a read-only copy of the set of DFTopicListenerDelegate objects
135  */
136 -(NSArray*)topicListeners;
137 
138 
139 /**
140  * Issue a fetch request to the Diffusion server, for the given set of comma delimeted topic-names
141  * @param topicSet Name of the topic to fetch
142  * @throws DFException if the connected server implements less than protocol level 3
143  * @deprecated in favor of [fetch:error:]
144  */
145 -(void)fetch:(NSString *)topicSet __attribute__((deprecated));
146 
147 /**
148  * Issue a fetch request to the Diffusion server, for the given set of comma delimeted topic-names
149  * @param topicSet Name of the topic to fetch
150  * @param error set if the connected server implements less than protocol level 3
151  * @returns NO if the call failed
152  */
153 -(BOOL)fetch:(NSString *)topicSet error:(NSError*__autoreleasing *)error;
154 
155 /**
156  * Issue a fetch request to the Diffusion server, for the given set of comma delimeted topic-names.
157  * @param topicSet Name of the topic to fetch
158  * @param headers NSArray of NSString that will be relayed back from the server to aid request correlation
159  * @throws DFException if the connected server implements less than protocol level 3
160  * @deprecated in favor of [fetch:withCorrelation:error:]
161  */
162 -(void)fetch:(NSString *)topicSet withCorrelation:(NSArray*)headers __attribute__((deprecated));;
163 
164 /**
165  * Issue a fetch request to the Diffusion server, for the given set of comma delimeted topic-names.
166  * @param topicSet Name of the topic to fetch
167  * @param headers NSArray of NSString that will be relayed back from the server to aid request correlation
168  * @param error set if the connected server implements less than protocol level 3;
169  * @returns NO if the call failed
170  */
171 -(BOOL)fetch:(NSString *)topicSet withCorrelation:(NSArray*)headers error:(NSError*__autoreleasing*)error;
172 
173 /**
174  * Send a message acknowledgement back to the server. This will be required if autoAck is set to NO
175  * @param message message to acknowledge
176  */
177 -(void) acknowledge:(DFTopicMessage *) message;
178 
179 /**
180  * Create a new DFServiceTopicHandler
181  * @since 4.1
182  * @param message a service-topic-load message
183  * @param delegate an object that implements the DFServiceTopicDelegate protocol. Idiomatic of Objective C, this object is not retained.
184  * @return a newly created DFServiceTopicHandler or nil in case of error
185  *
186  * @throws DFException if the connected server implements less than protocol level 4
187  * @deprecated in favor of [createServiceTopicHandlerWithMessage:andDelegate:error]
188  */
189 -(DFServiceTopicHandler*)createServiceTopicHandlerWithMessage:(DFTopicMessage*)message
190  andDelegate:(__weak NSObject<DFServiceTopicDelegate>*)delegate;
191 
192 /**
193  * Create a new DFServiceTopicHandler
194  * @param message a service-topic-load message
195  * @param delegate an object that implements the DFServiceTopicDelegate protocol. Idiomatic of Objective C, this object is not retained.
196  * @param error populated in cases of error
197  * @return a newly created DFServiceTopicHandler or nil in case of error
198  *
199  * @since 4.6
200  */
201 -(DFServiceTopicHandler*)createServiceTopicHandlerWithMessage:(DFTopicMessage*)message
202  andDelegate:(__weak NSObject<DFServiceTopicDelegate>*)delegate
203  error:(NSError*__autoreleasing*)error;
204 
205 /**
206  * Creates a handler object for a 'paged' Topic.
207  *
208  * @since 4.1
209  * @param message the load message received from the Topic.
210  * @param delegate an object that is to receive all notifications from the topic. Idiomatic of Objective C, this object is not retained.
211  * @return the handler which may be used to send requests to the Topic.
212  *
213  * @throws DFException if the connected server implements less than protocol level 4
214  * @deprecated in favor of [createPagedTopicHandlerWithMessage:andDelegate:]
215  */
216 -(DFPagedTopicHandler*)createPagedTopicHandlerWithMessage:(DFTopicMessage*)message
217  andDelegate:(__weak NSObject<DFPagedTopicDelegate>*)delegate __attribute__((deprecated));
218 
219 /**
220  * Creates a handler object for a 'paged' Topic.
221  *
222  * @param message the load message received from the Topic.
223  * @param delegate an object that is to receive all notifications from the topic. Idiomatic of Objective C, this object is not retained.
224  * @param error populated in cases of error
225  *
226  * @return the handler which may be used to send requests to the Topic, or nil in case of error
227  *
228  * @since 4.6
229  */
230 -(DFPagedTopicHandler*)createPagedTopicHandlerWithMessage:(DFTopicMessage*)message
231  andDelegate:(__weak NSObject<DFPagedTopicDelegate>*)delegate
232  error:(NSError*__autoreleasing*)error;
233 
234 /**
235  * Creates a handler object for a 'Topic Notify' Topic.
236  *
237  * @param message the load message received from the Topic.
238  * @param delegate an object that is to receive all notifications from the Topic. Idiomatic of Objective C, this object is not retained.
239 
240  * @return the handler which may be used to send requests to the Topic.
241  * @throws DFException if unable to create the handler.
242  * @since 4.5
243  * @deprecated in favor of [createTopicNotifyTopicHandlerWithMessage:andDelegate:error:]
244  */
245 -(DFTopicNotifyTopicHandler*)createTopicNotifyTopicHandlerWithMessage:(DFTopicMessage*)message
246  andDelegate:(__weak NSObject<DFTopicNotifyTopicDelegate>*)delegate __attribute__((deprecated));;
247 
248 /**
249  * Creates a handler object for a 'Topic Notify' Topic.
250  *
251  * @param message the load message received from the Topic.
252  * @param delegate an object that is to receive all notifications from the Topic. Idiomatic of Objective C, this object is not retained.
253  * @param error populated in cases of error
254  * @return the handler which may be used to send requests to the Topic, or nil in case of error.
255  *
256  * @since 4.6
257  */
258 -(DFTopicNotifyTopicHandler*)createTopicNotifyTopicHandlerWithMessage:(DFTopicMessage*)message
259  andDelegate:(__weak NSObject<DFTopicNotifyTopicDelegate>*)delegate
260  error:(NSError*__autoreleasing*)error;
261 
262 
263 /**
264  * Dictionary of optional values used when establishing SSL/TLS encrypted connections.
265  * Make the iOS device overlook self signed certificates with this, for example...
266  * [[DFClient sslOptions] setObject:[NSNumber numberWithBool:YES] forKey:(NSString*)kCFStreamSSLAllowsAnyRoot];
267  */
268 +(NSMutableDictionary*)sslOptions;
269 
270 @end
271 
272 // ===================================
273 // Documentation for the front page
274 // ===================================
275 
276 
277 /*! \mainpage Diffusion client library for iOS devices
278 
279  \section Introduction
280 
281  This documentation covers the Diffusion client library for iOS devices, which is supplied as a static library with header files.
282 
283  \subsection SDKs Supported SDKs
284 
285  This version of the Diffusion client library for iOS devices supports between iOS v5.1.1 and v7.1 inclusively.
286 
287  \subsection CPUs Supported CPUs
288 
289  ARM CPUs armv7 and arm64, Bitcode is provided for both. Intel CPUs i386 and x86_64.
290 
291  \subsection Changes in v5.1
292 
293  This version of the Diffusion client library for iOS devices supports Diffusion over WebSockets and secure WebSockets.
294 
295  \subsection Dependencies
296 
297  The following are required by this library:
298  - libicucore.dylib
299  - libz.dylib
300  - CFNetwork.framework
301  - Foundation.framework
302  - Security.framework
303 
304  \subsection Acknowledgements
305 
306  This library depends on code from the following OSS libraries. Full details available in the Diffusion manual.
307 
308  - CocoaAsyncSocket v7.3.4 from https://github.com/robbiehanson/CocoaAsyncSocket
309  - SocketRocket v0.3.1-beta2 from http://github.com/square/SocketRocket
310 
311  */