MQTT

MQTT protocol management interface. More...

Collaboration diagram for MQTT:

Data Structures
union	net_mqtt_t
	Opaque MQTT handle. More...

Typedefs
typedef union net_mqtt_t	net_mqtt_t
	Opaque MQTT handle. More...
typedef void(*	net_mqtt_connect_callback_t) (net_mqtt_t *mqtt, net_mqtt_status_t status, void *user_data)
	Callback invoked on connection state changes and errors. More...

Enumerations
enum	net_mqtt_status_t {   net_mqtt_status_connected_t, net_mqtt_status_disconnected_t, net_mqtt_status_dns_error_t = (1 << 2), net_mqtt_status_protocol_error_t,   net_mqtt_status_auth_error_t, net_mqtt_status_timeout_t, net_mqtt_status_error_t }
	Connection/event status flags for MQTT operations. More...

Functions
net_mqtt_t	net_mqtt_init (net_mqtt_connect_callback_t connect, void *user_data)
	Create and initialize an MQTT handle. More...
bool	net_mqtt_valid (net_mqtt_t *mqtt)
	Check whether an MQTT client is valid and connected. More...
void	net_mqtt_finalize (net_mqtt_t *mqtt)
	Finalize the MQTT handle and free associated resources. More...
bool	net_mqtt_connect (net_mqtt_t *mqtt, const char *hostname, uint16_t port, const char *client_id, const char *user, const char *password, uint16_t keepalive_secs, const char *will_topic, const char *will_message)
	Begin an asynchronous connection to an MQTT broker. More...
bool	net_mqtt_disconnect (net_mqtt_t *mqtt)
	Begin an asynchronous disconnect from the MQTT broker. More...
bool	net_mqtt_publish (net_mqtt_t *mqtt, const char *topic, const void *data, size_t size, uint8_t qos)
	Publish a message to a topic. More...
static bool	net_mqtt_publish_str (net_mqtt_t *mqtt, const char *topic, const char *str, uint8_t qos)
	Publish a NULL-terminated string to a topic. More...
bool	net_mqtt_subscribe (net_mqtt_t *mqtt, const char *topic, uint8_t qos)
	Subscribe to a topic. More...

Detailed Description

MQTT protocol management interface.

The MQTT management interface provides methods for connecting to and interacting with MQTT brokers. The main methods for publishing and subscribing to topics are asynchronous and call the provided callback function to update operation status.

Typedef Documentation

net_mqtt_connect_callback_t

typedef void(* net_mqtt_connect_callback_t) (net_mqtt_t *mqtt, net_mqtt_status_t status, void *user_data)

Callback invoked on connection state changes and errors.

Parameters

mqtt	The MQTT instance that generated the event.
status	One or more net_mqtt_status_t flags describing the event. Typically a single flag such as net_mqtt_status_connected_t or net_mqtt_status_disconnected_t.
user_data	Opaque pointer supplied at initialization time. Not interpreted by the runtime.

Definition at line 72 of file mqtt.h.

net_mqtt_t

typedef union net_mqtt_t net_mqtt_t

Opaque MQTT handle.

A fixed-size opaque handle that contains implementation-defined state. It is safe to pass by value.

Enumeration Type Documentation

net_mqtt_status_t

enum net_mqtt_status_t

Connection/event status flags for MQTT operations.

Enumerator
net_mqtt_status_connected_t	Connected to the broker and session is active.
net_mqtt_status_disconnected_t	Disconnected from the broker (remote close or local request).
net_mqtt_status_dns_error_t	DNS resolution failed.
net_mqtt_status_protocol_error_t	Protocol-level error (malformed packet, unsupported feature, etc).
net_mqtt_status_auth_error_t	Authentication failure (bad client ID/username/password).
net_mqtt_status_timeout_t	Operation timed out (connect or in-flight request exceeded deadline).
net_mqtt_status_error_t	Generic error occurred (e.g., connection failed).

Definition at line 40 of file mqtt.h.

             {
  net_mqtt_status_connected_t =
      (1 << 0), 
  net_mqtt_status_disconnected_t =
      (1 << 1), 
  net_mqtt_status_dns_error_t = (1 << 2), 
  net_mqtt_status_protocol_error_t =
      (1 << 3), 
  net_mqtt_status_auth_error_t =
      (1
       << 4), 
  net_mqtt_status_timeout_t =
      (1 << 5), 
  net_mqtt_status_error_t =
      (1 << 6), 
} net_mqtt_status_t;

Function Documentation

net_mqtt_connect()

bool net_mqtt_connect	(	net_mqtt_t *	mqtt,
		const char *	hostname,
		uint16_t	port,
		const char *	client_id,
		const char *	user,
		const char *	password,
		uint16_t	keepalive_secs,
		const char *	will_topic,
		const char *	will_message
	)

Begin an asynchronous connection to an MQTT broker.

Parameters

mqtt	MQTT handle created by net_mqtt_init.
hostname	Broker hostname or IP address.
port	Broker port (e.g., 1883 for MQTT, 8883 for MQTT over TLS). Pass 0 to use the default port (1883).
client_id	Client identifier. May be NULL to use an implementation-defined or stack-provided default if available.
user	Username for authentication. May be NULL for anonymous.
password	Password for authentication. Ignored if user is NULL.
keepalive_secs	Keep-alive interval in seconds.
will_topic	Optional Last Will topic. May be NULL to disable will.
will_message	Optional Last Will message. If provided, a non-NULL will_topic is also expected.

Returns

true if the connection attempt was successfully initiated; false on immediate failure (invalid parameters or state).

Completion and errors are reported via the connect callback provided at initialization (see net_mqtt_connect_callback_t) with one of the net_mqtt_status_t values.

net_mqtt_disconnect()

bool net_mqtt_disconnect

(

net_mqtt_t *

mqtt

)

Begin an asynchronous disconnect from the MQTT broker.

Parameters

mqtt	MQTT handle created by net_mqtt_init.

Returns

true if the disconnect was successfully initiated; false otherwise.

When the connection is fully closed, the connect callback will be invoked with net_mqtt_status_disconnected_t.

net_mqtt_finalize()

void net_mqtt_finalize

(

net_mqtt_t *

mqtt

)

Finalize the MQTT handle and free associated resources.

Parameters

mqtt	The MQTT handle to finalize. NULL is allowed and is a no-op.

The caller should ensure the connection is closed (see net_mqtt_disconnect) and that no callbacks are in flight before calling this function.

net_mqtt_init()

net_mqtt_t net_mqtt_init	(	net_mqtt_connect_callback_t	connect,
		void *	user_data
	)

Create and initialize an MQTT handle.

Parameters

connect	Callback to receive connection status updates.
user_data	Opaque pointer passed back to connect.

Returns

net_mqtt_t An MQTT handle on success; a zero-initialized handle on failure.

The returned handle is opaque and must be released with net_mqtt_finalize after disconnecting.

net_mqtt_publish()

bool net_mqtt_publish	(	net_mqtt_t *	mqtt,
		const char *	topic,
		const void *	data,
		size_t	size,
		uint8_t	qos
	)

Publish a message to a topic.

Synchronously sends a PUBLISH packet on the active connection. The call returns after the message is sent.

Parameters

mqtt	MQTT handle created by net_mqtt_init and currently connected (see net_mqtt_valid).
topic	Topic name to publish to. Must be non-NULL and non-empty.
data	Pointer to the message payload. Must be non-NULL.
size	Size of the message payload in bytes.
qos	QoS level: 0, 1, or 2. Messages with QoS 1 or 2 will also set retain flag.

Returns

true if the message was sent; false on failure.

net_mqtt_publish_str()

static bool net_mqtt_publish_str ( net_mqtt_t *  mqtt, const char *  topic, const char *  str, uint8_t  qos  )

inlinestatic

Publish a NULL-terminated string to a topic.

Parameters

mqtt	MQTT handle created by net_mqtt_init and currently connected (see net_mqtt_valid).
topic	Topic name to publish to. Must be non-NULL and non-empty.
str	NULL-terminated string to publish. Must be non-NULL.
qos	QoS level: 0, 1, or 2. Messages with QoS 1 or 2 will also set retain flag.

Returns

true if the message was sent; false on failure.

Asynchronously queues a PUBLISH packet on the active connection. The call returns after the message is queued for transmission; it does not block for broker acknowledgements.

Definition at line 195 of file mqtt.h.

                                                                      {
  return net_mqtt_publish(mqtt, topic, str, strlen(str), qos);
}

net_mqtt_subscribe()

bool net_mqtt_subscribe	(	net_mqtt_t *	mqtt,
		const char *	topic,
		uint8_t	qos
	)

Subscribe to a topic.

Begins an asynchronous SUBSCRIBE request on the active connection. The call returns after the request is queued; it does not block for broker acknowledgement. Connection state changes and errors continue to be reported via the connect callback.

Parameters

mqtt	MQTT handle created by net_mqtt_init and currently connected (see net_mqtt_valid).
topic	UTF-8 topic filter to subscribe to. Must be non-NULL and non-empty. MQTT wildcards '+' and '#' are allowed per broker policy.
qos	Requested maximum QoS for incoming publishes: 0, 1, or 2.

Returns

true if the subscribe request was accepted/queued; false on immediate failure (invalid parameters, not connected, or resource exhaustion).

net_mqtt_valid()

bool net_mqtt_valid

(

net_mqtt_t *

mqtt

)

Check whether an MQTT client is valid and connected.

Parameters

mqtt	The MQTT handle to check.

Returns

true if the handle is initialized and currently connected to a broker, false otherwise.