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>