Annotation of mqtt/inc/aitmqtt.h, revision 1.1.1.1.2.29
1.1 misho 1: #ifndef __AITMQTT_H
2: #define __AITMQTT_H
3:
4:
1.1.1.1.2.4 misho 5: /* FIXED HEADER */
1.1.1.1.2.3 misho 6:
1.1.1.1.2.1 misho 7: struct mqtthdr {
1.1.1.1.2.17 misho 8: union {
9: struct {
10: unsigned char retain:1,
11: qos:2,
12: dup:1,
13: type:4;
14: };
1.1.1.1.2.19 misho 15: unsigned char val;
1.1.1.1.2.4 misho 16: } mqtt_msg;
1.1.1.1.2.19 misho 17: unsigned char mqtt_len[1]; /* may be grow to 4 bytes */
1.1.1.1.2.4 misho 18: } __packed;
1.1.1.1.2.17 misho 19: #define MQTTHDR_MSGINIT(x) (assert((x)), (x)->mqtt_msg.val ^= (x)->mqtt_msg.val)
1.1.1.1.2.1 misho 20:
1.1.1.1.2.21 misho 21: #define MQTT_TYPE_UNKNOWN 0 /* reserved */
22: #define MQTT_TYPE_CONNECT 1 /* client request to connect to server */
23: #define MQTT_TYPE_CONNACK 2 /* connect acknowledgment */
24: #define MQTT_TYPE_PUBLISH 3 /* publish message */
25: #define MQTT_TYPE_PUBACK 4 /* publish acknowledgment */
26: #define MQTT_TYPE_PUBREC 5 /* publish received (assured delivery part 1) */
27: #define MQTT_TYPE_PUBREL 6 /* publish release (assured delivery part 2) */
28: #define MQTT_TYPE_PUBCOMP 7 /* publish complete (assured delivery part 3) */
29: #define MQTT_TYPE_SUBSCRIBE 8 /* client subscribe request */
30: #define MQTT_TYPE_SUBACK 9 /* subscribe acknowledgment */
31: #define MQTT_TYPE_UNSUBSCRIBE 10 /* client unsubscribe request */
32: #define MQTT_TYPE_UNSUBACK 11 /* unsubscribe acknowledgment */
33: #define MQTT_TYPE_PINGREQ 12 /* PING request */
34: #define MQTT_TYPE_PINGRESP 13 /* PING response */
35: #define MQTT_TYPE_DISCONNECT 14 /* client is disconnecting */
36: #define MQTT_TYPE_MAX 15 /* reserved */
37:
1.1.1.1.2.1 misho 38: #define MQTT_FLAG_DUP 1 /* This flag is set when the client or server attempts to re-deliver
39: a PUBLISH, PUBREL, SUBSCRIBE or UNSUBSCRIBE message.
40: This applies to messages where the value of QoS is greater than
41: zero (0), and an acknowledgment is required.
42: When the DUP bit is set, the variable header includes a Message ID.
43:
44: The recipient should treat this flag as a hint as to whether
45: the message may have been previously received.
46: It should not be relied on to detect duplicates. */
47:
48: #define MQTT_QOS_ONCE 0 /* At most once, Fire and Forget, <=1 */
49: #define MQTT_QOS_ACK 1 /* At least once, Acknowledged delivery, >=1 */
50: #define MQTT_QOS_EXACTLY 2 /* Exactly once, Assured delivery, =1 */
51: #define MQTT_QOS_RESERVED 3 /* reserved */
52:
53: #define MQTT_FLAG_RETAIN 1 /* This flag is only used on PUBLISH messages.
54:
55: When a client sends a PUBLISH to a server,
56: if the Retain flag is set (1),
57: the server should hold on to the message after it has been
58: delivered to the current subscribers.
59: When a new subscription is established on a topic,
60: the last retained message on that topic should be sent to
61: the subscriber with the Retain flag set.
62: If there is no retained message, nothing is sent
63: This is useful where publishers send messages on a
64: "report by exception" basis, where it might be some time between messages.
65: This allows new subscribers to instantly receive data with the retained,
66: or Last Known Good, value.
67:
68: When a server sends a PUBLISH to a client as a result of
69: a subscription that already existed when the original PUBLISH arrived,
70: the Retain flag should not be set, regardless of the Retain flag
71: of the original PUBLISH. This allows a client to distinguish messages
72: that are being received because they were retained and those
73: that are being received "live".
74:
75: Retained messages should be kept over restarts of the server.
76: A server may delete a retained message if it receives a message
77: with a zero-length payload and the Retain flag set on the same topic. */
78:
1.1.1.1.2.4 misho 79: /* VARIABLE HEADERS */
80:
81: #define MQTT_RETCODE_ACCEPTED 0
82: #define MQTT_RETCODE_REFUSE_VER 1
83: #define MQTT_RETCODE_REFUSE_ID 2
84: #define MQTT_RETCODE_REFUSE_UNAVAIL 3
85: #define MQTT_RETCODE_REFUSE_USERPASS 4
86: #define MQTT_RETCODE_DENIED 5
87:
88:
89: typedef union {
90: struct {
91: unsigned short m:8,
92: l:8;
93: } sb;
94: unsigned short val;
1.1.1.1.2.5 misho 95: } mqtt_v_t;
1.1.1.1.2.4 misho 96:
97: typedef struct {
1.1.1.1.2.22 misho 98: unsigned char sub_ret;
99: struct __sbuf sub_topic;
100: struct __sbuf sub_value;
1.1.1.1.2.12 misho 101: } mqtt_subscr_t;
102:
103: typedef struct {
1.1.1.1.2.5 misho 104: mqtt_v_t var_sb;
1.1.1.1.2.4 misho 105: unsigned char var_data[0];
106: } __packed mqtthdr_var_t;
1.1.1.1.2.5 misho 107: #define MQTTHDR_VAR_SIZEOF(x) (assert((x)), sizeof(mqtt_v_t) + ntohs((x)->var_sb.val))
1.1.1.1.2.4 misho 108:
109: typedef unsigned char mqtthdr_protover_t;
110:
111: typedef struct {
112: unsigned char reserved:1,
113: clean_sess:1,
114: will_flg:1,
115: will_qos:2,
116: will_retain:1,
117: password:1,
118: username:1;
119: } __packed mqtthdr_connflgs_t;
120:
1.1.1.1.2.7 misho 121: typedef struct {
122: unsigned char reserved;
123: unsigned char retcode;
124: } __packed mqtthdr_connack_t;
125:
1.1.1.1.2.1 misho 126:
1.1.1.1.2.5 misho 127: /* MQTT Message buffer */
128:
129: typedef struct {
130: void *msg_base;
131: unsigned short msg_len;
132: } mqtt_msg_t;
133:
1.1.1.1.2.20 misho 134: /* MQTT dispatcher callbacks */
135:
136: typedef int (*mqtt_cb_t)(void *);
137:
1.1.1.1.2.5 misho 138:
1.1 misho 139: // -------------------------------------------------------
140: // mqtt_GetErrno() Get error code of last operation
141: inline int mqtt_GetErrno();
142: // mqtt_GetError() Get error text of last operation
143: inline const char *mqtt_GetError();
144: // -------------------------------------------------------
145:
146:
1.1.1.1.2.1 misho 147: /*
1.1.1.1.2.5 misho 148: * mqtt_msgAlloc() Allocate memory for MQTT Message
1.1.1.1.2.15 misho 149: *
1.1.1.1.2.5 misho 150: * @len = >0 Allocate buffer with length
151: * return: NULL error or Message, after use must call mqtt_msgFree() with all!=0
152: */
153: inline mqtt_msg_t *mqtt_msgAlloc(unsigned short len);
154: /*
155: * mqtt_msgFree() Free MQTT message
1.1.1.1.2.15 misho 156: *
1.1.1.1.2.5 misho 157: * @msg = Message buffer
158: * @all = !=0 Destroy entire message, if MQTT Message allocated with mqtt_msgAlloc()
159: * return: none
160: */
161: inline void mqtt_msgFree(mqtt_msg_t ** __restrict msg, int all);
162: /*
163: * mqtt_msgRealloc() Reallocate MQTT message buffer
1.1.1.1.2.15 misho 164: *
1.1.1.1.2.5 misho 165: * @msg = MQTT message
166: * @len = new length
167: * return: -1 error or >-1 old buffer length
168: */
169: inline int mqtt_msgRealloc(mqtt_msg_t * __restrict msg, unsigned short len);
170:
171: /*
1.1.1.1.2.1 misho 172: * mqtt_encodeLen() Encode number to MQTT length field
1.1.1.1.2.15 misho 173: *
1.1.1.1.2.1 misho 174: * @num = number for encode
175: * return: -1 error or >-1 length
176: */
177: inline unsigned int mqtt_encodeLen(unsigned int num);
178: /*
179: * mqtt_decodeLen() Decode length from MQTT packet
1.1.1.1.2.15 misho 180: *
1.1.1.1.2.23 misho 181: * @len = length from MQTT header
1.1.1.1.2.2 misho 182: * @n = sizeof bytes, if !=NULL
1.1.1.1.2.1 misho 183: * return: -1 error, >-1 length of message
184: */
1.1.1.1.2.23 misho 185: inline unsigned int mqtt_decodeLen(void * __restrict len, int * __restrict n);
1.1.1.1.2.2 misho 186: /*
187: * mqtt_sizeLen Return sizeof len field
1.1.1.1.2.15 misho 188: *
1.1.1.1.2.2 misho 189: * @len = length
190: * return: -1 error, >-1 sizeof len in bytes
191: */
192: inline char mqtt_sizeLen(unsigned int len);
1.1.1.1.2.4 misho 193: /*
1.1.1.1.2.12 misho 194: * mqtt_str2sub Create MQTT subscribe variable from string(s)
1.1.1.1.2.15 misho 195: *
1.1.1.1.2.12 misho 196: * @csStr = strings
197: * @strnum = number of strings elements
198: * @qoses = QoS elements applied to subscribe variable,
199: * count of elements must be equal with csStr elements
200: * return: NULL error or != subscribe variables array, must be free after use with mqtt_freeSub()
201: */
202: inline mqtt_subscr_t *mqtt_str2sub(const char **csStr, unsigned short strnum, unsigned char *qoses);
203: /*
1.1.1.1.2.15 misho 204: * mqtt_subFree() Free array from subscribe variables
1.1.1.1.2.12 misho 205: *
206: * @subs = Subscribe variables
207: * return: none
1.1.1.1.2.4 misho 208: */
1.1.1.1.2.16 misho 209: inline void mqtt_subFree(mqtt_subscr_t ** __restrict subs);
1.1.1.1.2.15 misho 210: /*
211: * mqtt_subAlloc() Create array from subscribe variables
212: *
213: * @num = Number of elements
1.1.1.1.2.16 misho 214: * return: NULL error or subscribe array, after use must call mqtt_subFree()
1.1.1.1.2.15 misho 215: */
216: inline mqtt_subscr_t *mqtt_subAlloc(unsigned short num);
1.1.1.1.2.29! misho 217: /*
! 218: * mqtt_subRealloc() Reallocate array from subscribe variables
! 219: *
! 220: * @subs = Subscribe array
! 221: * @num = Number of elements
! 222: * return: NULL error or subscribe array, after use must call mqtt_subFree()
! 223: */
! 224: inline mqtt_subscr_t *mqtt_subRealloc(mqtt_subscr_t * __restrict subs, unsigned short num);
1.1.1.1.2.1 misho 225:
1.1.1.1.2.20 misho 226:
227: /*** SENDER FUNCTIONS ***/
228:
1.1.1.1.2.6 misho 229: /*
230: * mqtt_msgCONNECT() Create CONNECT message
231: *
232: * @buf = Message buffer
233: * @csConnID = ConnectID
234: * @csUser = Username if !=NULL
235: * @csPass = Password for Username, only if csUser is set
236: * @csWillTopic = Will Topic if !=NULL Will Flags set into message
237: * @csWillMessage = Will Message, may be NULL
238: * @ClrSess = Clear Session subscriptions after disconnect
239: * @WillQOS = Will QOS if csWillTopic is set
240: * @WillRetain = Will Retain Will Message if csWillTopic is set
241: * return: -1 error or >-1 message size for send
242: */
243: int mqtt_msgCONNECT(mqtt_msg_t * __restrict buf, const char *csConnID,
244: const char *csUser, const char *csPass,
245: const char *csWillTopic, const char *csWillMessage,
1.1.1.1.2.8 misho 246: unsigned char ClrSess, unsigned char WillQOS, unsigned char WillRetain);
1.1.1.1.2.7 misho 247: /*
248: * mqtt_msgCONNACK() Create CONNACK message
249: *
250: * @buf = Message buffer
251: * @retcode = Return code
252: * return: -1 error or >-1 message size for send
253: */
1.1.1.1.2.8 misho 254: int mqtt_msgCONNACK(mqtt_msg_t * __restrict buf, unsigned char retcode);
1.1.1.1.2.18 misho 255: /*
256: * mqtt_msgDISCONNECT() Create DISCONNECT message
257: *
258: * @buf = Message buffer
259: * return: -1 error or >-1 message size for send
260: */
261: int mqtt_msgDISCONNECT(mqtt_msg_t * __restrict buf);
262: /*
263: * mqtt_msgPINGREQ() Create PINGREQ message
264: *
265: * @buf = Message buffer
266: * return: -1 error or >-1 message size for send
267: */
268: int mqtt_msgPINGREQ(mqtt_msg_t * __restrict buf);
269: /*
270: * mqtt_msgPINGRESP() Create PINGRESP message
271: *
272: * @buf = Message buffer
273: * return: -1 error or >-1 message size for send
274: */
275: int mqtt_msgPINGRESP(mqtt_msg_t * __restrict buf);
1.1.1.1.2.13 misho 276:
1.1.1.1.2.8 misho 277: /*
278: * mqtt_msgPUBLISH() Create PUBLISH message
279: *
280: * @buf = Message buffer
281: * @csTopic = Publish topic
282: * @msgID = MessageID >0, if QOS != MQTT_QOS_ONCE
283: * @Dup = Duplicate message
284: * @QOS = QoS
1.1.1.1.2.10 misho 285: * @Retain = Retain message
1.1.1.1.2.11 misho 286: * @pData = Publish data into topic
287: * @datlen = Publish data length
1.1.1.1.2.8 misho 288: * return: -1 error or >-1 message size for send
289: */
1.1.1.1.2.28 misho 290: int mqtt_msgPUBLISH(mqtt_msg_t * __restrict buf, const char *csTopic,
291: unsigned short msgID, unsigned char Dup, unsigned char QOS,
292: unsigned char Retain, const void *pData, int datlen);
1.1.1.1.2.8 misho 293: /*
294: * mqtt_msgPUBACK() Create PUBACK message
295: *
296: * @buf = Message buffer
297: * @msgID = MessageID
298: * return: -1 error or >-1 message size for send
299: */
300: inline int mqtt_msgPUBACK(mqtt_msg_t * __restrict buf, unsigned short msgID);
301: /*
302: * mqtt_msgPUBREC() Create PUBREC message
303: *
304: * @buf = Message buffer
305: * @msgID = MessageID
306: * return: -1 error or >-1 message size for send
307: */
308: inline int mqtt_msgPUBREC(mqtt_msg_t * __restrict buf, unsigned short msgID);
309: /*
310: * mqtt_msgPUBREL() Create PUBREL message
311: *
312: * @buf = Message buffer
313: * @msgID = MessageID
314: * return: -1 error or >-1 message size for send
315: */
316: inline int mqtt_msgPUBREL(mqtt_msg_t * __restrict buf, unsigned short msgID);
317: /*
318: * mqtt_msgPUBCOMP() Create PUBCOMP message
319: *
320: * @buf = Message buffer
321: * @msgID = MessageID
322: * return: -1 error or >-1 message size for send
323: */
324: inline int mqtt_msgPUBCOMP(mqtt_msg_t * __restrict buf, unsigned short msgID);
1.1.1.1.2.6 misho 325:
1.1.1.1.2.13 misho 326: /*
327: * mqtt_msgSUBSCRIBE() Create SUBSCRIBE message
328: *
329: * @buf = Message buffer
330: * @Topics = MQTT subscription topics
331: * @msgID = MessageID
332: * @Dup = Duplicate message
333: * @QOS = QoS
334: * return: -1 error or >-1 message size for send
335: */
336: int
337: mqtt_msgSUBSCRIBE(mqtt_msg_t * __restrict buf, mqtt_subscr_t * __restrict Topics,
338: unsigned short msgID, unsigned char Dup, unsigned char QOS);
1.1.1.1.2.15 misho 339: /*
340: * mqtt_msgSUBACK() Create SUBACK message
341: *
342: * @buf = Message buffer
343: * @Topics = MQTT subscription topics
344: * @msgID = MessageID
345: * return: -1 error or >-1 message size for send
346: */
347: int mqtt_msgSUBACK(mqtt_msg_t * __restrict buf, mqtt_subscr_t * __restrict Topics,
348: unsigned short msgID);
1.1.1.1.2.17 misho 349: /*
350: * mqtt_msgUNSUBSCRIBE() Create UNSUBSCRIBE message
351: *
352: * @buf = Message buffer
353: * @Topics = MQTT subscription topics
354: * @msgID = MessageID
355: * @Dup = Duplicate message
356: * @QOS = QoS
357: * return: -1 error or >-1 message size for send
358: */
359: int
360: mqtt_msgUNSUBSCRIBE(mqtt_msg_t * __restrict buf, mqtt_subscr_t * __restrict Topics,
361: unsigned short msgID, unsigned char Dup, unsigned char QOS);
362: /*
363: * mqtt_msgUNSUBACK() Create UNSUBACK message
364: *
365: * @buf = Message buffer
366: * @msgID = MessageID
367: * return: -1 error or >-1 message size for send
368: */
369: int mqtt_msgUNSUBACK(mqtt_msg_t * __restrict buf, unsigned short msgID);
1.1.1.1.2.13 misho 370:
1.1.1.1.2.1 misho 371:
1.1.1.1.2.20 misho 372: /*** RECEIVER FUNCTIONS ***/
373:
374: /*
1.1.1.1.2.24 misho 375: * mqtt_readCONNECT() Read elements from CONNECT message
376: *
377: * @buf = Message buffer
378: * @kasec = Keep Alive in seconds for current connection
379: * @psConnID = ConnectID
380: * @connLen = ConnectID length
381: * @psUser = Username if !=NULL
382: * @userLen = Username length
383: * @psPass = Password for Username, only if csUser is set
384: * @passLen = Password length
385: * @psWillTopic = Will Topic if !=NULL Will Flags set into message
386: * @topicLen = Will Topic length
387: * @psWillMessage = Will Message, may be NULL
388: * @msgLen = Will Message length
389: * return: .reserved == 1 is error or == 0 connection flags & msg ok
390: */
391: mqtthdr_connflgs_t mqtt_readCONNECT(mqtt_msg_t * __restrict buf, unsigned short *kasec,
392: char * __restrict psConnID, int connLen,
393: char * __restrict psUser, int userLen, char * __restrict psPass, int passLen,
394: char * __restrict psWillTopic, int topicLen, char * __restrict psWillMessage, int msgLen);
1.1.1.1.2.25 misho 395: /*
396: * mqtt_readCONNACK() Read CONNACK message
397: *
398: * @buf = Message buffer
399: * return: -1 error or >-1 CONNECT message return code
400: */
401: unsigned char mqtt_readCONNACK(mqtt_msg_t * __restrict buf);
1.1.1.1.2.26 misho 402: /*
403: * mqtt_readDISCONNECT() Read DISCONNECT message
404: *
405: * @buf = Message buffer
406: * return: -1 error, 0 ok, >0 undefined result
407: */
408: int mqtt_readDISCONNECT(mqtt_msg_t * __restrict buf);
409: /*
410: * mqtt_readPINGREQ() Read PINGREQ message
411: *
412: * @buf = Message buffer
413: * return: -1 error, 0 ok, >0 undefined result
414: */
415: int mqtt_readPINGREQ(mqtt_msg_t * __restrict buf);
416: /*
417: * mqtt_readPINGRESP() Read PINGRESP message
418: *
419: * @buf = Message buffer
420: * return: -1 error, 0 ok, >0 undefined result
421: */
422: int mqtt_readPINGRESP(mqtt_msg_t * __restrict buf);
1.1.1.1.2.24 misho 423:
1.1.1.1.2.27 misho 424: /*
1.1.1.1.2.28 misho 425: * mqtt_readPUBLISH() Read PUBLISH message
426: *
427: * @buf = Message buffer
428: * @psTopic = Topic
429: * @topicLen = Topic length
430: * @msgID = MessageID
431: * @pData = Data buffer
432: * @datLen = Data buffer length, if *datLen == 0 allocate memory for pData
433: * return: NULL error or !=NULL MQTT fixed header
434: */
435: struct mqtthdr *mqtt_readPUBLISH(mqtt_msg_t * __restrict buf, char * __restrict psTopic,
436: int topicLen, unsigned short *msgID, void * __restrict pData, int *datLen);
437: /*
1.1.1.1.2.27 misho 438: * mqtt_readPUBACK() Read PUBACK message
439: *
440: * @buf = Message buffer
441: * return: -1 error or MessageID
442: */
443: u_short mqtt_readPUBACK(mqtt_msg_t * __restrict buf);
444: /*
445: * mqtt_readPUBREC() Read PUBREC message
446: *
447: * @buf = Message buffer
448: * return: -1 error or MessageID
449: */
450: u_short mqtt_readPUBREC(mqtt_msg_t * __restrict buf);
451: /*
452: * mqtt_readPUBREL() Read PUBREL message
453: *
454: * @buf = Message buffer
455: * return: -1 error or MessageID
456: */
457: u_short mqtt_readPUBREL(mqtt_msg_t * __restrict buf);
458: /*
459: * mqtt_readPUBCOMP() Read PUBCOMP message
460: *
461: * @buf = Message buffer
462: * return: -1 error or MessageID
463: */
464: u_short mqtt_readPUBCOMP(mqtt_msg_t * __restrict buf);
465:
466: /*
1.1.1.1.2.29! misho 467: * mqtt_readSUBSCRIBE() Read SUBSCRIBE message
! 468: *
! 469: * @buf = Message buffer
! 470: * @msgID = MessageID
! 471: * @subscr = Subscriptions, must be free after use with mqtt_subFree()
! 472: * return: NULL error or !=NULL MQTT fixed header
! 473: */
! 474: struct mqtthdr *mqtt_readSUBSCRIBE(mqtt_msg_t * __restrict buf, unsigned short *msgID,
! 475: mqtt_subscr_t **subscr);
! 476: /*
1.1.1.1.2.27 misho 477: * mqtt_readUNSUBACK() Read UNSUBACK message
478: *
479: * @buf = Message buffer
480: * return: -1 error or MessageID
481: */
482: u_short mqtt_readUNSUBACK(mqtt_msg_t * __restrict buf);
1.1.1.1.2.24 misho 483:
484: /*** ENGINE FUNCTIONS ***/
485:
486: /*
1.1.1.1.2.20 misho 487: * mqttInitCallbacks() Init callback array for dispatcher
488: *
489: * return: NULL error or !=NULL allocated callback array, after use free with mqttFiniCallbacks()
490: */
491: mqtt_cb_t *mqttInitCallbacks(void);
492: /*
493: * mqttFiniCallbacks() Free callback array
494: *
495: * @cb = Callback array
496: * return: none
497: */
498: void mqttFiniCallbacks(mqtt_cb_t ** __restrict cb);
1.1.1.1.2.21 misho 499: /*
500: * MQTT_CALLBACK() Assign function to callback array for MQTT dispatcher
501: *
502: * @_cbs = Callback array
503: * @_x = MQTT Message type, like MQTT_TYPE_* ...
504: * @_func = Function
505: * return: none
506: */
507: #define MQTT_CALLBACK(_cbs, _x, _func) (assert((_cbs)), (_cbs)[(_x)] = (_func))
508: /*
509: * mqttDispatcher() MQTT Message type dispatcher
510: *
511: * @cb = Callback array
512: * @buf = Received MQTT message
513: * return: -1 error or >-1 return value from executed callback
514: */
515: inline int mqttDispatcher(mqtt_cb_t * __restrict cb, mqtt_msg_t * __restrict buf);
1.1.1.1.2.20 misho 516:
517:
1.1 misho 518: #endif
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to aitmqtt.h CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / mqtt / inc