DEPRECATED: Diffusion iOS Classic API  5.9.4
 All Data Structures Files Functions Variables Enumerations Enumerator Properties Macros Pages
DFCommon.h
Go to the documentation of this file.
1 /**
2  * \file DFCommon.h
3  * \brief Common constants, macros and enumerations
4  *
5  * Created by mcowie on 15/10/2010 - Diffusion 5.9.4_01
6  * Copyright © 2009, 2015 Push Technology Ltd. All rights reserved.
7  *
8  */
9 
10 /** Logging macro
11  * <p>
12  * Prints filename, function-name and line number, then the arguments, providing DEBUG is defined.
13  * @param fmt printf-style format string
14  */
15 #ifdef DEBUG
16 # define DLog(fmt, ...) NSLog((@"%s [Line %d] " fmt), __PRETTY_FUNCTION__, __LINE__, ##__VA_ARGS__)
17 #else
18 # define DLog(fmt, ...)
19 #endif
20 
21 #define DF_PRIVATE(...) __VA_ARGS__
22 #define DF_PRIVATE_FILE /* nothing */
23 
24 #define K 1024
25 
26 #define DIFFUSION_MESSAGE_TYPE_INITIAL_TOPIC_LOAD 20
27 #define DIFFUSION_MESSAGE_TYPE_DELTA 21
28 #define DIFFUSION_MESSAGE_TYPE_SUBSCRIBE 22
29 #define DIFFUSION_MESSAGE_TYPE_UNSUBSCRIBE 23
30 #define DIFFUSION_MESSAGE_TYPE_SERVER_PING 24
31 #define DIFFUSION_MESSAGE_TYPE_CLIENT_PING 25
32 #define DIFUFSION_MESSAGE_TYPE_SEND_CREDS 26
33 #define DIFFUSION_MESSAGE_TYPE_REJECTED_CREDS 27
34 #define DIFFUSION_MESSAGE_TYPE_CLIENT_ABORT 28
35 #define DIFFUSION_MESSAGE_TYPE_LOST_CONNECTION 29 // "Close request" from the manual.
36 #define DIFFUSION_MESSAGE_TYPE_ITL_REQ_ACK 30
37 #define DIFFUSION_MESSAGE_TYPE_DELTA_REQ_ACK 31
38 #define DIFFUSION_MESSAGE_TYPE_ACK_RESPONSE 32
39 #define DIFFUSION_MESSAGE_TYPE_FETCH 33
40 #define DIFFUSION_MESSAGE_TYPE_FETCH_RESPONSE 34
41 #define DIFFUSION_MESSAGE_TYPE_TOPIC_STATUS_NOTIFICATION 35
42 
43 // Service/command messages - v4 feature
44 #define DIFFUSION_MESSAGE_TYPE_COMMAND 36
45 #define DIFFUSION_MESSAGE_TYPE_COMMAND_TOPIC_LOAD 40
46 #define DIFFUSION_MESSAGE_TYPE_COMMAND_NOTIFICATION 41
47 
48 #define DIFFUSION_MESSAGE_ENCODING_NONE_ENCODING 0
49 #define DIFFUSION_MESSAGE_ENCODING_ENCRYPTED_ENCODING 17
50 #define DIFFUSION_MESSAGE_ENCODING_COMPRESSED_ENCODING 18
51 #define DIFFUSION_MESSAGE_ENCODING_BASE64_ENCODING 19
52 
53 #define DIFFUSION_MESSAGE_ENCODING_ENCRYPTED_REQUESTED 1
54 #define DIFFUSION_MESSAGE_ENCODING_COMPRESSED_REQUESTED 2
55 #define DIFFUSION_MESSAGE_ENCODING_BASE64_REQUESTED 3
56 
57 #define MD "\x00"
58 #define MD_CHAR 0
59 
60 #define RD "\x01"
61 #define RD_CHAR 1
62 
63 #define FD "\x02"
64 #define FD_CHAR 2
65 
66 /**
67  * The protocols currently supported
68  */
69 #define WS @"ws" // WebSocket
70 #define WSS @"wss" // Secure WebSocket
71 #define DPT @"dpt" // Diffusion Protocol over TCP
72 #define DPTS @"dpts" // Secure Diffusion Protocol over TCP
73 
75 
76 @end
77 
78 @interface NSArray (DFCommon)
79 
80 @end
81 
82 /**
83  * Specifies the mode when selecting topic ranges for notification
84  * @since 4.6
85  */
86 typedef enum {
87  DSM_ADD, /**< This indicates that the specified set of topic names and/or selectors should be added to any existing selection */
88  DSM_REPLACE, /**< This indicates that the specified set of topic names and/or selectors should replace any current selections */
89  DSM_REMOVE, /**< Specifies that the specified set of topic names and/or selectors should be removed from the current set of selections. Only string values that exactly match previously set selectors will be removed */
90  DSM_CLEAR /**< Specifies that all current selections should be removed */
92 
93 
94 /**
95  * Specifies the level of notification that the client wishes to receive.
96  * @since 4.6
97  */
98 typedef enum {
99  DNL_MINIMUM, /**< The minimum level of notification that can be received which will simply notify the topic name and its type */
100  DNL_PROPERTIES, /**< This level of notification is the same as DNL_MINIMUM plus all properties of the Topic. See DFTopicProperty and DFTopicDefinition. */
101  DNL_METADATA, /**< This level of notification is the same as DNL_MINIMUM plus any metadata associated with the Topic. */
102  DNL_FULL, /**< The level of notification provides all details of the Topic and would be the level needed in order to replicate the Topic. This is equivalent to DNL_MINIMUM plus DNL_PROPERTIES plus DNL_METADATA. */
103  DNL_NONE /**< This special setting may be used to indicate that add notifications are not required */
105 
106 
107 /**
108  * Defines the type of an instance of TopicData
109  * @since 4.6
110  */
111 typedef enum {
112  DTDT_ERROR_ENUM = -1, /** Error parsing the TopicData type */
113  DTDT_NONE = 0, /**< No Topic Data. This special type is used to represent a Topic that has no Topic Data. */
114  DTDT_SINGLE_VALUE, /**< Single Value Format. Publishing Topic Data of type SingleValueTopicData. */
115  DTDT_RECORD, /**< Diffusion Record Format. Publishing Topic Data of type RecordTopicData.*/
116  DTDT_PROTOCOL_BUFFER, /**< Protocol Buffers (from Google). Publishing Data of type PBTopicData. */
117  DTDT_CUSTOM, /**< Custom. Publishing Topic Data of type CustomTopicData. */
118  DTDT_SLAVE, /**< Slave Topic Data. Publishing Topic Data of type SlaveTopicData */
119  DTDT_SERVICE, /**< Service Topic Data. Functional Command Topic Data of type ServiceTopicData */
120  DTDT_PAGED_STRING, /**< Paged String Value Topic Data. Functional Command Topic Data of type PagedStringTopicData */
121  DTDT_PAGED_RECORD, /**< Paged Record Topic Data. Functional Command Topic Data of type PagedRecordTopicData */
122  DTDT_TOPIC_NOTIFY, /**< Topic Notify Topic Data. Functional Command Topic Data of type TopicNotifyTopicData */
123  DTDT_ROUTING, /**< Routing Topic Data. Functional Topic Data of type RoutingTopicData */
124  DTDT_CHILD_LIST, /**< Child Topics List. Functional Topic Data of type ChildListTopicData. */
125  DTDT_REMOTE_CONTROL, /**< Remote Control Topic Data. Functional Topic Data of type RemoteControlTopicDataEdge */
126  DTDT_REMOTE_SERVICE, /**< Remote Service Topic Data. Functional Topic Data of type RemoteServiceTopicData in an Edge role. */
127  DTDT_REMOTE_CONTROL_RELAY, /**< Remote Control Topic Data in the relay tier. Functional Topic Data of type RemoteControlTopicDataRelay */
128  DTDT_REMOTE_SERVICE_RELAY /**< Remote Service Topic Data in the relay tier. Functional Topic Data of type RemoteServiceTopicData in a relay role. */
130 
131 
132 
133 
134 /**
135  * Specifies Topic Property keys that may be used in the DFTopicDefinition properties field.
136  *
137  * @since 4.6
138  */
139 typedef enum {
140  DTP_ALIASING, /**< Specifies whether the Topic should use Topic Aliasing.
141  * This is an optional Boolean property and if not specified then the
142  * aliasing requirement will be taken from the Publisher. */
143 
144  DTP_ATTACHMENT, /**< This property defines the topic attachment.
145  * This is an optional Object to be attached to the topic. */
146 
147  DTP_ATTACHMENT_CLASS,/**< This property defines the a Topic attachment class.
148  * This is an optional String property specifying a full class name.
149  * If specified then the no arguments constructor of the class will be used
150  * to create an instance of the class and attach it to the topic.
151  * This property would be ignored if DTP_ATTACHMENT is specified. */
152  DTP_CUSTOM_HANDLER, /**< Specifies a Custom Topic Handler.
153  * <P>
154  * This is used with Topics of type DTP_CUSTOM but would
155  * be ignored for all other types.
156  * <P>
157  * It is an Object property where the object must be of type
158  * CustomTopicDataHandler. */
159  DTP_CUSTOM_HANDLER_CLASS, /**< Specifies a Custom Topic Handler.
160  * <P>
161  * This is used with Topics of type DTP_CUSTOM but would
162  * be ignored for all other types.
163  * <P>
164  * This is a String property specifying a loadable class of type
165  * CustomTopicDataHandler which must have a no arguments constructor
166  * which will be used to create an instance of the handler when the Topic is
167  * created.
168  * <P>
169  * This is ignored if DTP_CUSTOM_HANDLER is specified.
170  * <P>
171  * To create a Topic of type CUSTOM either this
172  * property or CUSTOM_HANDLER must be supplied. */
173 
174  DTP_DATA_INITIALISER, /**< Specifies a Topic Data Initialiser.
175  * <P>
176  * This is used with Topics of type PublishingTopicData but would
177  * be ignored for all other types.
178  * <P>
179  * This is an Object property of type TopicDataInitialiser.
180  * <P>
181  * This is ignored if DTP_DATA_INITIALISER is specified. */
182 
183  DTP_DATA_INITIALISER_CLASS, /**< Specifies a Topic Data Initialiser class.
184  * <P>
185  * This is used with Topics of type PublishingTopicData but would
186  * be ignored for all other types.
187  * <P>
188  * This is a String property specifying a loadable class of type
189  * TopicDataInitialiser which must have a no arguments constructor
190  * which will be used to create an instance of the handler when the Topic is
191  * created.
192  * <P>
193  * This is ignored if DTP_DATA_INITIALISER is specified. */
194  DTP_DELTA_ACK_REQUIRED, /**< Specifies that delta messages require acknowledgment.
195  * <P>
196  * This is an optional Boolean property that only applies to Topics that
197  * have data of type PublishingTopicData. */
198  DTP_DELTA_ENCODING, /**< Delta Encoding.
199  * <P>
200  * This is an optional Byte value. The value must be one of the
201  * DFEncoding values.
202  */
203  DTP_DELTA_MESSAGE_CAPACITY, /**< Specifies the default delta message capacity.
204  * <P>
205  * This is an optional Integer property. */
206  DTP_DOMAIN_TOPIC_NAME, /**< Domain Topic Name.
207  * <P>
208  * This indicates that the Topic is a subdomain of the specified Topic
209  * which is a Remote Control Service Topic DTP_REMOTE_SERVICE.
210  * <P>
211  * This is not a supported property when creating a Topic but will be
212  * returned in any DFTopicDefinition returned from such a Topic.
213  */
214  DTP_INTROSPECTION_MASK, /**< Introspection mask.
215  * <P>
216  * This is optional Byte property. */
217  DTP_LOAD_ACK_REQUIRED, /**< Specifies that load messages require acknowledgment.
218  * <P>
219  * This is an optional Boolean property that only applies to Topics that
220  * have data of type PublishingTopicData. */
221 
222  DTP_LOAD_ENCODING, /**< Load Encoding.
223  * <P>
224  * This is an optional Byte property. The value must be one of the DFEncoding values. */
225 
226  DTP_LOAD_HEADERS, /**< Specifies headers to be associated with load messages.
227  * <P>
228  * This is an optional String property that only applies to Topics that have
229  * data of type PublishingTopicData. */
230 
231  DTP_LOAD_MESSAGE_CAPACITY, /**< Specifies the default load message capacity.
232  * <P>
233  * This is an optional Integer property. */
234 
235  DTP_LOCKABLE, /**< Indicates whether the topic is lockable.
236  * <P>
237  * This is an optional Boolean property.
238  * <P>
239  * This only applies to a Topic of type TopicDataType.NONE and if
240  * not specified then 'YES' would be assumed. */
241 
242  DTP_LOCK_TIMEOUT, /**< Lock timeout.
243  * <P>
244  * This is an optional Long property.*/
245 
246  DTP_NOTIFY_ALL_TOPICS, /**< Specifies whether a Topic Notify Topic notifies all Topics or only
247  * those owned by the same Publisher as the notifier.
248  * <P>
249  * This is an optional Boolean property which applies only to Topics of type
250  * DTP_TOPIC_NOTIFY}. */
251 
252  DTP_NOTIFY_METADATA_CACHING, /**< Specifies whether a Topic Notify Topic supports metadata caching.
253  * <P>
254  * This is an Optional boolean property which applies only to Topics of type
255  * DTP_TOPIC_NOTIFY */
256 
257  DTP_PAGED_COMPARATOR, /**< Specifies a Paged Topic Comparator.
258  * <P>
259  * This may optionally be used with Topics of type DTP_PAGED_RECORD or DTP_PAGED_STRING but would
260  * be ignored for all other types.
261  * <P>
262  * It is an Object property where the object must be of type
263  * Comparator with a generic type of either Record or
264  * String depending on Topic Data type.
265  * <P>
266  * If a comparator is specified then the Topic Data will be ordered using
267  * the comparator. */
268 
269 
270  DTP_PAGED_COMPARATOR_CLASS, /**< Specifies a Paged Topic Comparator class.
271  * <P>
272  * This may optionally be used with Topics of type
273  * DTP_PAGED_RECORD or DTP_PAGED_STRING but would
274  * be ignored for all other types.
275  * <P>
276  * This is a String property specifying a loadable class of type
277  * Comparator which must have a no arguments constructor
278  * which will be used to create an instance of the handler when the Topic is
279  * created. The comparator should have a generic type of either
280  * Record or String depending on Topic Data type.
281  * <P>
282  * This is ignored if DTP_PAGED_COMPARATOR is specified.
283  * <P>
284  * If a comparator is specified then the Topic Data will be ordered using
285  * the comparator. */
286 
287  DTP_PAGED_DUPLICATES_POLICY, /**< Specifies Paged Topic Data Duplicates Policy.
288  * <P>
289  * This is an optional property that only has meaning for Topics that have
290  * data of type DTP_PAGED_RECORD or DTP_PAGED_STRING. It is ignored for all other types.
291  * <P>
292  * It is a String property that may be one of the update mode code values
293  * as obtained from Duplicates.getCode().
294  * <P>
295  * If not specified then Duplicates.NOT_ALLOWED is assumed. */
296 
297  DTP_PB_CLASS, /**< Specifies a Protocol Buffer proto class name.
298  * <P>
299  * This is a String property that that is mandatory for Topics that have
300  * data of type DTDT_PROTOCOL_BUFFER. It is ignored for all
301  * other types. */
302 
303  DTP_PB_DELETION_VALUE, /**< Specifies the Protocol Buffers Topic Data Deletion Value.
304  * <P>
305  * This is an optional property that only has meaning for Topics that have
306  * data of type DTDT_PROTOCOL_BUFFER. It is ignored for all
307  * other types.
308  * <P>
309  * It is a String property that specifies a value used to represent field
310  * deletions.
311  * <P>
312  * If not specified then PBTopicData.DEFAULT_DELETION_VALUE is assumed. */
313 
314  DTP_PB_NAME, /**< Specifies a Protocol Buffers Message name.
315  * <P>
316  * This is a String property that is mandatory for Topics that have
317  * data of type DTDT_PROTOCOL_BUFFER. It is ignored for all
318  * other types. */
319 
320  DTP_PB_UPDATE_MODE, /**< Specifies the Protocol Buffers Topic Data Update Mode.
321  * <P>
322  * This is an optional property that only has meaning for Topics that have
323  * data of type DTDT_PROTOCOL_BUFFER. It is ignored for all
324  * other types.
325  * <P>
326  * It is a String property that may be one of the update mode code values
327  * as obtained from UpdateMode.getCode().
328  * <P>
329  * If not specified then UpdateMode.PARTIAL is assumed.
330  * <P>
331  * See PBTopicData.setUpdateMode(UpdateMode) for more details. */
332 
333  DTP_RECORD_EMPTY_FIELD_VALUE, /**< Specifies a value to use to represent empty fields.
334  * <P>
335  * This is an optional String property for use with Topics of type
336  * DTDT_RECORD and would be ignored for all other types.
337  * <P>
338  * See RecordTopicData.setEmptyFieldValue(String) for details. */
339 
340  DTP_REFERENCE, /**< This specifies the Topic reference.
341  * <P>
342  * This is an optional String property. */
343 
344  DTP_ROUTING_HANDLER, /**< Specifies a Routing Topic Subscription Handler.
345  * <P>
346  * This is an Object property used with Topics of type
347  * DTDT_ROUTING and would be ignored for all other types.
348  * The object specified must be of type
349  * RoutingTopicDataSubscriptionHandler.
350  * <P>
351  * To create a Topic of type opicDataType.ROUTING either this
352  * property or DTP_ROUTING_HANDLER must be supplied. */
353 
354  DTP_ROUTING_HANDLER_CLASS, /**< Specifies a Routing Topic Subscription Handler.
355  * <P>
356  * This is a String property used with Topics of type
357  * DTDT_ROUTING and would be ignored for all other types.
358  * It specifies a loadable class of type
359  * RoutingTopicDataSubscriptionHandler which must have a no
360  * arguments constructor which that be used to create an instance of the
361  * handler to attach to the Topic.
362  * <P>
363  * This will be ignored if DTP_ROUTING_HANDLER is specified.
364  * <P>
365  * To create a Topic of type DTDT_ROUTING either this
366  * property or DTP_ROUTING_HANDLER must be supplied. */
367 
368  DTP_SERVICE_HANDLER, /**< Specifies a Service handler.
369  * <P>
370  * This is an Object property which only applies to Topics of type
371  * DTDT_SERVICE and would be ignored for all other types.
372  * The object specified must be of type ServiceHandler.
373  * <P>
374  * To create a Topic of type DTDT_SERVICE either this
375  * property or DTP_SERVICE_HANDLER must be supplied. */
376 
377  DTP_SERVICE_HANDLER_CLASS, /**< Specifies a Service handler.
378  * <P>
379  * This is a String property which only applies to Topics of type
380  * DTDT_SERVICE and would be ignored for all other types.
381  * It specifies a loadable class of type ServiceHandler which must
382  * have a no arguments constructor which will be used to create an instance
383  * of the handler to attach to the Topic.
384  * <P>
385  * This is ignored is DTP_SERVICE_HANDLER is specified.
386  * <P>
387  * To create a Topic of type TopicDataType.SERVICE either this
388  * property or DTP_SERVICE_HANDLER must be supplied. */
389 
390  DTP_SERVICE_HEADERS, /**< Specifies service header options.
391  * <P>
392  * This is an optional String property that only applies for Topics of type
393  * DTDT_SERVICE and would be ignored for all other types. */
394 
395  DTP_SERVICE_TARGET_TOPIC, /**< Specifies a service target topic name.
396  * <P>
397  * This is an optional String property that only applies to Topics of type
398  * DTDT_SERVICE and would be ignored for all other types. */
399 
400  DTP_SERVICE_TIMEOUT, /**< Specifies a service request timeout.
401  * <P>
402  * This is an optional Long property only applies for Topics of type
403  * DTDT_SERVICE and would be ignored for all other types. */
404 
405  DTP_SERVICE_TYPE, /**< Specifies Service Type.
406  * <P>
407  * This is a mandatory String property for Topics of type
408  * DTDT_SERVICE and is ignored for all other types. */
409 
410  DTP_SLAVE_MASTER_TOPIC, /**< Specifies the master Topic name for a Slave Topic.
411  * <P>
412  * This is a mandatory String property for topics of type
413  * DTDT_SLAVE and will be ignored for all other types. */
414 
415  DTP_SUBSCRIPTION_HANDLER, /**< Specifies a Subscription Handler.
416  * <P>
417  * This is an optional String property specifying the full name of a
418  * loadable class of type TopicSubscriptionHandler.
419  * <P>
420  * If specified then the class must have a no arguments constructor which
421  * will be used to create and associate the handler object when the topic is
422  * created.
423  * <P>
424  * This is ignored if DTP_SUBSCRIPTION_HANDLER is specified. */
425 
426  DTP_SUBSCRIPTION_HANDLER_CLASS, /**< Specifies a Subscription Handler.
427  * <P>
428  * This is an optional String property specifying the full name of a
429  * loadable class of type TopicSubscriptionHandler.
430  * <P>
431  * If specified then the class must have a no arguments constructor which
432  * will be used to create and associate the handler object when the topic is
433  * created.
434  * <P>
435  * This is ignored if DTP_SUBSCRIPTION_HANDLER is specified. */
436 
437  DTP_TIDY_ON_UNSUBSCRIBE /**< Tidy on Unsubscribe.
438  * <P>
439  * This is optional Boolean property. */
440 
442 
443 
444 
445 /**
446  * Error domain key used when populating NSError objects
447  */
448 #define DIFFUSION_ERROR_DOMAIN @"Diffusion"
449 
450 /**
451  * Diffusion version string constant
452  */
453 extern const char *transportVersion;
454