Annotation of libaitmqtt/inc/mqttapi.h, revision 1.3.2.1

1.2       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.2.1 ! misho       6: * $Id: mqttapi.h,v 1.3 2012/06/29 13:54:48 misho Exp $
1.2       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: 
                     15: Copyright 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012
                     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 __MQTTAPI_H
                     47: #define __MQTTAPI_H
                     48: 
                     49: 
                     50: #include "aitmqtt.h"
                     51: 
                     52: 
                     53: #ifdef API_SERVER_SIDE
                     54: /* MQTT server structure & hooks */
                     55: 
                     56: /* MQTT command callback. 1st argument is (mqtt_srv_t*) server handle, 2nd is ready length */
                     57: typedef int (*mqtt_cb_t)(void* /*mqtt_srv_t**/, int, void *);
                     58: typedef struct {
                     59:        mqtt_cb_t       cmds[MQTT_TYPE_MAX];
                     60: 
                     61:        int             sock;
                     62:        unsigned short  timeout;
                     63:        mqtt_msg_t      *buf;
                     64: } mqtt_srv_t;
                     65: #define mqtt_srv_setCmd(x, _cmd, _func)        (assert((x)), (x)->cmds[(_cmd)] = (_func))
                     66: #define mqtt_srv_getCmd(x, _cmd)       (assert((x)), (x)->cmds[(_cmd)])
                     67: 
                     68: 
                     69: /*
1.3       misho      70:  * mqtt_srv_cliInit() Init MQTT server side support for clients
1.2       misho      71:  *
                     72:  * @sock = Client socket from accept()
                     73:  * @buf = Message buffer
                     74:  * @timeout = timeout
1.3       misho      75:  * @nb = Non block socket
1.2       misho      76:  * return: NULL error or !=NULL allocated server handle
                     77:  */
1.3       misho      78: mqtt_srv_t *mqtt_srv_cliInit(int sock, mqtt_msg_t * __restrict buf, 
                     79:                unsigned short timeout, int nb);
1.2       misho      80: /*
1.3       misho      81:  * mqtt_srv_Fini() Finish MQTT server side support for clients
1.2       misho      82:  *
                     83:  * @psrv = Server handle
                     84:  * return: none
                     85:  */
1.3       misho      86: void mqtt_srv_cliFini(mqtt_srv_t ** __restrict psrv);
1.2       misho      87: /*
1.3       misho      88:  * mqtt_srv_Dispatch() MQTT server dispatcher for clients
1.2       misho      89:  *
                     90:  * @srv = Server handle
                     91:  * @rlen = Ready bytes to parse
                     92:  * @arg = Argument pass to command callback
                     93:  * return: -1 error or 0 ok
                     94:  */
1.3       misho      95: int mqtt_srv_cliDispatch(mqtt_srv_t * __restrict srv, int rlen, void *arg);
                     96: 
                     97: /*
                     98:  * mqtt_srv_Create() - Create server socket
                     99:  *
                    100:  * @sa = Server bind address
                    101:  * @salen = Server struct sockaddr size
                    102:  * return: -1 error or >-1 server socket
                    103:  */
                    104: int mqtt_srv_Create(struct sockaddr * __restrict sa, int salen);
                    105: /*
                    106:  * mqtt_srv_Destroy() - Close server socket
                    107:  *
                    108:  * @sock = Server socket
                    109:  * return: -1 error or 0 ok
                    110:  */
                    111: int mqtt_srv_Destroy(int sock);
                    112: /*
                    113:  * mqtt_srv_Listen() - Listen server socket
                    114:  *
                    115:  * @sock = Server socket
                    116:  * @maxconn = max number of pending connections
                    117:  * @nb = Non block socket
                    118:  * return: -1 error or 0 ok
                    119:  */
                    120: int mqtt_srv_Listen(int sock, int maxconn, int nb);
1.2       misho     121: #endif
                    122: 
                    123: /*
                    124:  * mqtt_KeepAlive() - Keep Alive check routine
                    125:  *
                    126:  * @sock = connected socket
                    127:  * @ka = keep alive timeout
                    128:  * @tries = tries for receive correct ping response, usually ==1
                    129:  * return: -1 error, 0 host is alive, 1 timeout session or 2 broken session
                    130:  */
                    131: int mqtt_KeepAlive(int sock, unsigned short ka, unsigned char tries);
1.3.2.1 ! misho     132: /*
        !           133:  * mqtt_WillMessage() - Publish WILL message
        !           134:  *
        !           135:  * @sock = connected socket
        !           136:  * @ka = keep alive timeout
        !           137:  * @topic = will topic
        !           138:  * @data = will message
        !           139:  * return: -1 error, 1 timeout, 2 not ack or 0 ok
        !           140:  */
        !           141: int mqtt_WillMessage(int sock, unsigned short ka, const char *topic, const char *data);
1.2       misho     142: 
                    143: 
                    144: #ifdef API_CLIENT_SIDE
                    145: /* MQTT client structure */
                    146: 
                    147: typedef struct {
                    148:        int             sock;
                    149:        unsigned short  timeout;
                    150:        mqtt_msg_t      *buf;
                    151: } mqtt_cli_t;
                    152: 
                    153: 
                    154: /*
                    155:  * mqtt_cli_Open() - Open client connection to MQTT broker
                    156:  *
                    157:  * @addr = brokers address
                    158:  * @timeout = timeout
                    159:  * return: NULL error or !=NULL connected to broker
                    160:  */
                    161: mqtt_cli_t *mqtt_cli_Open(struct sockaddr *addr, unsigned short timeout);
                    162: /*
                    163:  * mqtt_cli_Close() - Close client connection
                    164:  *
                    165:  * @cli = connected client
                    166:  * return: -1 error or 0 disconnected client and freed all resources
                    167:  */
                    168: int mqtt_cli_Close(mqtt_cli_t ** __restrict cli);
                    169: 
                    170: /*
                    171:  * mqtt_cli_Subscribe() - Subscribe to broker
                    172:  *
                    173:  * @cli = connected client
                    174:  * @Topics = Topics for subscribes
                    175:  * @msgID = Message ID
                    176:  * @Dup = Duplicated request
                    177:  * @QoS = Message QoS
                    178:  * return: NULL error or !=NULL allocated array with subscribed QoS responses, 
                    179:  *     must be free() result!
                    180:  */
                    181: unsigned char *mqtt_cli_Subscribe(mqtt_cli_t * __restrict cli, 
                    182:                mqtt_subscr_t * __restrict Topics, unsigned short msgID, 
                    183:                unsigned char Dup, unsigned char QoS);
                    184: /*
                    185:  * mqtt_cli_Unsubscribe() - Unsubscribe from broker
                    186:  *
                    187:  * @cli = connected client
                    188:  * @Topics = Topics for unsubscribes
                    189:  * @msgID = Message ID
                    190:  * @Dup = Duplicated request
                    191:  * @QoS = Message QoS
                    192:  * return: -1 error or 0 ok
                    193:  */
                    194: int mqtt_cli_Unsubscribe(mqtt_cli_t * __restrict cli, 
                    195:                mqtt_subscr_t * __restrict Topics, unsigned short msgID, 
                    196:                unsigned char Dup, unsigned char QoS);
                    197: /*
                    198:  * mqtt_cli_Publish() - Publish message to broker
                    199:  *
                    200:  * @cli = connected client
                    201:  * @msgID = Message ID
                    202:  * @Dup = Duplicated request
                    203:  * @QoS = Message QoS
                    204:  * @Retain = Retain message
                    205:  * @csTopic = Topic
                    206:  * @pData = Data
                    207:  * @datLen = Data length
                    208:  * return: -1 error or > -1 sended bytes
                    209:  */
                    210: int mqtt_cli_Publish(mqtt_cli_t * __restrict cli, unsigned short msgID, 
                    211:                unsigned char Dup, unsigned char QoS, unsigned char Retain, 
                    212:                const char *csTopic, const void *pData, int datLen);
                    213: #endif
                    214: 
                    215: 
                    216: #endif

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