The Server Library API(s)

Classes
struct	mqtt_server_msg_cbs
struct	mqtt_server_lib_cfg
Modules
	Helper Macros for RX CONNECT
Defines
#define	MQP_SERVER_RX_LEN   1024
Functions
i32	mqtt_vh_msg_send (void *ctx_cl, u8 msg_type, enum mqtt_qos qos, bool has_vh, u16 vh_data)
i32	mqtt_vh_msg_send_locked (void *ctx_cl, u8 msg_type, enum mqtt_qos qos, bool has_vh, u16 vh_data)
i32	mqtt_server_pub_dispatch (void *ctx_cl, struct mqtt_packet *mqp, bool dup)
i32	mqtt_server_pub_dispatch_locked (void *ctx_cl, struct mqtt_packet *mqp, bool dup)
i32	mqtt_server_run (u32 wait_secs)
i32	mqtt_server_register_net_svc (const struct device_net_services *net)
i32	mqtt_server_lib_init (const struct mqtt_server_lib_cfg *cfg, const struct mqtt_server_msg_cbs *cbs)

---

Define Documentation

#define MQP_SERVER_RX_LEN   1024

Max size(B) of RX Buffer for MQTT Server

---

Function Documentation

i32 mqtt_server_lib_init	(	const struct mqtt_server_lib_cfg *	cfg,
		const struct mqtt_server_msg_cbs *	cbs
	)

Initialize the MQTT Server Packet library This routine initializes the packet and network constructs that are required to manage the multiple network connetions. The server packet LIB must be initialized prior to invoking of any other routine or service.

Note:

This routine must be invoked only once in an run of the system.

If there are more than one application (tasks) that utilize the services of the server packet library, then certain configuration must be set in the LIB

See also:

struct mqtt_server_lib_cfg

The application should also provision the platform network specific network services into the packet library

See also:

mqtt_server_register_net_svc.

Once, the server LIB has been intialized successfully, it must be put into action, to listen to requests for incoming connections, by invoking the API mqtt_server_run.

Parameters:

[in]	cfg	configuration information for the MQTT server packet library
[in]	cbs	callback routines that LIB will invoke into the application

Returns:

0 on success otherwise -1.

i32 mqtt_server_pub_dispatch	(	void *	ctx_cl,
		struct mqtt_packet *	mqp,
		bool	dup
	)

Dispatch application constructed PUBLISH message to the client. Prior to sending the message to the client, this routine shall update the fixed-header to account for the duplicate flag that has been indicated by the caller.

The caller must populate the payload information of topic and data before invoking this service. In addition, the application must prepare, for the packet, the fix header leaving aside the duplicate flag - this flag shall be included in the fix heder by the LIB.

This service facilitates the application to re-use, iteratively, a single PUBLISH packet for multiple remote clients that have subscribed to the same topic for which the data is being published. The LIB does not free-up the MQTT packet after sending the packet to the remote client and the application is responsible for managing the packet container / memory

Parameters:

[in]	ctx_cl	handle to the underlying network context in the LIB. This handle is provided to the application by the LIB in the CONNECT callback.
[in]	mqp	app created PUBLISH message alongwith the fixed header
[in]	dup	is this a duplicate message that is being sent to client?

Returns:

on success, the number of bytes transferred. Otherwise, error defined in LIBRARY Generated Error Codes

i32 mqtt_server_pub_dispatch_locked	(	void *	ctx_cl,
		struct mqtt_packet *	mqp,
		bool	dup
	)

mqtt_server_pub_dispatch() with mutual exclusion (in multi-task application). This routine ensures that the LIB sends the specified packet onto the network in a manner that excludes execution of any other control. This API has been enabled to support the scenarios, where the multi-tasked user application has chosen to use a mutex object other than the one provisioned in the packet LIB to streamline / serialize accesses to the services of the packet LIB.

Refer to mqtt_server_pub_dispatch for other details.

i32 mqtt_server_register_net_svc

(

const struct device_net_services *

net

)

Abstraction for the device specific network services Network services for communication with the clients

Parameters:

[in]

net

refers to network services supported by the platform

Returns:

on success, 0, otherwise -1

Abstraction of Network Services on a platform

Note:

all entries in net must be supported by the platform.

i32 mqtt_server_run

(

u32

wait_secs

)

Run the server packet LIB for the specified wait time. This routine yields the control back to the application after the specified duration of wait time. Such an arrangement enable the application to make overall progress to meet it intended functionality.

The wait time implies the maximum intermediate duration between the reception of two successive messages from the server. If no message is received before the expiry of the wait time, the routine returns. However, the routine would continue to block, in case, messages are being received within the successive period of wait time.

Parameters:

[in]

wait_secs

maximum time to wait for a message from the server

Note:

if the value of MQP_ERR_LIBQUIT is returned, then system must be restarted.

i32 mqtt_vh_msg_send	(	void *	ctx_cl,
		u8	msg_type,
		enum mqtt_qos	qos,
		bool	has_vh,
		u16	vh_data
	)

Send a Variable Header only message to the client. Application should this routine to send PUBREL and PUBCOMP messages.

Parameters:

[in]	ctx_cl	handle to the underlying network context in the LIB. This handle is provided to the application by the LIB in the CONNECT callback.
[in]	msg_type	message type that has to be sent to the client
[in]	qos	QoS with which the message needs to send to server
[in]	has_vh	does this message has data in the variable header?
[in]	vh_data	data <MSB:LSB> to be included in the variable header

Returns:

on success, the number of bytes transferred. Otherwise, errors defined in LIBRARY Generated Error Codes

i32 mqtt_vh_msg_send_locked	(	void *	ctx_cl,
		u8	msg_type,
		enum mqtt_qos	qos,
		bool	has_vh,
		u16	vh_data
	)

mqtt_vh_msg_send() with mutual exclusion (in multi-task application). This routine ensures that the LIB sends the specified VH MSG onto the network in a manner that excludes execution of any other control. This API has been enabled to support the scenarios, where the multi-tasked user application has chosen to use a mutex object other than the one provisioned in the packet LIB to streamline / serialize accesses to the services of the packet LIB.

Refer to mqtt_vh_msg_send for details