MQTT

MQTT is a machine-to-machine (M2M)/"Internet of Things" connectivity protocol. More...

Data Structures
struct	sol_mqtt_config
	Server Configuration. More...
struct	sol_mqtt_handlers
	MQTT callback handlers. More...
struct	sol_mqtt_message
	MQTT Message. More...

Macros
#define	SOL_MQTT_MESSAGE_CHECK_API_VERSION(msg_,...)
	Macro used to check if a struct struct sol_mqtt_message has the expected API version. More...

Typedefs
typedef struct sol_mqtt	sol_mqtt
	MQTT Object. More...
typedef struct sol_mqtt_config	sol_mqtt_config
	Server Configuration. More...
typedef struct sol_mqtt_handlers	sol_mqtt_handlers
	MQTT callback handlers. More...
typedef struct sol_mqtt_message	sol_mqtt_message
	MQTT Message. More...

Enumerations
enum	sol_mqtt_conn_status {   SOL_MQTT_DISCONNECTED = -1, SOL_MQTT_CONNECTED = 0, SOL_MQTT_WRONG_PROTOCOL = 1, SOL_MQTT_ID_REJECTED = 2,   SOL_MQTT_UNAVAILABLE = 3 }
	Connection status. More...
enum	sol_mqtt_qos { SOL_MQTT_QOS_AT_MOST_ONCE = 0, SOL_MQTT_QOS_AT_LEAST_ONCE = 1, SOL_MQTT_QOS_EXACTLY_ONCE = 2 }
	MQTT QOS level for message delivery. More...

Functions
struct sol_mqtt *	sol_mqtt_connect (const struct sol_mqtt_config *config)
	Connect to a MQTT broker. More...
void	sol_mqtt_disconnect (struct sol_mqtt *mqtt)
	Disconnect from MQTT Broker. More...
int	sol_mqtt_get_connection_status (const struct sol_mqtt *mqtt)
	Get connection status. More...
int	sol_mqtt_publish (const struct sol_mqtt *mqtt, struct sol_mqtt_message *message)
	Send the Broker a message to be published in a given topic. More...
int	sol_mqtt_reconnect (struct sol_mqtt *mqtt)
	Reestablish the connection to the MQTT broker. More...
int	sol_mqtt_subscribe (const struct sol_mqtt *mqtt, const char *topic, sol_mqtt_qos qos)
	Ask the Broker to be subscribed to a given topic. More...

Detailed Description

MQTT is a machine-to-machine (M2M)/"Internet of Things" connectivity protocol.

It was designed as an extremely lightweight publish/subscribe messaging transport. It is useful for connections with remote locations where a small code footprint is required and/or network bandwidth is at a premium. For example, it has been used in sensors communicating to a broker via satellite link, over occasional dial-up connections with healthcare providers, and in a range of home automation and small device scenarios. It is also ideal for mobile applications because of its small size, low power usage, minimised data packets, and efficient distribution of information to one or many receivers

Macro Definition Documentation

#define SOL_MQTT_MESSAGE_CHECK_API_VERSION	(		msg_,
			...
	)

Value:

if (SOL_UNLIKELY((msg_)->api_version != \
        SOL_MQTT_MESSAGE_API_VERSION)) { \
        SOL_ERR("Unexpected API version (message is %" PRIu16 ", expected %" PRIu16 ")", \
            (msg_)->api_version, SOL_MQTT_MESSAGE_API_VERSION); \
        return __VA_ARGS__; \
    }

Macro used to check if a struct struct sol_mqtt_message has the expected API version.

In case it has wrong version, it'll return extra arguments passed to the macro.

Typedef Documentation

sol_mqtt

MQTT Object.

See Also

sol_mqtt_connect

This object is the abstraction of a MQTT session. This is the base structure for all MQTT operations and is obtained through the sol_mqtt_connect() API.

typedef struct sol_mqtt_config sol_mqtt_config

Server Configuration.

typedef struct sol_mqtt_handlers sol_mqtt_handlers

MQTT callback handlers.

typedef struct sol_mqtt_message sol_mqtt_message

MQTT Message.

This object is the abstraction of a MQTT message and is the base for publishing and receiving data to/from the broker.

Enumeration Type Documentation

enum sol_mqtt_conn_status

Connection status.

Enumerator
SOL_MQTT_DISCONNECTED	Disconnected due to unexpected reasons.
SOL_MQTT_CONNECTED	Successfully connected to the broker.
SOL_MQTT_WRONG_PROTOCOL	MQTT protocol rejected by the broker.
SOL_MQTT_ID_REJECTED	Client ID rejected by the broker.
SOL_MQTT_UNAVAILABLE	Broker unavailable at provided host.

enum sol_mqtt_qos

MQTT QOS level for message delivery.

Enumerator
SOL_MQTT_QOS_AT_MOST_ONCE	The message is delivered according to the capabilities of the underlying network. No response is sent by the receiver and no retry is performed by the sender. The message arrives at the receiver either once or not at all.
SOL_MQTT_QOS_AT_LEAST_ONCE	This quality of service ensures that the message arrives at the receiver at least once. A QoS 1 PUBLISH Packet has a Packet Identifier in its variable header and is acknowledged by a PUBACK Packet.
SOL_MQTT_QOS_EXACTLY_ONCE	This is the highest quality of service, for use when neither loss nor duplication of messages are acceptable. There is an increased overhead associated with this quality of service.

Function Documentation

struct sol_mqtt* sol_mqtt_connect

(

const struct sol_mqtt_config *

config

)

Connect to a MQTT broker.

Parameters

config

Configuration and callbacks

Returns

New mqtt object on success, NULL otherwise

Examples:

/src/samples/iio+network/iio-gyroscope-console-and-mqtt-publish.c, /src/samples/mqtt/mqtt-publish.c, and /src/samples/mqtt/mqtt-subscribe.c.

Referenced by main().

void sol_mqtt_disconnect

(

struct sol_mqtt *

mqtt

)

Disconnect from MQTT Broker.

Parameters

mqtt	MQTT Object;

See Also

sol_mqtt_connect

Terminate the connection to the broker and free the resources associated to the mqtt object.

Examples:

/src/samples/iio+network/iio-gyroscope-console-and-mqtt-publish.c, /src/samples/mqtt/mqtt-publish.c, and /src/samples/mqtt/mqtt-subscribe.c.

Referenced by main().

int sol_mqtt_get_connection_status

(

const struct sol_mqtt *

mqtt

)

Get connection status.

Parameters

mqtt	MQTT Object

See Also

sol_mqtt_conn_status

Returns

sol_mqtt_conn_status code

Examples:

/src/samples/iio+network/iio-gyroscope-console-and-mqtt-publish.c, /src/samples/mqtt/mqtt-publish.c, and /src/samples/mqtt/mqtt-subscribe.c.

Referenced by iio_gyroscope_reader_cb(), and on_connect().

int sol_mqtt_publish	(	const struct sol_mqtt *	mqtt,
		struct sol_mqtt_message *	message
	)

Send the Broker a message to be published in a given topic.

Parameters

mqtt	MQTT Object
message	Message to be published. The memory associated to this object should be handled by the caller.

Returns

0 on success, -EINVAL otherwise

Examples:

/src/samples/iio+network/iio-gyroscope-console-and-mqtt-publish.c, and /src/samples/mqtt/mqtt-publish.c.

Referenced by iio_gyroscope_reader_cb(), and publish_callback().

int sol_mqtt_reconnect

(

struct sol_mqtt *

mqtt

)

Reestablish the connection to the MQTT broker.

Parameters

mqtt	MQTT Object

Returns

0 on success, -EINVAL otherwise

Examples:

/src/samples/iio+network/iio-gyroscope-console-and-mqtt-publish.c, /src/samples/mqtt/mqtt-publish.c, and /src/samples/mqtt/mqtt-subscribe.c.

Referenced by try_reconnect().

int sol_mqtt_subscribe	(	const struct sol_mqtt *	mqtt,
		const char *	topic,
		sol_mqtt_qos	qos
	)

Ask the Broker to be subscribed to a given topic.

Parameters

mqtt	MQTT Object
topic	Null terminated string with the topic to subscribe to
qos	MQTT QOS that should be used by the subscribe message

Returns

0 on success, -EINVAL otherwise

Examples:

/src/samples/mqtt/mqtt-subscribe.c.

Referenced by on_connect().