The Server Daemon API(s)

Classes
struct	mqtt_server_app_cbs
struct	mqtt_server_app_cfg
Functions
i32	mqtt_server_topic_enroll (const void *app_hnd, const struct utf8_string *topic, enum mqtt_qos qos)
i32	mqtt_server_topic_disenroll (const void *app_hnd, const struct utf8_string *topic)
i32	mqtt_server_app_pub_send (const struct utf8_string *topic, const u8 *data_buf, u32 data_len, enum mqtt_qos qos, bool retain)
void *	mqtt_server_app_register (const struct mqtt_server_app_cbs *cbs, const i8 *name)
i32	mqtt_server_init (const struct mqtt_server_lib_cfg *lib_cfg, const struct mqtt_server_app_cfg *app_cfg)

---

Function Documentation

i32 mqtt_server_app_pub_send	(	const struct utf8_string *	topic,
		const u8 *	data_buf,
		u32	data_len,
		enum mqtt_qos	qos,
		bool	retain
	)

Send data to network for a topic This routine offers the binary data along-with associated properties for a specific topic to the server. The server, based on the subscriptions from the remote clients and the enrollments made by the local applications for this topic, will send the binary data and its qualifiers, adjusted for the maximum subscribed or enrolled QoS, to the remote clients and the local applications.

Parameters:

[in]	topic	UTF8 topic Name for which data has been published
[in]	data_buf	the published binary data for the topic
[in]	data_len	the length of the binary data
[in]	qos	quality of service of the message / data
[in]	retain	should the server retain the data?

Returns:

on success, the length of data sent, otherwise -1 on error.

void* mqtt_server_app_register	(	const struct mqtt_server_app_cbs *	cbs,
		const i8 *	name
	)

Register an application with the server. This routine makes known to the server about an application identified by its name and creates a context / reference for the application in the server.

An application intending to utlize the servicse of the MQTT server must be first registered with the server.

Parameters:

[in]	cbs	callback routines from the application to be invoked by the server
[in]	name	refers to the name of the application. The application must retain the memory used by the 'name' after the function call. The server does not copy the name into its internal buffers.

Returns:

a valid handle to context of application in the server, othewise NULL on error

i32 mqtt_server_init	(	const struct mqtt_server_lib_cfg *	lib_cfg,
		const struct mqtt_server_app_cfg *	app_cfg
	)

Initialize the MQTT Server (Task / Daemon). This routine initializes the server implementation and sets it up using the provided configuration. The server implementation must be initialized prior to invoking of any other routine or service.

This routine should be invoked as part of the platform initialization.

Note:

This routine must be invoked only once in an run of the system. This routine internally invokes the mqtt_server_lib_init( ) and therefore, there is no need to invoke the mqtt_server_lib_init( ) explicitly.

The server needs to be in a state to listen to incoming MQTT connection requests. Therefore, the platform sequence after provisioning the buffer using the API mqtt_server_register_net_svc, must invoke the API mqtt_server_run, in an infinite loop, to keep the server daemon active.

Parameters:

[in]	lib_cfg	configuration information for the MQTT server packet library.
[in]	app_cfg	configuration information for the server applications.

Returns:

0 on success, otherwise -1 on error

i32 mqtt_server_topic_disenroll	(	const void *	app_hnd,
		const struct utf8_string *	topic
	)

Cancel previous enrollment to receive data for a topic This routines terminates the previous registration, if any, made by the application to receive any publishised data for the specified topic. Once, the enrollment is removed, the application, there after, will not receive any data for this topic from the server.

Parameters:

[in]	app_hnd	handle to the application context in the server. This handle is provided by server mqtt_server_app_register()
[in]	topic	UTF8 based string for which the application needs to stop getting the published data

Returns:

0 on success, otherwise a negative value on error.

i32 mqtt_server_topic_enroll	(	const void *	app_hnd,
		const struct utf8_string *	topic,
		enum mqtt_qos	qos
	)

Enroll with server to receive data for a topic This routine registers with the server, the specified topic for which the application should receive any published data from the network. Whenever, any of the remote clients that are connected to the server or applications, this or other, publishes data for the specified topic, the server will present the published information to this application.

As part of the enrollment, the application should provide the maxmimum QoS with which the server should provide the published data. If the topic data received by the server bears a QoS higher than the one specified by the application, the server shall lower it to the QoS level preferred by the application. Otherwise, the QoS of the data shall be presented 'as-is'. In other words, the application should expect a published data with a lower QoS.

Parameters:

[in]	app_hnd	handle to the application context in the server. This handle is provided by server mqtt_server_app_register()
[in]	topic	UTF8 based string for which the application needs to start getting the published data
[in]	qos	the meximum QoS the application intends to receive data for this particular topic

Returns:

0 on sucess, otherwise a negative value on error.