Annotation of libaitmqtt/inc/aitmqtt.h, revision 1.3.4.11

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 $
1.3.4.11! misho       6: * $Id: aitmqtt.h,v 1.3.4.10 2022/09/14 17:37:13 misho Exp $
1.1       misho       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: 
1.3.4.2   misho      15: Copyright 2004 - 2022
1.1       misho      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: 
1.3.4.7   misho      50: #define MQTT_CONNID_MAX                24
                     51: #define MQTT_CRED_MAX          13
1.3.4.2   misho      52: #define MQTTMSG_MAX            65535
1.3.4.3   misho      53: #define MQTTMSG_BIN_MAX                65535
1.2       misho      54: #define MQTT_DATA_MAX          268435455
                     55: 
1.3.4.8   misho      56: #define MQTT_PROTO_VER_3       3
                     57: #define MQTT_PROTO_VER_311     4
                     58: #define MQTT_PROTO_VER_5       5
                     59: #define MQTT_KEEPALIVE         60
1.2       misho      60: 
1.1       misho      61: /* FIXED HEADER */
                     62: 
                     63: struct mqtthdr {
                     64:        union {
                     65:                struct {
                     66:                        unsigned char   retain:1, 
                     67:                                        qos:2,
                     68:                                        dup:1,
                     69:                                        type:4;
                     70:                };
                     71:                unsigned char           val;
                     72:        } mqtt_msg;
                     73:        unsigned char                   mqtt_len[1];    /* may be grow to 4 bytes */
1.3.4.1   misho      74: } __attribute__((packed));
1.3.4.6   misho      75: #define MQTTHDR_MSGINIT(x)     (assert((x)), (x)->mqtt_msg.val ^= (x)->mqtt_msg.val, *(x)->mqtt_len = 0)
1.2       misho      76: #define MQTTHDR_DATA_SIZEOF(x) (assert((x)), mqtt_decodeLen((x)->mqtt_len, NULL))
1.1       misho      77: 
1.3.4.8   misho      78: typedef union {
                     79:        struct {
                     80:                unsigned short  m:8,
                     81:                                l:8;
                     82:        } sb;
                     83:        unsigned short  val;
                     84: } __attribute__((packed)) mqtt_len_t;
                     85: 
                     86: typedef struct {
                     87:        mqtt_len_t      var_sb;
                     88:        unsigned char   var_data[0];
                     89: } __attribute__((packed)) mqtthdr_var_t;
                     90: #define MQTTHDR_VAR_SIZEOF(x)          (assert((x)), sizeof(mqtt_len_t) + ntohs((x)->var_sb.val))
                     91: 
                     92: typedef union {
                     93:        struct {
                     94:                unsigned char   reserved:1,
                     95:                                clean_sess:1,
                     96:                                will_flg:1,
                     97:                                will_qos:2,
                     98:                                will_retain:1,
                     99:                                password:1,
                    100:                                username:1;
                    101:        };
                    102:        unsigned char           flags;
                    103: } __attribute__((packed)) mqtthdr_connflgs_t;
                    104: 
                    105: typedef struct {
                    106:        unsigned char   reserved;
                    107:        unsigned char   retcode;
                    108: } __attribute__((packed)) mqtthdr_connack_t;
                    109: 
1.1       misho     110: #define MQTT_TYPE_UNKNOWN      0       /* reserved */
1.3.4.3   misho     111: #define MQTT_TYPE_CONNECT      1       /* client request to connect to server (CLI) */
1.3.4.4   misho     112: #define MQTT_TYPE_CONNACK      2       /* connect acknowledgment (SRV) [ret_no_data] */
                    113: #define MQTT_TYPE_PUBLISH      3       /* publish message [ret_is_optional] */
                    114: #define MQTT_TYPE_PUBACK       4       /* publish acknowledgment [ret_no_data] */
                    115: #define MQTT_TYPE_PUBREC       5       /* publish received (assured delivery part 1) [ret_no_data] */
                    116: #define MQTT_TYPE_PUBREL       6       /* publish release (assured delivery part 2) [ret_no_data] */
                    117: #define MQTT_TYPE_PUBCOMP      7       /* publish complete (assured delivery part 3) [ret_no_data] */
1.3.4.3   misho     118: #define MQTT_TYPE_SUBSCRIBE    8       /* client subscribe request (CLI) */
                    119: #define MQTT_TYPE_SUBACK       9       /* subscribe acknowledgment (SRV) */
                    120: #define MQTT_TYPE_UNSUBSCRIBE  10      /* client unsubscribe request (CLI) */
                    121: #define MQTT_TYPE_UNSUBACK     11      /* unsubscribe acknowledgment (SRV) */
1.3.4.4   misho     122: #define MQTT_TYPE_PINGREQ      12      /* PING request (CLI) [ret_no_data] */
                    123: #define MQTT_TYPE_PINGRESP     13      /* PING response (SRV) [ret_no_data] */
                    124: #define MQTT_TYPE_DISCONNECT   14      /* client is disconnecting [ret_no_data] */
                    125: #define MQTT_TYPE_AUTH         15      /* authentication exchange [ret_no_data] */
1.3.4.3   misho     126: 
                    127: #define MQTT_TYPE_MAX          15
1.1       misho     128: 
                    129: #define MQTT_FLAG_DUP          1       /* This flag is set when the client or server attempts to re-deliver 
                    130:                                           a PUBLISH, PUBREL, SUBSCRIBE or UNSUBSCRIBE message. 
                    131:                                           This applies to messages where the value of QoS is greater than 
                    132:                                           zero (0), and an acknowledgment is required. 
                    133:                                           When the DUP bit is set, the variable header includes a Message ID.
                    134: 
                    135:                                           The recipient should treat this flag as a hint as to whether 
                    136:                                           the message may have been previously received. 
                    137:                                           It should not be relied on to detect duplicates. */
                    138: 
                    139: #define MQTT_QOS_ONCE          0       /* At most once, Fire and Forget, <=1 */
                    140: #define MQTT_QOS_ACK           1       /* At least once, Acknowledged delivery, >=1 */
                    141: #define MQTT_QOS_EXACTLY       2       /* Exactly once, Assured delivery, =1 */
                    142: #define MQTT_QOS_RESERVED      3       /* reserved */
                    143: 
1.2       misho     144: #define MQTT_QOS_DENY          0       /* Not granted QoS for SUBACK */
                    145: #define MQTT_QOS_PASS          2       /* Granted QoS for SUBACK */
                    146: 
1.1       misho     147: #define MQTT_FLAG_RETAIN       1       /* This flag is only used on PUBLISH messages.
                    148: 
                    149:                                           When a client sends a PUBLISH to a server, 
                    150:                                           if the Retain flag is set (1), 
                    151:                                           the server should hold on to the message after it has been 
                    152:                                           delivered to the current subscribers.
                    153:                                           When a new subscription is established on a topic, 
                    154:                                           the last retained message on that topic should be sent to 
                    155:                                           the subscriber with the Retain flag set.
                    156:                                           If there is no retained message, nothing is sent
                    157:                                           This is useful where publishers send messages on a 
                    158:                                           "report by exception" basis, where it might be some time between messages. 
                    159:                                           This allows new subscribers to instantly receive data with the retained, 
                    160:                                           or Last Known Good, value.
                    161: 
                    162:                                           When a server sends a PUBLISH to a client as a result of 
                    163:                                           a subscription that already existed when the original PUBLISH arrived, 
                    164:                                           the Retain flag should not be set, regardless of the Retain flag 
                    165:                                           of the original PUBLISH. This allows a client to distinguish messages 
                    166:                                           that are being received because they were retained and those 
                    167:                                           that are being received "live".
                    168: 
                    169:                                           Retained messages should be kept over restarts of the server.
                    170:                                           A server may delete a retained message if it receives a message 
                    171:                                           with a zero-length payload and the Retain flag set on the same topic. */
                    172: 
                    173: /* VARIABLE HEADERS */
                    174: 
                    175: #define MQTT_RETCODE_ACCEPTED          0
                    176: #define MQTT_RETCODE_REFUSE_VER                1
                    177: #define MQTT_RETCODE_REFUSE_ID         2
                    178: #define MQTT_RETCODE_REFUSE_UNAVAIL    3
                    179: #define MQTT_RETCODE_REFUSE_USERPASS   4
                    180: #define MQTT_RETCODE_DENIED            5
                    181: 
1.3.4.4   misho     182: /* REASON CODES */
                    183: 
                    184: #define MQTT_REASON_OK                 0x0     /* CONNACK, PUBACK, PUBREC, PUBREL, PUBCOMP, UNSUBACK, AUTH, DISCONNECT, SUBACK */
                    185: #define MQTT_REASON_QOS1               0x1     /* SUBACK */
                    186: #define MQTT_REASON_QOS2               0x2     /* SUBACK */
                    187: #define MQTT_REASON_DWILL              0x4     /* DISCONNECT */
                    188: #define MQTT_REASON_NOMATCH            0x10    /* PUBACK, PUBREC */
                    189: #define MQTT_REASON_NOSUBEXIST         0x11    /* UNSUBACK */
                    190: #define MQTT_REASON_CONTAUTH           0x18    /* AUTH */
                    191: #define MQTT_REASON_REAUTH             0x19    /* AUTH */
                    192: 
                    193: /* REASON ERROR CODES */
                    194: 
                    195: #define MQTT_REASON_ERROR              0x80    /* CONNACK, PUBACK, PUBREC, SUBACK, UNSUBACK, DISCONNECT */
                    196: #define MQTT_REASON_MALFORMPKT         0x81    /* CONNACK, DISCONNECT */
                    197: #define MQTT_REASON_PROTOERR           0x82    /* CONNACK, DISCONNECT */
                    198: #define MQTT_REASON_IMPLSPECERR                0x83    /* CONNACK, PUBACK, PUBREC, SUBACK, UNSUBACK, DISCONNECT */
                    199: #define MQTT_REASON_UNSUPVERPROTO      0x84    /* CONNACK */
                    200: #define MQTT_REASON_CLINOVALID         0x85    /* CONNACK */
                    201: #define MQTT_REASON_BADUSERPASS                0x86    /* CONNACK */
                    202: #define MQTT_REASON_NOAUTH             0x87    /* CONNACK, PUBACK, PUBREC, SUBACK, UNSUBACK, DISCONNECT */
                    203: #define MQTT_REASON_SRVUNAVAIL         0x88    /* CONNACK */
                    204: #define MQTT_REASON_SRVBUSY            0x89    /* CONNACK, DISCONNECT */
                    205: #define MQTT_REASON_BANNED             0x8A    /* CONNACK */
                    206: #define MQTT_REASON_SRVSHUTDOWN                0x8B    /* DISCONNECT */
                    207: #define MQTT_REASON_BADAUTHMETHOD      0x8C    /* CONNACK, DISCONNECT */
                    208: #define MQTT_REASON_KEEPALIVETO                0x8D    /* DISCONNECT */
                    209: #define MQTT_REASON_SESTAKEOVER                0x8E    /* DISCONNECT */
                    210: #define MQTT_REASON_TOPICFLTINVAL      0x8F    /* SUBACK, UNSUBACK, DISCONNECT */
                    211: #define MQTT_REASON_TOPICNAMEINV       0x90    /* CONNACK, PUBACK, PUBREC, DISCONNECT */
                    212: #define MQTT_REASON_PKTIDINUSE         0x91    /* PUBACK, PUBREC, SUBACK, UNSUBACK */
                    213: #define MQTT_REASON_PKTIDNOTFOUND      0x92    /* PUBREL, PUBCOMP */
                    214: #define MQTT_REASON_RCVMAXEXCEED       0x93    /* DISCONNECT */
                    215: #define MQTT_REASON_TOPICALIASINV      0x94    /* DISCONNECT */
                    216: #define MQTT_REASON_PKTTOOLARGE                0x95    /* CONNACK, DISCONNECT */
                    217: #define MQTT_REASON_MSGRATETOHIGH      0x96    /* DISCONNECT */
                    218: #define MQTT_REASON_QUOTAEXCEED                0x97    /* CONNACK, PUBACK, PUBREC, SUBACK, DISCONNECT */
                    219: #define MQTT_REASON_ADMINACTION                0x98    /* DISCONNECT */
                    220: #define MQTT_REASON_PAYLOADFMTINV      0x99    /* CONNACK, PUBACK, PUBREC, DISCONNECT */
                    221: #define MQTT_REASON_RETAINNOTSUP       0x9A    /* CONNACK, DISCONNECT */
                    222: #define MQTT_REASON_QOSNOTSUP          0x9B    /* CONNACK, DISCONNECT */
                    223: #define MQTT_REASON_USENEXTSRV         0x9C    /* CONNACK, DISCONNECT */
                    224: #define MQTT_REASON_SRVMOVED           0x9D    /* CONNACK, DISCONNECT */
                    225: #define MQTT_REASON_SHARSUBNOTSUP      0x9E    /* SUBACK, DISCONNECT */
                    226: #define MQTT_REASON_CONRATEEXCEED      0x9F    /* CONNACK, DISCONNECT */
                    227: #define MQTT_REASON_MAXCONNTIME                0xA0    /* DISCONNECT */
                    228: #define MQTT_REASON_SUBIDNOTSUP                0xA1    /* SUBACK, DISCONNECT */
                    229: #define MQTT_RESON_WILDSUBNOTSUP       0xA2    /* SUBACK, DISCONNECT */
1.1       misho     230: 
                    231: /* MQTT Message buffer */
                    232: 
                    233: typedef struct {
                    234:        void            *msg_base;
1.3.4.6   misho     235:        unsigned int    msg_len;
1.1       misho     236: } mqtt_msg_t;
                    237: 
                    238: /* MQTT structures */
                    239: 
                    240: typedef struct {
                    241:        unsigned char   sub_ret;
                    242:        mqtt_msg_t      sub_topic;
                    243:        mqtt_msg_t      sub_value;
                    244: } mqtt_subscr_t;
                    245: 
                    246: 
                    247: // -------------------------------------------------------
                    248: // mqtt_GetErrno() Get error code of last operation
1.3       misho     249: int mqtt_GetErrno();
1.1       misho     250: // mqtt_GetError() Get error text of last operation
1.3       misho     251: const char *mqtt_GetError();
1.1       misho     252: // -------------------------------------------------------
                    253: 
                    254: 
                    255: /*
                    256:  * mqtt_msgAlloc() Allocate memory for MQTT Message
                    257:  *
                    258:  * @len = >0 Allocate buffer with length
                    259:  * return: NULL error or Message, after use must call mqtt_msgFree() with all!=0
                    260:  */
1.3.4.6   misho     261: mqtt_msg_t *mqtt_msgAlloc(unsigned int len);
1.1       misho     262: /*
                    263:  * mqtt_msgFree() Free MQTT message
                    264:  *
                    265:  * @msg = Message buffer
1.3.4.8   misho     266:  * @keepmsg = !=0 just free message content
1.1       misho     267:  * return: none
                    268:  */
1.3.4.8   misho     269: void mqtt_msgFree(mqtt_msg_t ** __restrict msg, int keepmsg);
1.1       misho     270: /*
                    271:  * mqtt_msgRealloc() Reallocate MQTT message buffer
                    272:  *
                    273:  * @msg = MQTT message
                    274:  * @len = new length
                    275:  * return: -1 error or >-1 old buffer length
                    276:  */
1.3.4.6   misho     277: int mqtt_msgRealloc(mqtt_msg_t * __restrict msg, unsigned int len);
1.2       misho     278: /*
                    279:  * mqtt_msgDup() - Duplicate message buffer
                    280:  *
                    281:  * @msg = Message
                    282:  * return: NULL error or !=NULL duplicated message, after use must call mqtt_msgFree() with all!=0
                    283:  */
1.3       misho     284: mqtt_msg_t *mqtt_msgDup(mqtt_msg_t * __restrict msg);
1.2       misho     285: 
                    286: /*
                    287:  * mqtt_expandTopic() - Expanding topic to regular expression
                    288:  *
                    289:  * @csInput = Input topic
                    290:  * @psRegEx = Output to regular expression
                    291:  * @regexLen = Length of psRegEx
                    292:  * @BOL = Begin of Line, if =0 not added
                    293:  * @EOL = End of Line, if =0 not appended
                    294:  * return: -1 error, 0 nothing expanded or >0 expanded bytes
                    295:  */
                    296: int mqtt_expandTopic(const char *csInput, char * __restrict psRegEx, int regexLen, 
                    297:                unsigned char BOL, unsigned char EOL);
                    298: /*
                    299:  * mqtt_sqlTopic() - Expanding topic to SQL search string
                    300:  *
                    301:  * @csInput = Input topic
                    302:  * @psSQL = Output to SQL search string
                    303:  * @sqlLen = Length of psSQL
                    304:  * return: -1 error, 0 changed bytes
                    305:  */
                    306: int mqtt_sqlTopic(const char *csInput, char * __restrict psSQL, int sqlLen);
1.1       misho     307: 
                    308: /*
                    309:  * mqtt_encodeLen() Encode number to MQTT length field
                    310:  *
                    311:  * @num = number for encode
                    312:  * return: -1 error or >-1 length
                    313:  */
1.3       misho     314: unsigned int mqtt_encodeLen(unsigned int num);
1.1       misho     315: /*
                    316:  * mqtt_decodeLen() Decode length from MQTT packet
                    317:  *
                    318:  * @len = length from MQTT header
                    319:  * @n = sizeof bytes, if !=NULL
                    320:  * return: -1 error, >-1 length of message
                    321:  */
1.3       misho     322: unsigned int mqtt_decodeLen(void * __restrict len, int * __restrict n);
1.1       misho     323: /*
                    324:  * mqtt_sizeLen Return sizeof len field
                    325:  *
                    326:  * @len = length
                    327:  * return: -1 error, >-1 sizeof len in bytes
                    328:  */
1.3       misho     329: char mqtt_sizeLen(unsigned int len);
1.1       misho     330: /*
1.2       misho     331:  * mqtt_pktLen() - Get total packet length
1.1       misho     332:  *
1.2       misho     333:  * @hdr = MQTT packet header
                    334:  * return: packet length
                    335:  */
1.3       misho     336: unsigned int mqtt_pktLen(struct mqtthdr * __restrict hdr);
1.2       misho     337: /*
1.3.4.6   misho     338:  * mqtt_strs2subs Create MQTT subscribe variable from string(s)
1.2       misho     339:  *
                    340:  * @csStr = null terminated string array
1.3.4.6   misho     341:  * @strnum = copy at most number of strings elements, ==0 till NULL element
1.1       misho     342:  * @qoses = QoS elements applied to subscribe variable, 
                    343:  *             count of elements must be equal with csStr elements
                    344:  * return: NULL error or != subscribe variables array, must be free after use with mqtt_freeSub()
                    345:  */
1.3.4.6   misho     346: mqtt_subscr_t *mqtt_strs2subs(const char **csStr, unsigned short strnum, unsigned char *qoses);
1.1       misho     347: /*
                    348:  * mqtt_subFree() Free array from subscribe variables
                    349:  *
                    350:  * @subs = Subscribe variables
                    351:  * return: none
                    352:  */
1.3       misho     353: void mqtt_subFree(mqtt_subscr_t ** __restrict subs);
1.1       misho     354: /*
                    355:  * mqtt_subAlloc() Create array from subscribe variables
                    356:  *
                    357:  * @num = Number of elements
                    358:  * return: NULL error or subscribe array, after use must call mqtt_subFree()
                    359:  */
1.3       misho     360: mqtt_subscr_t *mqtt_subAlloc(unsigned short num);
1.1       misho     361: /*
                    362:  * mqtt_subRealloc() Reallocate array from subscribe variables
                    363:  *
                    364:  * @subs = Subscribe array
                    365:  * @num = Number of elements
                    366:  * return: NULL error or subscribe array, after use must call mqtt_subFree()
                    367:  */
1.3       misho     368: mqtt_subscr_t *mqtt_subRealloc(mqtt_subscr_t ** __restrict subs, unsigned short num);
1.2       misho     369: /*
                    370:  * mqtt_subCopy() - Copy subscription structure to another one
                    371:  *
                    372:  * @dst = destination subscription
                    373:  * @src = source subscription
                    374:  * return: =NULL error or !=NULL successful copied a structure
                    375:  */
1.3       misho     376: mqtt_subscr_t *mqtt_subCopy(mqtt_subscr_t * __restrict dst, mqtt_subscr_t * __restrict src);
1.1       misho     377: 
                    378: 
                    379: /*** SENDER FUNCTIONS ***/
                    380: 
                    381: /*
                    382:  * mqtt_msgCONNECT() Create CONNECT message
                    383:  *
                    384:  * @csConnID = ConnectID
1.3.4.9   misho     385:  * @Version = MQTT version, if =0 default version is 3.1.1
1.3.4.8   misho     386:  * @KASec = Keep alive timeout, if =0 default timeout for MQTT
1.1       misho     387:  * @csUser = Username if !=NULL
                    388:  * @csPass = Password for Username, only if csUser is set
                    389:  * @csWillTopic = Will Topic if !=NULL Will Flags set into message
                    390:  * @csWillMessage = Will Message, may be NULL
                    391:  * @ClrSess = Clear Session subscriptions after disconnect
                    392:  * @WillQOS = Will QOS if csWillTopic is set
                    393:  * @WillRetain = Will Retain Will Message if csWillTopic is set
1.3.4.9   misho     394:  * return: NULL error or allocated CONNECT message
1.1       misho     395:  */
1.3.4.8   misho     396: mqtt_msg_t *mqtt_msgCONNECT(const char *csConnID, unsigned char Version, 
                    397:                unsigned short KASec, const char *csUser, const char *csPass, 
1.1       misho     398:                const char *csWillTopic, const char *csWillMessage, 
                    399:                unsigned char ClrSess, unsigned char WillQOS, unsigned char WillRetain);
                    400: /*
                    401:  * mqtt_msgCONNACK() Create CONNACK message
                    402:  *
                    403:  * @retcode = Return code
1.3.4.9   misho     404:  * return: NULL error or allocated CONNACK message
1.1       misho     405:  */
1.3.4.9   misho     406: mqtt_msg_t *mqtt_msgCONNACK(unsigned char retcode);
1.1       misho     407: /*
                    408:  * mqtt_msgDISCONNECT() Create DISCONNECT message
                    409:  *
1.3.4.9   misho     410:  * return: NULL error or allocated message
1.1       misho     411:  */
1.3.4.9   misho     412: mqtt_msg_t *mqtt_msgDISCONNECT();
1.1       misho     413: /*
                    414:  * mqtt_msgPINGREQ() Create PINGREQ message
                    415:  *
1.3.4.9   misho     416:  * return: NULL error or allocated message
1.1       misho     417:  */
1.3.4.9   misho     418: mqtt_msg_t *mqtt_msgPINGREQ();
1.1       misho     419: /*
                    420:  * mqtt_msgPINGRESP() Create PINGRESP message
                    421:  *
1.3.4.9   misho     422:  * return: NULL error or allocated message
1.1       misho     423:  */
1.3.4.9   misho     424: mqtt_msg_t *mqtt_msgPINGRESP();
1.1       misho     425: 
                    426: /*
                    427:  * mqtt_msgPUBLISH() Create PUBLISH message
                    428:  *
                    429:  * @csTopic = Publish topic
                    430:  * @msgID = MessageID >0, if QOS != MQTT_QOS_ONCE
                    431:  * @Dup = Duplicate message
                    432:  * @QOS = QoS
                    433:  * @Retain = Retain message
                    434:  * @pData = Publish data into topic
                    435:  * @datlen = Publish data length
1.3.4.10  misho     436:  * return: NULL error or allocated PUBLISH message
1.1       misho     437:  */
1.3.4.10  misho     438: mqtt_msg_t *mqtt_msgPUBLISH(const char *csTopic, unsigned short msgID, 
                    439:                unsigned char Dup, unsigned char QOS, 
1.1       misho     440:                unsigned char Retain, const void *pData, int datlen);
                    441: /*
                    442:  * mqtt_msgPUBACK() Create PUBACK message
                    443:  *
                    444:  * @msgID = MessageID
1.3.4.10  misho     445:  * return: NULL error or allocated PUBACK message
1.1       misho     446:  */
1.3.4.10  misho     447: mqtt_msg_t *mqtt_msgPUBACK(unsigned short msgID);
1.1       misho     448: /*
                    449:  * mqtt_msgPUBREC() Create PUBREC message
                    450:  *
                    451:  * @msgID = MessageID
1.3.4.10  misho     452:  * return: NULL error or allocated PUBREC message
1.1       misho     453:  */
1.3.4.10  misho     454: mqtt_msg_t *mqtt_msgPUBREC(unsigned short msgID);
1.1       misho     455: /*
                    456:  * mqtt_msgPUBREL() Create PUBREL message
                    457:  *
                    458:  * @msgID = MessageID
1.3.4.10  misho     459:  * return: NULL error or allocated PUBREL message
1.1       misho     460:  */
1.3.4.10  misho     461: mqtt_msg_t *mqtt_msgPUBREL(unsigned short msgID);
1.1       misho     462: /*
                    463:  * mqtt_msgPUBCOMP() Create PUBCOMP message
                    464:  *
                    465:  * @msgID = MessageID
1.3.4.10  misho     466:  * return: NULL error or allocated PUBCOMP message
1.1       misho     467:  */
1.3.4.10  misho     468: mqtt_msg_t *mqtt_msgPUBCOMP(unsigned short msgID);
1.1       misho     469: 
                    470: /*
                    471:  * mqtt_msgSUBSCRIBE() Create SUBSCRIBE message
                    472:  *
                    473:  * @Topics = MQTT subscription topics
                    474:  * @msgID = MessageID
                    475:  * @Dup = Duplicate message
                    476:  * @QOS = QoS
1.3.4.11! misho     477:  * return: NULL error or allocated SUBSCRIBE message
1.1       misho     478:  */
1.3.4.11! misho     479: mqtt_msg_t *mqtt_msgSUBSCRIBE(mqtt_subscr_t ** __restrict Topics, 
1.1       misho     480:                unsigned short msgID, unsigned char Dup, unsigned char QOS);
                    481: /*
                    482:  * mqtt_msgSUBACK() Create SUBACK message
                    483:  *
                    484:  * @Topics = MQTT subscription topics
                    485:  * @msgID = MessageID
1.3.4.11! misho     486:  * return: NULL error or allocated SUBACK message
1.1       misho     487:  */
1.3.4.11! misho     488: mqtt_msg_t *mqtt_msgSUBACK(mqtt_subscr_t ** __restrict Topics, unsigned short msgID);
1.1       misho     489: /*
                    490:  * mqtt_msgUNSUBSCRIBE() Create UNSUBSCRIBE message
                    491:  *
                    492:  * @Topics = MQTT subscription topics
                    493:  * @msgID = MessageID
                    494:  * @Dup = Duplicate message
                    495:  * @QOS = QoS
1.3.4.11! misho     496:  * return: NULL error or allocated UNSUBSCRIBE message
1.1       misho     497:  */
1.3.4.11! misho     498: mqtt_msg_t *mqtt_msgUNSUBSCRIBE(mqtt_subscr_t ** __restrict Topics, 
1.1       misho     499:                unsigned short msgID, unsigned char Dup, unsigned char QOS);
                    500: /*
                    501:  * mqtt_msgUNSUBACK() Create UNSUBACK message
                    502:  *
                    503:  * @msgID = MessageID
1.3.4.11! misho     504:  * return: NULL error or allocated UNSUBACK message
1.1       misho     505:  */
1.3.4.11! misho     506: mqtt_msg_t *mqtt_msgUNSUBACK(unsigned short msgID);
1.1       misho     507: 
                    508: 
                    509: /*** RECEIVER FUNCTIONS ***/
                    510: 
                    511: /*
                    512:  * mqtt_readCONNECT() Read elements from CONNECT message
                    513:  *
                    514:  * @buf = Message buffer
1.3.4.9   misho     515:  * @KASec = Keep Alive in seconds for current connection
1.1       misho     516:  * @psConnID = ConnectID
                    517:  * @connLen = ConnectID length
                    518:  * @psUser = Username if !=NULL
                    519:  * @userLen = Username length
                    520:  * @psPass = Password for Username, only if csUser is set
                    521:  * @passLen = Password length
                    522:  * @psWillTopic = Will Topic if !=NULL Will Flags set into message and must be free()
                    523:  * @psWillMessage = Will Message, may be NULL if !NULL must be free() after use!
                    524:  * return: .reserved == 1 is error or == 0 connection flags & msg ok
                    525:  */
1.3.4.9   misho     526: mqtthdr_connack_t mqtt_readCONNECT(mqtt_msg_t * __restrict buf, unsigned short *KASec, 
1.1       misho     527:                char * __restrict psConnID, int connLen, 
                    528:                char * __restrict psUser, int userLen, char * __restrict psPass, int passLen,  
                    529:                char ** __restrict psWillTopic, char ** __restrict psWillMessage);
                    530: /*
                    531:  * mqtt_readCONNACK() Read CONNACK message
                    532:  *
                    533:  * @buf = Message buffer
                    534:  * return: -1 error or >-1 CONNECT message return code
                    535:  */
                    536: unsigned char mqtt_readCONNACK(mqtt_msg_t * __restrict buf);
                    537: /*
                    538:  * mqtt_readDISCONNECT() Read DISCONNECT message
                    539:  *
                    540:  * @buf = Message buffer
                    541:  * return: -1 error, 0 ok, >0 undefined result
                    542:  */
                    543: int mqtt_readDISCONNECT(mqtt_msg_t * __restrict buf);
                    544: /*
                    545:  * mqtt_readPINGREQ() Read PINGREQ message
                    546:  *
                    547:  * @buf = Message buffer
                    548:  * return: -1 error, 0 ok, >0 undefined result
                    549:  */
                    550: int mqtt_readPINGREQ(mqtt_msg_t * __restrict buf);
                    551: /*
                    552:  * mqtt_readPINGRESP() Read PINGRESP message
                    553:  *
                    554:  * @buf = Message buffer
                    555:  * return: -1 error, 0 ok, >0 undefined result
                    556:  */
                    557: int mqtt_readPINGRESP(mqtt_msg_t * __restrict buf);
                    558: 
                    559: /*
                    560:  * mqtt_readPUBLISH() Read PUBLISH message
                    561:  *
                    562:  * @buf = Message buffer
                    563:  * @psTopic = Topic
                    564:  * @topicLen = Topic length
                    565:  * @msgID = MessageID
1.2       misho     566:  * @pData = Data buffer, may be NULL
                    567:  * return: -1 error or !=-1 allocated data buffer length
1.1       misho     568:  */
1.2       misho     569: int mqtt_readPUBLISH(mqtt_msg_t * __restrict buf, char * __restrict psTopic, 
                    570:                int topicLen, unsigned short *msgID, void ** __restrict pData);
1.1       misho     571: /*
                    572:  * mqtt_readPUBACK() Read PUBACK message
                    573:  *
                    574:  * @buf = Message buffer
                    575:  * return: -1 error or MessageID
                    576:  */
1.2       misho     577: unsigned short mqtt_readPUBACK(mqtt_msg_t * __restrict buf);
1.1       misho     578: /*
                    579:  * mqtt_readPUBREC() Read PUBREC message
                    580:  *
                    581:  * @buf = Message buffer
                    582:  * return: -1 error or MessageID
                    583:  */
1.2       misho     584: unsigned short mqtt_readPUBREC(mqtt_msg_t * __restrict buf);
1.1       misho     585: /*
                    586:  * mqtt_readPUBREL() Read PUBREL message
                    587:  *
                    588:  * @buf = Message buffer
                    589:  * return: -1 error or MessageID
                    590:  */
1.2       misho     591: unsigned short mqtt_readPUBREL(mqtt_msg_t * __restrict buf);
1.1       misho     592: /*
                    593:  * mqtt_readPUBCOMP() Read PUBCOMP message
                    594:  *
                    595:  * @buf = Message buffer
                    596:  * return: -1 error or MessageID
                    597:  */
1.2       misho     598: unsigned short mqtt_readPUBCOMP(mqtt_msg_t * __restrict buf);
1.1       misho     599: 
                    600: /*
                    601:  * mqtt_readSUBSCRIBE() Read SUBSCRIBE message
                    602:  *
                    603:  * @buf = Message buffer
                    604:  * @msgID = MessageID
                    605:  * @subscr = Subscriptions, must be free after use with mqtt_subFree()
1.2       misho     606:  * return: -1 error or >-1 elements into subscr
1.1       misho     607:  */
1.2       misho     608: int mqtt_readSUBSCRIBE(mqtt_msg_t * __restrict buf, unsigned short *msgID, 
1.1       misho     609:                mqtt_subscr_t **subscr);
                    610: /*
                    611:  * mqtt_readSUBACK() Read SUBACK message
                    612:  *
                    613:  * @buf = Message buffer
                    614:  * @msgID = MessageID
                    615:  * @subqos = Subscribes QoS, must be free after use with free()
                    616:  * return: -1 error or >-1 readed subscribes QoS elements
                    617:  */
1.2       misho     618: int mqtt_readSUBACK(mqtt_msg_t * __restrict buf, unsigned short *msgID, unsigned char **subqos);
1.1       misho     619: /*
                    620:  * mqtt_readUNSUBSCRIBE() Read UNSUBSCRIBE message
                    621:  *
                    622:  * @buf = Message buffer
                    623:  * @msgID = MessageID
                    624:  * @subscr = Subscriptions, must be free after use with mqtt_subFree()
1.2       misho     625:  * return: -1 error or >-1 elements into subscr
1.1       misho     626:  */
1.2       misho     627: int mqtt_readUNSUBSCRIBE(mqtt_msg_t * __restrict buf, unsigned short *msgID, 
1.1       misho     628:                mqtt_subscr_t **subscr);
                    629: /*
                    630:  * mqtt_readUNSUBACK() Read UNSUBACK message
                    631:  *
                    632:  * @buf = Message buffer
                    633:  * return: -1 error or MessageID
                    634:  */
1.2       misho     635: unsigned short mqtt_readUNSUBACK(mqtt_msg_t * __restrict buf);
1.1       misho     636: 
                    637: 
                    638: #endif

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