Skip to main content
aboutsummaryrefslogtreecommitdiffstats
blob: cc6a7ccfbba7f75170d99044abf94a562b66b64c (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
/*******************************************************************************
 * Copyright (c) 2008, 2013 IBM Corp.
 *
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * and Eclipse Distribution License v1.0 which accompany this distribution. 
 *
 * The Eclipse Public License is available at 
 *    http://www.eclipse.org/legal/epl-v10.html
 * and the Eclipse Distribution License is available at 
 *   http://www.eclipse.org/org/documents/edl-v10.php.
 *
 * Contributors:
 *    Ian Craggs - initial API and implementation and/or initial documentation
 *******************************************************************************/

/**
 * 
 * 
 * Description : MQTT-S client API header file 
 * 
 * 
 * 
 * 
 * 
 */



#ifndef _MQTTS_APPLICATION_API_H
#define _MQTTS_APPLICATION_API_H

/**
 * ************** MQTT-S specific parameters    **/
#define MQTTS_VERSION "1.03"
/**
 * Maximum length of network address, e.g. 4 for ZigBee, 16 for IPv6, etc.
 * Note: it just defines a max value, i.e. 16 can also be used for ZigBee */
#define MQTTS_MAX_NETWORK_ADDRESS_LENGTH  4
/**
 * Maximum size for a mqtts message */
#define MQTTS_MAX_MSG_SIZE 60
/**
 * Default value of timers, delay periods, etc.
 * All time values are in seconds  */
/**
 * max number of ACKs missed before gw is declared to be lost */
#define MAX_ACK_MISSED 4  
/**
 * ack waiting time */
#define ACK_TIME 10 
/**
 * waiting time before sending a SEARCHGW */
#define SEARCHGW_MIN_DELAY 2 
/**
 * waiting time before sending a GWINFO */
#define GWINFO_MIN_DELAY 2  
/** 
 * Broadcast radius for SEARCHGW messages */
#define MQTTS_SEARCHGW_BROADCAST_RADIUS  1



/**
 * ********************* Return codes **************/
/**
 * protocol return codes (received from gw) */
#define MQTTS_RET_ACCEPTED          0x00
#define MQTTS_RET_CONGESTION        0x01
#define MQTTS_RET_INVALID_TOPIC_ID  0x02

/* local return codes */
#define MQTTS_OK                    0xF0
#define MQTTS_ERR_STACK_NOT_READY   0xF1
#define MQTTS_ERR_DATA_TOO_LONG     0xF2
#define MQTTS_LOST_GATEWAY          0xF3


/**
 ******************** MQTTS client's states ***************/
/**
 *  Client not active, needs be started with mqtts_startStack() */
#define MQTTS_STATE_NOT_ACTIVE          0x00
/* Client is active, but waits for mqtts_connect() to setup a connection */
#define MQTTS_STATE_WAITING_CONNECT     0x01
/* Client is searching for a gateway (or forwarder) */
#define MQTTS_STATE_SEARCHING_GW        0x02
/* Client has sent a CONNECT to a gw and is waiting for its response */
#define MQTTS_STATE_CONNECTING_TO_GW    0x03
/* Client is ready for sending request to gw */
#define MQTTS_STATE_READY               0x04
/* Client has sent a request to the gw and is waiting for an acknowledgment 
 * Note that client can only have one outstanding request at a time and
 * therefore does not accept any further app's request in this state */
#define MQTTS_STATE_WAITING_ACK         0x05
/* Client has sent a DISCONNECT to gw and is waiting for its response 
 * Client will return to state WAITING_CONNECT afterwards */
#define MQTTS_STATE_DISCONNECTING       0x06


/**
 ********************* Definition of structures **************/
/* CONNECT parameters structure */
typedef struct {
	/* flags */ 
	unsigned char flagCleanSession;
	unsigned char flagWill;
	unsigned char flagWillQOS;
	unsigned char flagWillRetain;

	/* fixed length parameters */
	unsigned char flpProtocolID;
	unsigned char flpDuration[2]; /* Keep Alive timer value */

	/* variable length parameters */
	unsigned char *vlpClientID;
	unsigned char  vlpClientID_length;
	unsigned char *vlpWillMsg;
	unsigned char  vlpWillMsg_length;
	unsigned char *vlpWillTopic;
	unsigned char  vlpWillTopic_length;

} mqtts_CONNECT_Parms;

/* WILLTOPICUPD parameters structure */
typedef struct {
	/* flags */ 
	unsigned char flagWillQOS;
	unsigned char flagWillRetain;

	/* variable length parameters */
	unsigned char *vlpWillTopic;
	unsigned char  vlpWillTopic_length;

} mqtts_WILLTOPICUPD_Parms;

/* WILLMSGUPD parameters structure */
typedef struct {
	unsigned char *vlpWillMsg;
	unsigned char  vlpWillMsg_length;
} mqtts_WILLMSGUPD_Parms;

/* REGISTER parameters structure */
typedef struct {
	/* variable length parameters */
	unsigned char *vlpTopic;
	unsigned char vlpTopic_length;
} mqtts_REGISTER_Parms;

/* PUBLISH parameters structure */
typedef struct {
	/* flags */ 
	/* DUP is set by mqtts when retransmitting the message */
	unsigned char flagQOS;
	unsigned char flagRetain;
	unsigned char flagTopicIdType;
	/* fixed length parameters */
	unsigned char flpTopicID[2];
	/* variable length parameters */
	unsigned char *vlpData;
	unsigned char vlpData_length;
} mqtts_PUBLISH_Parms;

/* SUBSCRIBE parameters structure */
typedef struct {
	/* flags */
	unsigned char flagQOS;
	unsigned char flagTopicIdType;
	/* variable length parameters: TopicName or TopicId */
	unsigned char *vlpTopic;
	unsigned char vlpTopic_length;
} mqtts_SUBSCRIBE_Parms;

/* UNSUBSCRIBE parameters structure */
typedef struct {
	/* flags */ 
	unsigned char flagTopicIdType;
	/* variable length parameters: TopicName or TopicId */
	unsigned char *vlpTopic;
	unsigned char vlpTopic_length;
} mqtts_UNSUBSCRIBE_Parms;


/*************************************************************  
 *                                          
 *               Functions provided by the mqtts client 
 * 
 * Functions that trigger a request to be sent to the gw/broker and
 * required a reply from the gw/broker are non-blocking, i.e. the client 
 * with return immediately after having sent the request to the gw/broker.
 * The gw/broker's response will then be indicated by the corresponding
 * call-back function.
 * 
 *************************************************************/

/**
    start the mqtts client: client will go to state WAITING_CONNECT
    and begin to process ADVERTISE and GWINFO, but it will wait for
    mqtts_connect() to initialize a connection to a gw

    Parameters : none

    Returns : none

 */
void mqtts_startStack(void);


/**
    stop the mqtts client:
    client will then ignore all messages and go to state "NOT_ACTIVE";
    app needs to re-issue mqtts_startStack()

    Parameters : none

    Returns : none

 */
void mqtts_stopStack(void);


/**
    request client to setup a connection to a gw
    client stack has to be already started (with mqtts_startStack() )

    Parameters : 
        pParms - pointer to a mqtts_CONNECT_Parms       
    Returns :
        MQTTS_ERR_STACK_NOT_READY
        MQTTS_ERR_DATA_TOO_LONG
        MQTTS_OK

 */
unsigned char mqtts_connect(mqtts_CONNECT_Parms *pParms);


/**
    request client to disconnect 
    client will wait again for mqtts_connect() to setup a connection

    Parameters : none

    Returns :
        MQTTS_ERR_STACK_NOT_READY
        MQTTS_OK

 */
unsigned char mqtts_disconnect(void);


/**
    request client to send a REGISTER message 
    only accepted if client state = READY 

    Parameters :
        pParms - pointer to a REGISTER parameter

    Returns :
        MQTTS_ERR_STACK_NOT_READY
        MQTTS_OK
 * 
 */
unsigned char mqtts_register(mqtts_REGISTER_Parms *pParms);



/**
    request client to send a PUBLISH message
    only accepted if client state = READY

    Parameters :
        pParms - pointer to a PUBLISH parameter

    Returns :
        MQTTS_ERR_STACK_NOT_READY
        MQTTS_OK

 */
unsigned char mqtts_publish(mqtts_PUBLISH_Parms *pParms);


/**
    request client to send a SUBSCRIBE message 
    only accepted if client state = READY

    Parameters :
        pParms - pointer to a SUBSCRIBE parameter

    Returns :
        MQTTS_ERR_STACK_NOT_READY
        MQTTS_OK

 */
unsigned char mqtts_subscribe(mqtts_SUBSCRIBE_Parms *pParms);


/**
    request client to send an UNSUBSCRIBE message 
    only accepted if client state = READY

    Parameters :
        pParms - pointer to a UNSUBSCRIBE parameter

    Returns :
        MQTTS_ERR_STACK_NOT_READY
        MQTTS_OK

 */
unsigned char mqtts_unsubscribe(mqtts_UNSUBSCRIBE_Parms *pParms);

/**
 * request client to send a WILLTOPICUPD message to update the Will topic
 * only accepted if client state = READY
 * 
 * Parameters:
 *     pParms - pointer to a WILLTOPIC parameter
 *              NULL to send an empty WILLTOPICUPD message (delete Will)
 * 
 * Returns :
 *    MQTTS_ERR_STACK_NOT_READY
 *    MQTTS_OK
 * 
 * 
 */
unsigned char mqtts_willtopic_update(mqtts_WILLTOPICUPD_Parms *pParms);

/**
 * request client to send a WILLMSGUPD message to update the Will message
 * only accepted if client state = READY
 * 
 * Parameters:
 *     pParms - pointer to WILLMSGUPD parameter
 * 
 * Returns :
 *    MQTTS_ERR_STACK_NOT_READY
 *    MQTTS_OK
 * 
 * 
 */
unsigned char mqtts_willmsg_update(mqtts_WILLMSGUPD_Parms *pParms);


/**
 * Request for client state
 * 
 * Inputs: none
 * 
 * Returns: client state
 * 			
 * 
 */
unsigned char mqtts_get_state(void);



/***************************************************                                                   
 *   callback functions (to be implemented by the app)    
 ****************************************************                                                      
 */

/* CONNECT sent to gw, client is waiting for gw's answer */
void mqttscb_connect_sent(void);

/* client is connected to a gw, app can now start publishing, ... */
void mqttscb_connected(void);

/* client is disconnected
 * 		reason: reason of disconnection */
void mqttscb_disconnected(unsigned char reason);

/* REGACK received, app can now use the indicated topicID for publishing */
void mqttscb_regack_received(
		unsigned char topicID_0,
		unsigned char topicID_1,
		unsigned char returnCode);

/* PUBLISH received from gw/broker 
 * app should return immediately either with 
 * MQTTS_RET_ACCEPTED or MQTTS_RET_INVALID_TOPIC_ID
 * before calling any other mqtts function */
unsigned char mqttscb_publish_received(
		unsigned char dup,
		unsigned char qos,
		unsigned char topicID_0, /* Topic ID[0] */
		unsigned char topicID_1, /* Topic ID[1] */
		unsigned char *data,
		unsigned char data_len);

/* PUBACK received */ 
void mqttscb_puback_received(
		unsigned char topicID_0, /* Topic ID[0] */
		unsigned char topicID_1, /* Topic ID[1] */
		unsigned char returnCode);

/* TODO QoS Level 2 not supported yet */
/* we only need to inform app with PUBCOMP */
/* PUBREC received (QoS 2) */
/* void mqttscb_pubrec_received(void); */
/* PUBCOMP received (QoS 2) */
void mqttscb_pubcomp_received(void);

/* SUBACK received */
void mqttscb_suback_received(
		unsigned char qos,
		unsigned char topicID_0,
		unsigned char topicID_1,
		unsigned char returnCode);

/* UNSUBACK received */
void mqttscb_unsuback_received(void);

/* REGISTER received from gw */
void mqttscb_register_received(
		unsigned char topicID_0, /* Topic ID[0] */
		unsigned char topicID_1, /* Topic ID[1] */
		unsigned char *topic,
		unsigned char topic_len);    

/* WILLTOPICRESP received from gw */
void mqttscb_willtopicresp_received(void);

/* WILLMSGRESP received from gw */
void mqttscb_willmsgresp_received(void);

#endif

Back to the top