Annotation of mqtt/inc/aitmqtt.h, revision 1.1.1.1.2.11

1.1       misho       1: #ifndef __AITMQTT_H
                      2: #define __AITMQTT_H
                      3: 
                      4: 
1.1.1.1.2.3  misho       5: #define MQTT_DATA_MAX          268435455
1.1.1.1.2.4  misho       6: #define MQTT_CONN_STR          "MQIsdp"
                      7: #define MQTT_PROTO_VER         3
                      8: #define MQTT_KEEPALIVE         10
                      9: 
                     10: /* FIXED HEADER */
1.1.1.1.2.3  misho      11: 
1.1.1.1.2.1  misho      12: struct mqtthdr {
1.1.1.1.2.4  misho      13:        struct {
                     14:                unsigned char   retain:1, 
                     15:                                qos:2,
                     16:                                dup:1,
                     17:                                type:4;
                     18:        } mqtt_msg;
                     19:        unsigned char           mqtt_len[1];    /* may be grow to 4 bytes */
                     20: } __packed;
1.1.1.1.2.1  misho      21: 
                     22: #define MQTT_TYPE_UNKNOWN      0       /* reserved */
                     23: #define MQTT_TYPE_CONNECT      1       /* client request to connect to server */
                     24: #define MQTT_TYPE_CONNACK      2       /* connect acknowledgment */
                     25: #define MQTT_TYPE_PUBLISH      3       /* publish message */
                     26: #define MQTT_TYPE_PUBACK       4       /* publish acknowledgment */
                     27: #define MQTT_TYPE_PUBREC       5       /* publish received (assured delivery part 1) */
                     28: #define MQTT_TYPE_PUBREL       6       /* publish release (assured delivery part 2) */
                     29: #define MQTT_TYPE_PUBCOMP      7       /* publish complete (assured delivery part 3) */
                     30: #define MQTT_TYPE_SUBSCRIBE    8       /* client subscribe request */
                     31: #define MQTT_TYPE_SUBACK       9       /* subscribe acknowledgment */
                     32: #define MQTT_TYPE_UNSUBSCRIBE  10      /* client unsubscribe request */
                     33: #define MQTT_TYPE_UNSUBACK     11      /* unsubscribe acknowledgment */
                     34: #define MQTT_TYPE_PINGREQ      12      /* PING request */
                     35: #define MQTT_TYPE_PINGRESP     13      /* PING response */
                     36: #define MQTT_TYPE_DISCONNECT   14      /* client is disconnecting */
                     37: #define MQTT_TYPE_RESERVED     15      /* reserved */
                     38: 
                     39: #define MQTT_FLAG_DUP          1       /* This flag is set when the client or server attempts to re-deliver 
                     40:                                           a PUBLISH, PUBREL, SUBSCRIBE or UNSUBSCRIBE message. 
                     41:                                           This applies to messages where the value of QoS is greater than 
                     42:                                           zero (0), and an acknowledgment is required. 
                     43:                                           When the DUP bit is set, the variable header includes a Message ID.
                     44: 
                     45:                                           The recipient should treat this flag as a hint as to whether 
                     46:                                           the message may have been previously received. 
                     47:                                           It should not be relied on to detect duplicates. */
                     48: 
                     49: #define MQTT_QOS_ONCE          0       /* At most once, Fire and Forget, <=1 */
                     50: #define MQTT_QOS_ACK           1       /* At least once, Acknowledged delivery, >=1 */
                     51: #define MQTT_QOS_EXACTLY       2       /* Exactly once, Assured delivery, =1 */
                     52: #define MQTT_QOS_RESERVED      3       /* reserved */
                     53: 
                     54: #define MQTT_FLAG_RETAIN       1       /* This flag is only used on PUBLISH messages.
                     55: 
                     56:                                           When a client sends a PUBLISH to a server, 
                     57:                                           if the Retain flag is set (1), 
                     58:                                           the server should hold on to the message after it has been 
                     59:                                           delivered to the current subscribers.
                     60:                                           When a new subscription is established on a topic, 
                     61:                                           the last retained message on that topic should be sent to 
                     62:                                           the subscriber with the Retain flag set.
                     63:                                           If there is no retained message, nothing is sent
                     64:                                           This is useful where publishers send messages on a 
                     65:                                           "report by exception" basis, where it might be some time between messages. 
                     66:                                           This allows new subscribers to instantly receive data with the retained, 
                     67:                                           or Last Known Good, value.
                     68: 
                     69:                                           When a server sends a PUBLISH to a client as a result of 
                     70:                                           a subscription that already existed when the original PUBLISH arrived, 
                     71:                                           the Retain flag should not be set, regardless of the Retain flag 
                     72:                                           of the original PUBLISH. This allows a client to distinguish messages 
                     73:                                           that are being received because they were retained and those 
                     74:                                           that are being received "live".
                     75: 
                     76:                                           Retained messages should be kept over restarts of the server.
                     77:                                           A server may delete a retained message if it receives a message 
                     78:                                           with a zero-length payload and the Retain flag set on the same topic. */
                     79: 
1.1.1.1.2.4  misho      80: /* VARIABLE HEADERS */
                     81: 
                     82: #define MQTT_RETCODE_ACCEPTED          0
                     83: #define MQTT_RETCODE_REFUSE_VER                1
                     84: #define MQTT_RETCODE_REFUSE_ID         2
                     85: #define MQTT_RETCODE_REFUSE_UNAVAIL    3
                     86: #define MQTT_RETCODE_REFUSE_USERPASS   4
                     87: #define MQTT_RETCODE_DENIED            5
                     88: 
                     89: 
                     90: typedef union {
                     91:        struct {
                     92:                unsigned short  m:8,
                     93:                                l:8;
                     94:        } sb;
                     95:        unsigned short  val;
1.1.1.1.2.5  misho      96: } mqtt_v_t;
1.1.1.1.2.4  misho      97: 
                     98: typedef struct {
1.1.1.1.2.5  misho      99:        mqtt_v_t        var_sb;
1.1.1.1.2.4  misho     100:        unsigned char   var_data[0];
                    101: } __packed mqtthdr_var_t;
1.1.1.1.2.5  misho     102: #define MQTTHDR_VAR_SIZEOF(x)          (assert((x)), sizeof(mqtt_v_t) + ntohs((x)->var_sb.val))
1.1.1.1.2.4  misho     103: 
                    104: typedef unsigned char mqtthdr_protover_t;
                    105: typedef unsigned char mqtthdr_retcode_t;
                    106: 
                    107: typedef struct {
                    108:        unsigned char   reserved:1,
                    109:                        clean_sess:1,
                    110:                        will_flg:1,
                    111:                        will_qos:2,
                    112:                        will_retain:1,
                    113:                        password:1,
                    114:                        username:1;
                    115: } __packed mqtthdr_connflgs_t;
                    116: 
1.1.1.1.2.7  misho     117: typedef struct {
                    118:        unsigned char   reserved;
                    119:        unsigned char   retcode;
                    120: } __packed mqtthdr_connack_t;
                    121: 
1.1.1.1.2.1  misho     122: 
1.1.1.1.2.5  misho     123: /* MQTT Message buffer */
                    124: 
                    125: typedef struct {
                    126:        void            *msg_base;
                    127:        unsigned short  msg_len;
                    128: } mqtt_msg_t;
                    129: 
                    130: 
1.1       misho     131: // -------------------------------------------------------
                    132: // mqtt_GetErrno() Get error code of last operation
                    133: inline int mqtt_GetErrno();
                    134: // mqtt_GetError() Get error text of last operation
                    135: inline const char *mqtt_GetError();
                    136: // -------------------------------------------------------
                    137: 
                    138: 
1.1.1.1.2.1  misho     139: /*
1.1.1.1.2.5  misho     140:  * mqtt_msgAlloc() Allocate memory for MQTT Message
                    141:  * @len = >0 Allocate buffer with length
                    142:  * return: NULL error or Message, after use must call mqtt_msgFree() with all!=0
                    143:  */
                    144: inline mqtt_msg_t *mqtt_msgAlloc(unsigned short len);
                    145: /*
                    146:  * mqtt_msgFree() Free MQTT message
                    147:  * @msg = Message buffer
                    148:  * @all = !=0 Destroy entire message, if MQTT Message allocated with mqtt_msgAlloc()
                    149:  * return: none
                    150:  */
                    151: inline void mqtt_msgFree(mqtt_msg_t ** __restrict msg, int all);
                    152: /*
                    153:  * mqtt_msgRealloc() Reallocate MQTT message buffer
                    154:  * @msg = MQTT message
                    155:  * @len = new length
                    156:  * return: -1 error or >-1 old buffer length
                    157:  */
                    158: inline int mqtt_msgRealloc(mqtt_msg_t * __restrict msg, unsigned short len);
                    159: 
                    160: /*
1.1.1.1.2.1  misho     161:  * mqtt_encodeLen() Encode number to MQTT length field
                    162:  * @num = number for encode
                    163:  * return: -1 error or >-1 length
                    164:  */
                    165: inline unsigned int mqtt_encodeLen(unsigned int num);
                    166: /*
                    167:  * mqtt_decodeLen() Decode length from MQTT packet
                    168:  * @len = length
1.1.1.1.2.2  misho     169:  * @n = sizeof bytes, if !=NULL
1.1.1.1.2.1  misho     170:  * return: -1 error, >-1 length of message
                    171:  */
1.1.1.1.2.2  misho     172: inline unsigned int mqtt_decodeLen(unsigned int len, char *n);
                    173: /*
                    174:  * mqtt_sizeLen Return sizeof len field
                    175:  * @len = length
                    176:  * return: -1 error, >-1 sizeof len in bytes
                    177:  */
                    178: inline char mqtt_sizeLen(unsigned int len);
1.1.1.1.2.4  misho     179: /*
                    180:  * mqtt_str2var Create MQTT variable from string
                    181:  * @csStr = string
                    182:  * @strLen = string length
                    183:  * return: NULL error or != ok variable, must be free after use!
                    184:  */
                    185: inline mqtthdr_var_t *mqtt_str2var(const unsigned char *csStr, unsigned short strLen);
1.1.1.1.2.1  misho     186: 
1.1.1.1.2.6  misho     187: /*
                    188:  * mqtt_msgCONNECT() Create CONNECT message
                    189:  *
                    190:  * @buf = Message buffer
                    191:  * @csConnID = ConnectID
                    192:  * @csUser = Username if !=NULL
                    193:  * @csPass = Password for Username, only if csUser is set
                    194:  * @csWillTopic = Will Topic if !=NULL Will Flags set into message
                    195:  * @csWillMessage = Will Message, may be NULL
                    196:  * @ClrSess = Clear Session subscriptions after disconnect
                    197:  * @WillQOS = Will QOS if csWillTopic is set
                    198:  * @WillRetain = Will Retain Will Message if csWillTopic is set
                    199:  * return: -1 error or >-1 message size for send
                    200:  */
                    201: int mqtt_msgCONNECT(mqtt_msg_t * __restrict buf, const char *csConnID, 
                    202:                const char *csUser, const char *csPass, 
                    203:                const char *csWillTopic, const char *csWillMessage, 
1.1.1.1.2.8  misho     204:                unsigned char ClrSess, unsigned char WillQOS, unsigned char WillRetain);
1.1.1.1.2.7  misho     205: /*
                    206:  * mqtt_msgCONNACK() Create CONNACK message
                    207:  *
                    208:  * @buf = Message buffer
                    209:  * @retcode = Return code
                    210:  * return: -1 error or >-1 message size for send
                    211:  */
1.1.1.1.2.8  misho     212: int mqtt_msgCONNACK(mqtt_msg_t * __restrict buf, unsigned char retcode);
                    213: /*
                    214:  * mqtt_msgPUBLISH() Create PUBLISH message
                    215:  *
                    216:  * @buf = Message buffer
                    217:  * @csTopic = Publish topic
                    218:  * @msgID = MessageID >0, if QOS != MQTT_QOS_ONCE
                    219:  * @Dup = Duplicate message
                    220:  * @QOS = QoS
1.1.1.1.2.10  misho     221:  * @Retain = Retain message
1.1.1.1.2.11! misho     222:  * @pData = Publish data into topic
        !           223:  * @datlen = Publish data length
1.1.1.1.2.8  misho     224:  * return: -1 error or >-1 message size for send
                    225:  */
1.1.1.1.2.10  misho     226: int mqtt_msgPUBLISH(mqtt_msg_t * __restrict buf, const char *csTopic, unsigned short msgID, 
1.1.1.1.2.11! misho     227:                unsigned char Dup, unsigned char QOS, unsigned char Retain, 
        !           228:                const void *pData, unsigned short datlen);
1.1.1.1.2.8  misho     229: /*
                    230:  * mqtt_msgPUBACK() Create PUBACK message
                    231:  *
                    232:  * @buf = Message buffer
                    233:  * @msgID = MessageID
                    234:  * return: -1 error or >-1 message size for send
                    235:  */
                    236: inline int mqtt_msgPUBACK(mqtt_msg_t * __restrict buf, unsigned short msgID);
                    237: /*
                    238:  * mqtt_msgPUBREC() Create PUBREC message
                    239:  *
                    240:  * @buf = Message buffer
                    241:  * @msgID = MessageID
                    242:  * return: -1 error or >-1 message size for send
                    243:  */
                    244: inline int mqtt_msgPUBREC(mqtt_msg_t * __restrict buf, unsigned short msgID);
                    245: /*
                    246:  * mqtt_msgPUBREL() Create PUBREL message
                    247:  *
                    248:  * @buf = Message buffer
                    249:  * @msgID = MessageID
                    250:  * return: -1 error or >-1 message size for send
                    251:  */
                    252: inline int mqtt_msgPUBREL(mqtt_msg_t * __restrict buf, unsigned short msgID);
                    253: /*
                    254:  * mqtt_msgPUBCOMP() Create PUBCOMP message
                    255:  *
                    256:  * @buf = Message buffer
                    257:  * @msgID = MessageID
                    258:  * return: -1 error or >-1 message size for send
                    259:  */
                    260: inline int mqtt_msgPUBCOMP(mqtt_msg_t * __restrict buf, unsigned short msgID);
1.1.1.1.2.6  misho     261: 
1.1.1.1.2.1  misho     262: 
1.1       misho     263: #endif

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>