Mistake on this page?
Report an issue in GitHub or email us
mqtt.h
Go to the documentation of this file.
1 /**
2  * @file
3  * MQTT client
4  */
5 
6 /*
7  * Copyright (c) 2016 Erik Andersson
8  * All rights reserved.
9  *
10  * Redistribution and use in source and binary forms, with or without modification,
11  * are permitted provided that the following conditions are met:
12  *
13  * 1. Redistributions of source code must retain the above copyright notice,
14  * this list of conditions and the following disclaimer.
15  * 2. Redistributions in binary form must reproduce the above copyright notice,
16  * this list of conditions and the following disclaimer in the documentation
17  * and/or other materials provided with the distribution.
18  * 3. The name of the author may not be used to endorse or promote products
19  * derived from this software without specific prior written permission.
20  *
21  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED
22  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
23  * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
24  * SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
25  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
26  * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
27  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
28  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
29  * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
30  * OF SUCH DAMAGE.
31  *
32  * This file is part of the lwIP TCP/IP stack.
33  *
34  * Author: Erik Andersson
35  *
36  */
37 #ifndef LWIP_HDR_APPS_MQTT_CLIENT_H
38 #define LWIP_HDR_APPS_MQTT_CLIENT_H
39 
40 #include "lwip/apps/mqtt_opts.h"
41 #include "lwip/err.h"
42 #include "lwip/ip_addr.h"
43 #include "lwip/prot/iana.h"
44 
45 #ifdef __cplusplus
46 extern "C" {
47 #endif
48 
49 typedef struct mqtt_client_s mqtt_client_t;
50 
51 #if LWIP_ALTCP && LWIP_ALTCP_TLS
52 struct altcp_tls_config;
53 #endif
54 
55 /** @ingroup mqtt
56  * Default MQTT port (non-TLS) */
57 #define MQTT_PORT LWIP_IANA_PORT_MQTT
58 /** @ingroup mqtt
59  * Default MQTT TLS port */
60 #define MQTT_TLS_PORT LWIP_IANA_PORT_SECURE_MQTT
61 
62 /*---------------------------------------------------------------------------------------------- */
63 /* Connection with server */
64 
65 /**
66  * @ingroup mqtt
67  * Client information and connection parameters */
69  /** Client identifier, must be set by caller */
70  const char *client_id;
71  /** User name, set to NULL if not used */
72  const char* client_user;
73  /** Password, set to NULL if not used */
74  const char* client_pass;
75  /** keep alive time in seconds, 0 to disable keep alive functionality*/
76  u16_t keep_alive;
77  /** will topic, set to NULL if will is not to be used,
78  will_msg, will_qos and will retain are then ignored */
79  const char* will_topic;
80  /** will_msg, see will_topic */
81  const char* will_msg;
82  /** will_qos, see will_topic */
83  u8_t will_qos;
84  /** will_retain, see will_topic */
86 #if LWIP_ALTCP && LWIP_ALTCP_TLS
87  /** TLS configuration for secure connections */
88  struct altcp_tls_config *tls_config;
89 #endif
90 };
91 
92 /**
93  * @ingroup mqtt
94  * Connection status codes */
95 typedef enum
96 {
97  /** Accepted */
99  /** Refused protocol version */
101  /** Refused identifier */
103  /** Refused server */
105  /** Refused user credentials */
107  /** Refused not authorized */
109  /** Disconnected */
111  /** Timeout */
114 
115 /**
116  * @ingroup mqtt
117  * Function prototype for mqtt connection status callback. Called when
118  * client has connected to the server after initiating a mqtt connection attempt by
119  * calling mqtt_client_connect() or when connection is closed by server or an error
120  *
121  * @param client MQTT client itself
122  * @param arg Additional argument to pass to the callback function
123  * @param status Connect result code or disconnection notification @see mqtt_connection_status_t
124  *
125  */
126 typedef void (*mqtt_connection_cb_t)(mqtt_client_t *client, void *arg, mqtt_connection_status_t status);
127 
128 
129 /**
130  * @ingroup mqtt
131  * Data callback flags */
132 enum {
133  /** Flag set when last fragment of data arrives in data callback */
135 };
136 
137 /**
138  * @ingroup mqtt
139  * Function prototype for MQTT incoming publish data callback function. Called when data
140  * arrives to a subscribed topic @see mqtt_subscribe
141  *
142  * @param arg Additional argument to pass to the callback function
143  * @param data User data, pointed object, data may not be referenced after callback return,
144  NULL is passed when all publish data are delivered
145  * @param len Length of publish data fragment
146  * @param flags MQTT_DATA_FLAG_LAST set when this call contains the last part of data from publish message
147  *
148  */
149 typedef void (*mqtt_incoming_data_cb_t)(void *arg, const u8_t *data, u16_t len, u8_t flags);
150 
151 
152 /**
153  * @ingroup mqtt
154  * Function prototype for MQTT incoming publish function. Called when an incoming publish
155  * arrives to a subscribed topic @see mqtt_subscribe
156  *
157  * @param arg Additional argument to pass to the callback function
158  * @param topic Zero terminated Topic text string, topic may not be referenced after callback return
159  * @param tot_len Total length of publish data, if set to 0 (no publish payload) data callback will not be invoked
160  */
161 typedef void (*mqtt_incoming_publish_cb_t)(void *arg, const char *topic, u32_t tot_len);
162 
163 
164 /**
165  * @ingroup mqtt
166  * Function prototype for mqtt request callback. Called when a subscribe, unsubscribe
167  * or publish request has completed
168  * @param arg Pointer to user data supplied when invoking request
169  * @param err ERR_OK on success
170  * ERR_TIMEOUT if no response was received within timeout,
171  * ERR_ABRT if (un)subscribe was denied
172  */
173 typedef void (*mqtt_request_cb_t)(void *arg, err_t err);
174 
175 
176 err_t mqtt_client_connect(mqtt_client_t *client, const ip_addr_t *ipaddr, u16_t port, mqtt_connection_cb_t cb, void *arg,
177  const struct mqtt_connect_client_info_t *client_info);
178 
179 void mqtt_disconnect(mqtt_client_t *client);
180 
181 mqtt_client_t *mqtt_client_new(void);
182 void mqtt_client_free(mqtt_client_t* client);
183 
184 u8_t mqtt_client_is_connected(mqtt_client_t *client);
185 
186 void mqtt_set_inpub_callback(mqtt_client_t *client, mqtt_incoming_publish_cb_t,
187  mqtt_incoming_data_cb_t data_cb, void *arg);
188 
189 err_t mqtt_sub_unsub(mqtt_client_t *client, const char *topic, u8_t qos, mqtt_request_cb_t cb, void *arg, u8_t sub);
190 
191 /** @ingroup mqtt
192  *Subscribe to topic */
193 #define mqtt_subscribe(client, topic, qos, cb, arg) mqtt_sub_unsub(client, topic, qos, cb, arg, 1)
194 /** @ingroup mqtt
195  * Unsubscribe to topic */
196 #define mqtt_unsubscribe(client, topic, cb, arg) mqtt_sub_unsub(client, topic, 0, cb, arg, 0)
197 
198 err_t mqtt_publish(mqtt_client_t *client, const char *topic, const void *payload, u16_t payload_length, u8_t qos, u8_t retain,
199  mqtt_request_cb_t cb, void *arg);
200 
201 #ifdef __cplusplus
202 }
203 #endif
204 
205 #endif /* LWIP_HDR_APPS_MQTT_CLIENT_H */
u8_t will_qos
will_qos, see will_topic
Definition: mqtt.h:83
Accepted.
Definition: mqtt.h:98
const char * will_topic
will topic, set to NULL if will is not to be used, will_msg, will_qos and will retain are then ignore...
Definition: mqtt.h:79
Refused identifier.
Definition: mqtt.h:102
Refused server.
Definition: mqtt.h:104
Timeout.
Definition: mqtt.h:112
void(* mqtt_request_cb_t)(void *arg, err_t err)
Function prototype for mqtt request callback.
Definition: mqtt.h:173
const char * client_user
User name, set to NULL if not used.
Definition: mqtt.h:72
Refused not authorized.
Definition: mqtt.h:108
Refused user credentials.
Definition: mqtt.h:106
MQTT client.
Definition: mqtt_priv.h:70
u16_t keep_alive
keep alive time in seconds, 0 to disable keep alive functionality
Definition: mqtt.h:76
lwIP Error codes
MQTT client options.
mqtt_connection_status_t
Connection status codes.
Definition: mqtt.h:95
u8_t will_retain
will_retain, see will_topic
Definition: mqtt.h:85
Client information and connection parameters.
Definition: mqtt.h:68
IANA assigned numbers (RFC 1700 and successors)
Disconnected.
Definition: mqtt.h:110
void(* mqtt_connection_cb_t)(mqtt_client_t *client, void *arg, mqtt_connection_status_t status)
Function prototype for mqtt connection status callback.
Definition: mqtt.h:126
const char * client_pass
Password, set to NULL if not used.
Definition: mqtt.h:74
IP address structure for passing IP addresses by value.
Definition: nsapi_types.h:190
const char * will_msg
will_msg, see will_topic
Definition: mqtt.h:81
Refused protocol version.
Definition: mqtt.h:100
const char * client_id
Client identifier, must be set by caller.
Definition: mqtt.h:70
void(* mqtt_incoming_publish_cb_t)(void *arg, const char *topic, u32_t tot_len)
Function prototype for MQTT incoming publish function.
Definition: mqtt.h:161
void(* mqtt_incoming_data_cb_t)(void *arg, const u8_t *data, u16_t len, u8_t flags)
Function prototype for MQTT incoming publish data callback function.
Definition: mqtt.h:149
Flag set when last fragment of data arrives in data callback.
Definition: mqtt.h:134
IP address API (common IPv4 and IPv6)
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.