Annotation of mqtt/inc/aitmqtt.h, revision 1.1.1.1.2.20
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:
21: #define MQTT_FLAG_DUP 1 /* This flag is set when the client or server attempts to re-deliver
22: a PUBLISH, PUBREL, SUBSCRIBE or UNSUBSCRIBE message.
23: This applies to messages where the value of QoS is greater than
24: zero (0), and an acknowledgment is required.
25: When the DUP bit is set, the variable header includes a Message ID.
26:
27: The recipient should treat this flag as a hint as to whether
28: the message may have been previously received.
29: It should not be relied on to detect duplicates. */
30:
31: #define MQTT_QOS_ONCE 0 /* At most once, Fire and Forget, <=1 */
32: #define MQTT_QOS_ACK 1 /* At least once, Acknowledged delivery, >=1 */
33: #define MQTT_QOS_EXACTLY 2 /* Exactly once, Assured delivery, =1 */
34: #define MQTT_QOS_RESERVED 3 /* reserved */
35:
36: #define MQTT_FLAG_RETAIN 1 /* This flag is only used on PUBLISH messages.
37:
38: When a client sends a PUBLISH to a server,
39: if the Retain flag is set (1),
40: the server should hold on to the message after it has been
41: delivered to the current subscribers.
42: When a new subscription is established on a topic,
43: the last retained message on that topic should be sent to
44: the subscriber with the Retain flag set.
45: If there is no retained message, nothing is sent
46: This is useful where publishers send messages on a
47: "report by exception" basis, where it might be some time between messages.
48: This allows new subscribers to instantly receive data with the retained,
49: or Last Known Good, value.
50:
51: When a server sends a PUBLISH to a client as a result of
52: a subscription that already existed when the original PUBLISH arrived,
53: the Retain flag should not be set, regardless of the Retain flag
54: of the original PUBLISH. This allows a client to distinguish messages
55: that are being received because they were retained and those
56: that are being received "live".
57:
58: Retained messages should be kept over restarts of the server.
59: A server may delete a retained message if it receives a message
60: with a zero-length payload and the Retain flag set on the same topic. */
61:
1.1.1.1.2.4 misho 62: /* VARIABLE HEADERS */
63:
64: #define MQTT_RETCODE_ACCEPTED 0
65: #define MQTT_RETCODE_REFUSE_VER 1
66: #define MQTT_RETCODE_REFUSE_ID 2
67: #define MQTT_RETCODE_REFUSE_UNAVAIL 3
68: #define MQTT_RETCODE_REFUSE_USERPASS 4
69: #define MQTT_RETCODE_DENIED 5
70:
71:
72: typedef union {
73: struct {
74: unsigned short m:8,
75: l:8;
76: } sb;
77: unsigned short val;
1.1.1.1.2.5 misho 78: } mqtt_v_t;
1.1.1.1.2.4 misho 79:
80: typedef struct {
1.1.1.1.2.12 misho 81: mqtt_v_t sub_sb;
82: char *sub_data;
83: unsigned char sub_qos;
84: } mqtt_subscr_t;
85:
86: typedef struct {
1.1.1.1.2.5 misho 87: mqtt_v_t var_sb;
1.1.1.1.2.4 misho 88: unsigned char var_data[0];
89: } __packed mqtthdr_var_t;
1.1.1.1.2.5 misho 90: #define MQTTHDR_VAR_SIZEOF(x) (assert((x)), sizeof(mqtt_v_t) + ntohs((x)->var_sb.val))
1.1.1.1.2.4 misho 91:
92: typedef unsigned char mqtthdr_protover_t;
93:
94: typedef struct {
95: unsigned char reserved:1,
96: clean_sess:1,
97: will_flg:1,
98: will_qos:2,
99: will_retain:1,
100: password:1,
101: username:1;
102: } __packed mqtthdr_connflgs_t;
103:
1.1.1.1.2.7 misho 104: typedef struct {
105: unsigned char reserved;
106: unsigned char retcode;
107: } __packed mqtthdr_connack_t;
108:
1.1.1.1.2.1 misho 109:
1.1.1.1.2.5 misho 110: /* MQTT Message buffer */
111:
112: typedef struct {
113: void *msg_base;
114: unsigned short msg_len;
115: } mqtt_msg_t;
116:
1.1.1.1.2.20! misho 117: /* MQTT dispatcher callbacks */
! 118:
! 119: typedef int (*mqtt_cb_t)(void *);
! 120:
1.1.1.1.2.5 misho 121:
1.1 misho 122: // -------------------------------------------------------
123: // mqtt_GetErrno() Get error code of last operation
124: inline int mqtt_GetErrno();
125: // mqtt_GetError() Get error text of last operation
126: inline const char *mqtt_GetError();
127: // -------------------------------------------------------
128:
129:
1.1.1.1.2.1 misho 130: /*
1.1.1.1.2.5 misho 131: * mqtt_msgAlloc() Allocate memory for MQTT Message
1.1.1.1.2.15 misho 132: *
1.1.1.1.2.5 misho 133: * @len = >0 Allocate buffer with length
134: * return: NULL error or Message, after use must call mqtt_msgFree() with all!=0
135: */
136: inline mqtt_msg_t *mqtt_msgAlloc(unsigned short len);
137: /*
138: * mqtt_msgFree() Free MQTT message
1.1.1.1.2.15 misho 139: *
1.1.1.1.2.5 misho 140: * @msg = Message buffer
141: * @all = !=0 Destroy entire message, if MQTT Message allocated with mqtt_msgAlloc()
142: * return: none
143: */
144: inline void mqtt_msgFree(mqtt_msg_t ** __restrict msg, int all);
145: /*
146: * mqtt_msgRealloc() Reallocate MQTT message buffer
1.1.1.1.2.15 misho 147: *
1.1.1.1.2.5 misho 148: * @msg = MQTT message
149: * @len = new length
150: * return: -1 error or >-1 old buffer length
151: */
152: inline int mqtt_msgRealloc(mqtt_msg_t * __restrict msg, unsigned short len);
153:
154: /*
1.1.1.1.2.1 misho 155: * mqtt_encodeLen() Encode number to MQTT length field
1.1.1.1.2.15 misho 156: *
1.1.1.1.2.1 misho 157: * @num = number for encode
158: * return: -1 error or >-1 length
159: */
160: inline unsigned int mqtt_encodeLen(unsigned int num);
161: /*
162: * mqtt_decodeLen() Decode length from MQTT packet
1.1.1.1.2.15 misho 163: *
1.1.1.1.2.1 misho 164: * @len = length
1.1.1.1.2.2 misho 165: * @n = sizeof bytes, if !=NULL
1.1.1.1.2.1 misho 166: * return: -1 error, >-1 length of message
167: */
1.1.1.1.2.2 misho 168: inline unsigned int mqtt_decodeLen(unsigned int len, char *n);
169: /*
170: * mqtt_sizeLen Return sizeof len field
1.1.1.1.2.15 misho 171: *
1.1.1.1.2.2 misho 172: * @len = length
173: * return: -1 error, >-1 sizeof len in bytes
174: */
175: inline char mqtt_sizeLen(unsigned int len);
1.1.1.1.2.4 misho 176: /*
1.1.1.1.2.12 misho 177: * mqtt_str2sub Create MQTT subscribe variable from string(s)
1.1.1.1.2.15 misho 178: *
1.1.1.1.2.12 misho 179: * @csStr = strings
180: * @strnum = number of strings elements
181: * @qoses = QoS elements applied to subscribe variable,
182: * count of elements must be equal with csStr elements
183: * return: NULL error or != subscribe variables array, must be free after use with mqtt_freeSub()
184: */
185: inline mqtt_subscr_t *mqtt_str2sub(const char **csStr, unsigned short strnum, unsigned char *qoses);
186: /*
1.1.1.1.2.15 misho 187: * mqtt_subFree() Free array from subscribe variables
1.1.1.1.2.12 misho 188: *
189: * @subs = Subscribe variables
190: * return: none
1.1.1.1.2.4 misho 191: */
1.1.1.1.2.16 misho 192: inline void mqtt_subFree(mqtt_subscr_t ** __restrict subs);
1.1.1.1.2.15 misho 193: /*
194: * mqtt_subAlloc() Create array from subscribe variables
195: *
196: * @num = Number of elements
1.1.1.1.2.16 misho 197: * return: NULL error or subscribe array, after use must call mqtt_subFree()
1.1.1.1.2.15 misho 198: */
199: inline mqtt_subscr_t *mqtt_subAlloc(unsigned short num);
1.1.1.1.2.1 misho 200:
1.1.1.1.2.20! misho 201:
! 202: /*** SENDER FUNCTIONS ***/
! 203:
1.1.1.1.2.6 misho 204: /*
205: * mqtt_msgCONNECT() Create CONNECT message
206: *
207: * @buf = Message buffer
208: * @csConnID = ConnectID
209: * @csUser = Username if !=NULL
210: * @csPass = Password for Username, only if csUser is set
211: * @csWillTopic = Will Topic if !=NULL Will Flags set into message
212: * @csWillMessage = Will Message, may be NULL
213: * @ClrSess = Clear Session subscriptions after disconnect
214: * @WillQOS = Will QOS if csWillTopic is set
215: * @WillRetain = Will Retain Will Message if csWillTopic is set
216: * return: -1 error or >-1 message size for send
217: */
218: int mqtt_msgCONNECT(mqtt_msg_t * __restrict buf, const char *csConnID,
219: const char *csUser, const char *csPass,
220: const char *csWillTopic, const char *csWillMessage,
1.1.1.1.2.8 misho 221: unsigned char ClrSess, unsigned char WillQOS, unsigned char WillRetain);
1.1.1.1.2.7 misho 222: /*
223: * mqtt_msgCONNACK() Create CONNACK message
224: *
225: * @buf = Message buffer
226: * @retcode = Return code
227: * return: -1 error or >-1 message size for send
228: */
1.1.1.1.2.8 misho 229: int mqtt_msgCONNACK(mqtt_msg_t * __restrict buf, unsigned char retcode);
1.1.1.1.2.18 misho 230: /*
231: * mqtt_msgDISCONNECT() Create DISCONNECT message
232: *
233: * @buf = Message buffer
234: * return: -1 error or >-1 message size for send
235: */
236: int mqtt_msgDISCONNECT(mqtt_msg_t * __restrict buf);
237: /*
238: * mqtt_msgPINGREQ() Create PINGREQ message
239: *
240: * @buf = Message buffer
241: * return: -1 error or >-1 message size for send
242: */
243: int mqtt_msgPINGREQ(mqtt_msg_t * __restrict buf);
244: /*
245: * mqtt_msgPINGRESP() Create PINGRESP message
246: *
247: * @buf = Message buffer
248: * return: -1 error or >-1 message size for send
249: */
250: int mqtt_msgPINGRESP(mqtt_msg_t * __restrict buf);
1.1.1.1.2.13 misho 251:
1.1.1.1.2.8 misho 252: /*
253: * mqtt_msgPUBLISH() Create PUBLISH message
254: *
255: * @buf = Message buffer
256: * @csTopic = Publish topic
257: * @msgID = MessageID >0, if QOS != MQTT_QOS_ONCE
258: * @Dup = Duplicate message
259: * @QOS = QoS
1.1.1.1.2.10 misho 260: * @Retain = Retain message
1.1.1.1.2.11 misho 261: * @pData = Publish data into topic
262: * @datlen = Publish data length
1.1.1.1.2.8 misho 263: * return: -1 error or >-1 message size for send
264: */
1.1.1.1.2.10 misho 265: int mqtt_msgPUBLISH(mqtt_msg_t * __restrict buf, const char *csTopic, unsigned short msgID,
1.1.1.1.2.11 misho 266: unsigned char Dup, unsigned char QOS, unsigned char Retain,
267: const void *pData, unsigned short datlen);
1.1.1.1.2.8 misho 268: /*
269: * mqtt_msgPUBACK() Create PUBACK message
270: *
271: * @buf = Message buffer
272: * @msgID = MessageID
273: * return: -1 error or >-1 message size for send
274: */
275: inline int mqtt_msgPUBACK(mqtt_msg_t * __restrict buf, unsigned short msgID);
276: /*
277: * mqtt_msgPUBREC() Create PUBREC message
278: *
279: * @buf = Message buffer
280: * @msgID = MessageID
281: * return: -1 error or >-1 message size for send
282: */
283: inline int mqtt_msgPUBREC(mqtt_msg_t * __restrict buf, unsigned short msgID);
284: /*
285: * mqtt_msgPUBREL() Create PUBREL message
286: *
287: * @buf = Message buffer
288: * @msgID = MessageID
289: * return: -1 error or >-1 message size for send
290: */
291: inline int mqtt_msgPUBREL(mqtt_msg_t * __restrict buf, unsigned short msgID);
292: /*
293: * mqtt_msgPUBCOMP() Create PUBCOMP message
294: *
295: * @buf = Message buffer
296: * @msgID = MessageID
297: * return: -1 error or >-1 message size for send
298: */
299: inline int mqtt_msgPUBCOMP(mqtt_msg_t * __restrict buf, unsigned short msgID);
1.1.1.1.2.6 misho 300:
1.1.1.1.2.13 misho 301: /*
302: * mqtt_msgSUBSCRIBE() Create SUBSCRIBE message
303: *
304: * @buf = Message buffer
305: * @Topics = MQTT subscription topics
306: * @msgID = MessageID
307: * @Dup = Duplicate message
308: * @QOS = QoS
309: * return: -1 error or >-1 message size for send
310: */
311: int
312: mqtt_msgSUBSCRIBE(mqtt_msg_t * __restrict buf, mqtt_subscr_t * __restrict Topics,
313: unsigned short msgID, unsigned char Dup, unsigned char QOS);
1.1.1.1.2.15 misho 314: /*
315: * mqtt_msgSUBACK() Create SUBACK message
316: *
317: * @buf = Message buffer
318: * @Topics = MQTT subscription topics
319: * @msgID = MessageID
320: * return: -1 error or >-1 message size for send
321: */
322: int mqtt_msgSUBACK(mqtt_msg_t * __restrict buf, mqtt_subscr_t * __restrict Topics,
323: unsigned short msgID);
1.1.1.1.2.17 misho 324: /*
325: * mqtt_msgUNSUBSCRIBE() Create UNSUBSCRIBE message
326: *
327: * @buf = Message buffer
328: * @Topics = MQTT subscription topics
329: * @msgID = MessageID
330: * @Dup = Duplicate message
331: * @QOS = QoS
332: * return: -1 error or >-1 message size for send
333: */
334: int
335: mqtt_msgUNSUBSCRIBE(mqtt_msg_t * __restrict buf, mqtt_subscr_t * __restrict Topics,
336: unsigned short msgID, unsigned char Dup, unsigned char QOS);
337: /*
338: * mqtt_msgUNSUBACK() Create UNSUBACK message
339: *
340: * @buf = Message buffer
341: * @msgID = MessageID
342: * return: -1 error or >-1 message size for send
343: */
344: int mqtt_msgUNSUBACK(mqtt_msg_t * __restrict buf, unsigned short msgID);
1.1.1.1.2.13 misho 345:
1.1.1.1.2.1 misho 346:
1.1.1.1.2.20! misho 347: /*** RECEIVER FUNCTIONS ***/
! 348:
! 349: /*
! 350: * mqttInitCallbacks() Init callback array for dispatcher
! 351: *
! 352: * return: NULL error or !=NULL allocated callback array, after use free with mqttFiniCallbacks()
! 353: */
! 354: mqtt_cb_t *mqttInitCallbacks(void);
! 355: /*
! 356: * mqttFiniCallbacks() Free callback array
! 357: *
! 358: * @cb = Callback array
! 359: * return: none
! 360: */
! 361: void mqttFiniCallbacks(mqtt_cb_t ** __restrict cb);
! 362:
! 363:
1.1 misho 364: #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