Annotation of libaitmqtt/inc/aitmqtt.h, revision 1.1.1.1
1.1 misho 1: /*************************************************************************
2: * (C) 2011 AITNET ltd - Sofia/Bulgaria - <misho@aitbg.com>
3: * by Michael Pounov <misho@openbsd-bg.org>
4: *
5: * $Author: misho $
6: * $Id: aitsched.c,v 1.5 2012/01/24 21:59:47 misho Exp $
7: *
8: **************************************************************************
9: The ELWIX and AITNET software is distributed under the following
10: terms:
11:
12: All of the documentation and software included in the ELWIX and AITNET
13: Releases is copyrighted by ELWIX - Sofia/Bulgaria <info@elwix.org>
14:
15: Copyright 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011
16: by Michael Pounov <misho@elwix.org>. All rights reserved.
17:
18: Redistribution and use in source and binary forms, with or without
19: modification, are permitted provided that the following conditions
20: are met:
21: 1. Redistributions of source code must retain the above copyright
22: notice, this list of conditions and the following disclaimer.
23: 2. Redistributions in binary form must reproduce the above copyright
24: notice, this list of conditions and the following disclaimer in the
25: documentation and/or other materials provided with the distribution.
26: 3. All advertising materials mentioning features or use of this software
27: must display the following acknowledgement:
28: This product includes software developed by Michael Pounov <misho@elwix.org>
29: ELWIX - Embedded LightWeight unIX and its contributors.
30: 4. Neither the name of AITNET nor the names of its contributors
31: may be used to endorse or promote products derived from this software
32: without specific prior written permission.
33:
34: THIS SOFTWARE IS PROVIDED BY AITNET AND CONTRIBUTORS ``AS IS'' AND
35: ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
36: IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
37: ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
38: FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
39: DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
40: OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
41: HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
42: LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
43: OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
44: SUCH DAMAGE.
45: */
46: #ifndef __AITMQTT_H
47: #define __AITMQTT_H
48:
49:
50: /* FIXED HEADER */
51:
52: struct mqtthdr {
53: union {
54: struct {
55: unsigned char retain:1,
56: qos:2,
57: dup:1,
58: type:4;
59: };
60: unsigned char val;
61: } mqtt_msg;
62: unsigned char mqtt_len[1]; /* may be grow to 4 bytes */
63: } __packed;
64: #define MQTTHDR_MSGINIT(x) (assert((x)), (x)->mqtt_msg.val ^= (x)->mqtt_msg.val)
65:
66: #define MQTT_TYPE_UNKNOWN 0 /* reserved */
67: #define MQTT_TYPE_CONNECT 1 /* client request to connect to server */
68: #define MQTT_TYPE_CONNACK 2 /* connect acknowledgment */
69: #define MQTT_TYPE_PUBLISH 3 /* publish message */
70: #define MQTT_TYPE_PUBACK 4 /* publish acknowledgment */
71: #define MQTT_TYPE_PUBREC 5 /* publish received (assured delivery part 1) */
72: #define MQTT_TYPE_PUBREL 6 /* publish release (assured delivery part 2) */
73: #define MQTT_TYPE_PUBCOMP 7 /* publish complete (assured delivery part 3) */
74: #define MQTT_TYPE_SUBSCRIBE 8 /* client subscribe request */
75: #define MQTT_TYPE_SUBACK 9 /* subscribe acknowledgment */
76: #define MQTT_TYPE_UNSUBSCRIBE 10 /* client unsubscribe request */
77: #define MQTT_TYPE_UNSUBACK 11 /* unsubscribe acknowledgment */
78: #define MQTT_TYPE_PINGREQ 12 /* PING request */
79: #define MQTT_TYPE_PINGRESP 13 /* PING response */
80: #define MQTT_TYPE_DISCONNECT 14 /* client is disconnecting */
81: #define MQTT_TYPE_MAX 15 /* reserved */
82:
83: #define MQTT_FLAG_DUP 1 /* This flag is set when the client or server attempts to re-deliver
84: a PUBLISH, PUBREL, SUBSCRIBE or UNSUBSCRIBE message.
85: This applies to messages where the value of QoS is greater than
86: zero (0), and an acknowledgment is required.
87: When the DUP bit is set, the variable header includes a Message ID.
88:
89: The recipient should treat this flag as a hint as to whether
90: the message may have been previously received.
91: It should not be relied on to detect duplicates. */
92:
93: #define MQTT_QOS_ONCE 0 /* At most once, Fire and Forget, <=1 */
94: #define MQTT_QOS_ACK 1 /* At least once, Acknowledged delivery, >=1 */
95: #define MQTT_QOS_EXACTLY 2 /* Exactly once, Assured delivery, =1 */
96: #define MQTT_QOS_RESERVED 3 /* reserved */
97:
98: #define MQTT_FLAG_RETAIN 1 /* This flag is only used on PUBLISH messages.
99:
100: When a client sends a PUBLISH to a server,
101: if the Retain flag is set (1),
102: the server should hold on to the message after it has been
103: delivered to the current subscribers.
104: When a new subscription is established on a topic,
105: the last retained message on that topic should be sent to
106: the subscriber with the Retain flag set.
107: If there is no retained message, nothing is sent
108: This is useful where publishers send messages on a
109: "report by exception" basis, where it might be some time between messages.
110: This allows new subscribers to instantly receive data with the retained,
111: or Last Known Good, value.
112:
113: When a server sends a PUBLISH to a client as a result of
114: a subscription that already existed when the original PUBLISH arrived,
115: the Retain flag should not be set, regardless of the Retain flag
116: of the original PUBLISH. This allows a client to distinguish messages
117: that are being received because they were retained and those
118: that are being received "live".
119:
120: Retained messages should be kept over restarts of the server.
121: A server may delete a retained message if it receives a message
122: with a zero-length payload and the Retain flag set on the same topic. */
123:
124: /* VARIABLE HEADERS */
125:
126: #define MQTT_RETCODE_ACCEPTED 0
127: #define MQTT_RETCODE_REFUSE_VER 1
128: #define MQTT_RETCODE_REFUSE_ID 2
129: #define MQTT_RETCODE_REFUSE_UNAVAIL 3
130: #define MQTT_RETCODE_REFUSE_USERPASS 4
131: #define MQTT_RETCODE_DENIED 5
132:
133:
134: /* MQTT Message buffer */
135:
136: typedef struct {
137: void *msg_base;
138: unsigned short msg_len;
139: } mqtt_msg_t;
140:
141: /* MQTT hooks callback */
142:
143: typedef void *(*mqtt_cb_t)(void *);
144:
145: /* MQTT structures */
146:
147: typedef union {
148: struct {
149: unsigned short m:8,
150: l:8;
151: } sb;
152: unsigned short val;
153: } mqtt_len_t;
154:
155: typedef struct {
156: unsigned char sub_ret;
157: mqtt_msg_t sub_topic;
158: mqtt_msg_t sub_value;
159: } mqtt_subscr_t;
160:
161: typedef struct {
162: mqtt_len_t var_sb;
163: unsigned char var_data[0];
164: } __packed mqtthdr_var_t;
165: #define MQTTHDR_VAR_SIZEOF(x) (assert((x)), sizeof(mqtt_len_t) + ntohs((x)->var_sb.val))
166:
167: typedef unsigned char mqtthdr_protover_t;
168:
169: typedef union {
170: struct {
171: unsigned char reserved:1,
172: clean_sess:1,
173: will_flg:1,
174: will_qos:2,
175: will_retain:1,
176: password:1,
177: username:1;
178: };
179: unsigned char flags;
180: } __packed mqtthdr_connflgs_t;
181:
182: typedef struct {
183: unsigned char reserved;
184: unsigned char retcode;
185: } __packed mqtthdr_connack_t;
186:
187:
188: // -------------------------------------------------------
189: // mqtt_GetErrno() Get error code of last operation
190: inline int mqtt_GetErrno();
191: // mqtt_GetError() Get error text of last operation
192: inline const char *mqtt_GetError();
193: // -------------------------------------------------------
194:
195:
196: /*
197: * mqtt_msgAlloc() Allocate memory for MQTT Message
198: *
199: * @len = >0 Allocate buffer with length
200: * return: NULL error or Message, after use must call mqtt_msgFree() with all!=0
201: */
202: inline mqtt_msg_t *mqtt_msgAlloc(unsigned short len);
203: /*
204: * mqtt_msgFree() Free MQTT message
205: *
206: * @msg = Message buffer
207: * @all = !=0 Destroy entire message, if MQTT Message allocated with mqtt_msgAlloc()
208: * return: none
209: */
210: inline void mqtt_msgFree(mqtt_msg_t ** __restrict msg, int all);
211: /*
212: * mqtt_msgRealloc() Reallocate MQTT message buffer
213: *
214: * @msg = MQTT message
215: * @len = new length
216: * return: -1 error or >-1 old buffer length
217: */
218: inline int mqtt_msgRealloc(mqtt_msg_t * __restrict msg, unsigned short len);
219:
220: /*
221: * mqtt_encodeLen() Encode number to MQTT length field
222: *
223: * @num = number for encode
224: * return: -1 error or >-1 length
225: */
226: inline unsigned int mqtt_encodeLen(unsigned int num);
227: /*
228: * mqtt_decodeLen() Decode length from MQTT packet
229: *
230: * @len = length from MQTT header
231: * @n = sizeof bytes, if !=NULL
232: * return: -1 error, >-1 length of message
233: */
234: inline unsigned int mqtt_decodeLen(void * __restrict len, int * __restrict n);
235: /*
236: * mqtt_sizeLen Return sizeof len field
237: *
238: * @len = length
239: * return: -1 error, >-1 sizeof len in bytes
240: */
241: inline char mqtt_sizeLen(unsigned int len);
242: /*
243: * mqtt_str2sub Create MQTT subscribe variable from string(s)
244: *
245: * @csStr = strings
246: * @strnum = number of strings elements
247: * @qoses = QoS elements applied to subscribe variable,
248: * count of elements must be equal with csStr elements
249: * return: NULL error or != subscribe variables array, must be free after use with mqtt_freeSub()
250: */
251: inline mqtt_subscr_t *mqtt_str2sub(const char **csStr, unsigned short strnum, unsigned char *qoses);
252: /*
253: * mqtt_subFree() Free array from subscribe variables
254: *
255: * @subs = Subscribe variables
256: * return: none
257: */
258: inline void mqtt_subFree(mqtt_subscr_t ** __restrict subs);
259: /*
260: * mqtt_subAlloc() Create array from subscribe variables
261: *
262: * @num = Number of elements
263: * return: NULL error or subscribe array, after use must call mqtt_subFree()
264: */
265: inline mqtt_subscr_t *mqtt_subAlloc(unsigned short num);
266: /*
267: * mqtt_subRealloc() Reallocate array from subscribe variables
268: *
269: * @subs = Subscribe array
270: * @num = Number of elements
271: * return: NULL error or subscribe array, after use must call mqtt_subFree()
272: */
273: inline mqtt_subscr_t *mqtt_subRealloc(mqtt_subscr_t * __restrict subs, unsigned short num);
274:
275:
276: /*** SENDER FUNCTIONS ***/
277:
278: /*
279: * mqtt_msgCONNECT() Create CONNECT message
280: *
281: * @buf = Message buffer
282: * @csConnID = ConnectID
283: * @kasec = Keep alive timeout
284: * @csUser = Username if !=NULL
285: * @csPass = Password for Username, only if csUser is set
286: * @csWillTopic = Will Topic if !=NULL Will Flags set into message
287: * @csWillMessage = Will Message, may be NULL
288: * @ClrSess = Clear Session subscriptions after disconnect
289: * @WillQOS = Will QOS if csWillTopic is set
290: * @WillRetain = Will Retain Will Message if csWillTopic is set
291: * return: -1 error or >-1 message size for send
292: */
293: int mqtt_msgCONNECT(mqtt_msg_t * __restrict buf, const char *csConnID,
294: unsigned short kasec, const char *csUser, const char *csPass,
295: const char *csWillTopic, const char *csWillMessage,
296: unsigned char ClrSess, unsigned char WillQOS, unsigned char WillRetain);
297: /*
298: * mqtt_msgCONNACK() Create CONNACK message
299: *
300: * @buf = Message buffer
301: * @retcode = Return code
302: * return: -1 error or >-1 message size for send
303: */
304: int mqtt_msgCONNACK(mqtt_msg_t * __restrict buf, unsigned char retcode);
305: /*
306: * mqtt_msgDISCONNECT() Create DISCONNECT message
307: *
308: * @buf = Message buffer
309: * return: -1 error or >-1 message size for send
310: */
311: int mqtt_msgDISCONNECT(mqtt_msg_t * __restrict buf);
312: /*
313: * mqtt_msgPINGREQ() Create PINGREQ message
314: *
315: * @buf = Message buffer
316: * return: -1 error or >-1 message size for send
317: */
318: int mqtt_msgPINGREQ(mqtt_msg_t * __restrict buf);
319: /*
320: * mqtt_msgPINGRESP() Create PINGRESP message
321: *
322: * @buf = Message buffer
323: * return: -1 error or >-1 message size for send
324: */
325: int mqtt_msgPINGRESP(mqtt_msg_t * __restrict buf);
326:
327: /*
328: * mqtt_msgPUBLISH() Create PUBLISH message
329: *
330: * @buf = Message buffer
331: * @csTopic = Publish topic
332: * @msgID = MessageID >0, if QOS != MQTT_QOS_ONCE
333: * @Dup = Duplicate message
334: * @QOS = QoS
335: * @Retain = Retain message
336: * @pData = Publish data into topic
337: * @datlen = Publish data length
338: * return: -1 error or >-1 message size for send
339: */
340: int mqtt_msgPUBLISH(mqtt_msg_t * __restrict buf, const char *csTopic,
341: unsigned short msgID, unsigned char Dup, unsigned char QOS,
342: unsigned char Retain, const void *pData, int datlen);
343: /*
344: * mqtt_msgPUBACK() Create PUBACK message
345: *
346: * @buf = Message buffer
347: * @msgID = MessageID
348: * return: -1 error or >-1 message size for send
349: */
350: inline int mqtt_msgPUBACK(mqtt_msg_t * __restrict buf, unsigned short msgID);
351: /*
352: * mqtt_msgPUBREC() Create PUBREC message
353: *
354: * @buf = Message buffer
355: * @msgID = MessageID
356: * return: -1 error or >-1 message size for send
357: */
358: inline int mqtt_msgPUBREC(mqtt_msg_t * __restrict buf, unsigned short msgID);
359: /*
360: * mqtt_msgPUBREL() Create PUBREL message
361: *
362: * @buf = Message buffer
363: * @msgID = MessageID
364: * return: -1 error or >-1 message size for send
365: */
366: inline int mqtt_msgPUBREL(mqtt_msg_t * __restrict buf, unsigned short msgID);
367: /*
368: * mqtt_msgPUBCOMP() Create PUBCOMP message
369: *
370: * @buf = Message buffer
371: * @msgID = MessageID
372: * return: -1 error or >-1 message size for send
373: */
374: inline int mqtt_msgPUBCOMP(mqtt_msg_t * __restrict buf, unsigned short msgID);
375:
376: /*
377: * mqtt_msgSUBSCRIBE() Create SUBSCRIBE message
378: *
379: * @buf = Message buffer
380: * @Topics = MQTT subscription topics
381: * @msgID = MessageID
382: * @Dup = Duplicate message
383: * @QOS = QoS
384: * return: -1 error or >-1 message size for send
385: */
386: int
387: mqtt_msgSUBSCRIBE(mqtt_msg_t * __restrict buf, mqtt_subscr_t * __restrict Topics,
388: unsigned short msgID, unsigned char Dup, unsigned char QOS);
389: /*
390: * mqtt_msgSUBACK() Create SUBACK message
391: *
392: * @buf = Message buffer
393: * @Topics = MQTT subscription topics
394: * @msgID = MessageID
395: * return: -1 error or >-1 message size for send
396: */
397: int mqtt_msgSUBACK(mqtt_msg_t * __restrict buf, mqtt_subscr_t * __restrict Topics,
398: unsigned short msgID);
399: /*
400: * mqtt_msgUNSUBSCRIBE() Create UNSUBSCRIBE message
401: *
402: * @buf = Message buffer
403: * @Topics = MQTT subscription topics
404: * @msgID = MessageID
405: * @Dup = Duplicate message
406: * @QOS = QoS
407: * return: -1 error or >-1 message size for send
408: */
409: int
410: mqtt_msgUNSUBSCRIBE(mqtt_msg_t * __restrict buf, mqtt_subscr_t * __restrict Topics,
411: unsigned short msgID, unsigned char Dup, unsigned char QOS);
412: /*
413: * mqtt_msgUNSUBACK() Create UNSUBACK message
414: *
415: * @buf = Message buffer
416: * @msgID = MessageID
417: * return: -1 error or >-1 message size for send
418: */
419: int mqtt_msgUNSUBACK(mqtt_msg_t * __restrict buf, unsigned short msgID);
420:
421:
422: /*** RECEIVER FUNCTIONS ***/
423:
424: /*
425: * mqtt_readCONNECT() Read elements from CONNECT message
426: *
427: * @buf = Message buffer
428: * @kasec = Keep Alive in seconds for current connection
429: * @psConnID = ConnectID
430: * @connLen = ConnectID length
431: * @psUser = Username if !=NULL
432: * @userLen = Username length
433: * @psPass = Password for Username, only if csUser is set
434: * @passLen = Password length
435: * @psWillTopic = Will Topic if !=NULL Will Flags set into message and must be free()
436: * @psWillMessage = Will Message, may be NULL if !NULL must be free() after use!
437: * return: .reserved == 1 is error or == 0 connection flags & msg ok
438: */
439: mqtthdr_connack_t mqtt_readCONNECT(mqtt_msg_t * __restrict buf, unsigned short *kasec,
440: char * __restrict psConnID, int connLen,
441: char * __restrict psUser, int userLen, char * __restrict psPass, int passLen,
442: char ** __restrict psWillTopic, char ** __restrict psWillMessage);
443: /*
444: * mqtt_readCONNACK() Read CONNACK message
445: *
446: * @buf = Message buffer
447: * return: -1 error or >-1 CONNECT message return code
448: */
449: unsigned char mqtt_readCONNACK(mqtt_msg_t * __restrict buf);
450: /*
451: * mqtt_readDISCONNECT() Read DISCONNECT message
452: *
453: * @buf = Message buffer
454: * return: -1 error, 0 ok, >0 undefined result
455: */
456: int mqtt_readDISCONNECT(mqtt_msg_t * __restrict buf);
457: /*
458: * mqtt_readPINGREQ() Read PINGREQ message
459: *
460: * @buf = Message buffer
461: * return: -1 error, 0 ok, >0 undefined result
462: */
463: int mqtt_readPINGREQ(mqtt_msg_t * __restrict buf);
464: /*
465: * mqtt_readPINGRESP() Read PINGRESP message
466: *
467: * @buf = Message buffer
468: * return: -1 error, 0 ok, >0 undefined result
469: */
470: int mqtt_readPINGRESP(mqtt_msg_t * __restrict buf);
471:
472: /*
473: * mqtt_readPUBLISH() Read PUBLISH message
474: *
475: * @buf = Message buffer
476: * @psTopic = Topic
477: * @topicLen = Topic length
478: * @msgID = MessageID
479: * @pData = Data buffer
480: * @datLen = Data buffer length, if *datLen == 0 allocate memory for pData
481: * return: NULL error or !=NULL MQTT fixed header
482: */
483: struct mqtthdr *mqtt_readPUBLISH(mqtt_msg_t * __restrict buf, char * __restrict psTopic,
484: int topicLen, unsigned short *msgID, void * __restrict pData, int *datLen);
485: /*
486: * mqtt_readPUBACK() Read PUBACK message
487: *
488: * @buf = Message buffer
489: * return: -1 error or MessageID
490: */
491: u_short mqtt_readPUBACK(mqtt_msg_t * __restrict buf);
492: /*
493: * mqtt_readPUBREC() Read PUBREC message
494: *
495: * @buf = Message buffer
496: * return: -1 error or MessageID
497: */
498: u_short mqtt_readPUBREC(mqtt_msg_t * __restrict buf);
499: /*
500: * mqtt_readPUBREL() Read PUBREL message
501: *
502: * @buf = Message buffer
503: * return: -1 error or MessageID
504: */
505: u_short mqtt_readPUBREL(mqtt_msg_t * __restrict buf);
506: /*
507: * mqtt_readPUBCOMP() Read PUBCOMP message
508: *
509: * @buf = Message buffer
510: * return: -1 error or MessageID
511: */
512: u_short mqtt_readPUBCOMP(mqtt_msg_t * __restrict buf);
513:
514: /*
515: * mqtt_readSUBSCRIBE() Read SUBSCRIBE message
516: *
517: * @buf = Message buffer
518: * @msgID = MessageID
519: * @subscr = Subscriptions, must be free after use with mqtt_subFree()
520: * return: NULL error or !=NULL MQTT fixed header
521: */
522: struct mqtthdr *mqtt_readSUBSCRIBE(mqtt_msg_t * __restrict buf, unsigned short *msgID,
523: mqtt_subscr_t **subscr);
524: /*
525: * mqtt_readSUBACK() Read SUBACK message
526: *
527: * @buf = Message buffer
528: * @msgID = MessageID
529: * @subqos = Subscribes QoS, must be free after use with free()
530: * return: -1 error or >-1 readed subscribes QoS elements
531: */
532: int mqtt_readSUBACK(mqtt_msg_t * __restrict buf, u_short *msgID, unsigned char **subqos);
533: /*
534: * mqtt_readUNSUBSCRIBE() Read UNSUBSCRIBE message
535: *
536: * @buf = Message buffer
537: * @msgID = MessageID
538: * @subscr = Subscriptions, must be free after use with mqtt_subFree()
539: * return: NULL error or !=NULL MQTT fixed header
540: */
541: struct mqtthdr *mqtt_readUNSUBSCRIBE(mqtt_msg_t * __restrict buf, unsigned short *msgID,
542: mqtt_subscr_t **subscr);
543: /*
544: * mqtt_readUNSUBACK() Read UNSUBACK message
545: *
546: * @buf = Message buffer
547: * return: -1 error or MessageID
548: */
549: u_short mqtt_readUNSUBACK(mqtt_msg_t * __restrict buf);
550:
551: /*** ENGINE FUNCTIONS ***/
552:
553: /*
554: * mqttInitCallbacks() Init callback array for dispatcher
555: *
556: * return: NULL error or !=NULL allocated callback array, after use free with mqttFiniCallbacks()
557: */
558: mqtt_cb_t *mqttInitCallbacks(void);
559: /*
560: * mqttFiniCallbacks() Free callback array
561: *
562: * @cb = Callback array
563: * return: none
564: */
565: void mqttFiniCallbacks(mqtt_cb_t ** __restrict cb);
566: /*
567: * MQTT_CALLBACK() Assign function to callback array for MQTT dispatcher
568: *
569: * @_cbs = Callback array
570: * @_x = MQTT Message type, like MQTT_TYPE_* ...
571: * @_func = Function
572: * return: none
573: */
574: #define MQTT_CALLBACK(_cbs, _x, _func) (assert((_cbs)), (_cbs)[(_x)] = (_func))
575: /*
576: * mqttDispatcher() MQTT Message type dispatcher
577: *
578: * @cb = Callback array
579: * @buf = Received MQTT message
580: * return: -1 error or >-1 return value from executed callback
581: */
582: inline int mqttDispatcher(mqtt_cb_t * __restrict cb, mqtt_msg_t * __restrict buf);
583:
584:
585: #endif
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>