MQTT Server: The Server Daemon API(s)

MQTT Server Package

MQTT Server 1.0.0
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]topicUTF8 topic Name for which data has been published
[in]data_bufthe published binary data for the topic
[in]data_lenthe length of the binary data
[in]qosquality of service of the message / data
[in]retainshould 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]cbscallback routines from the application to be invoked by the server
[in]namerefers 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_cfgconfiguration information for the MQTT server packet library.
[in]app_cfgconfiguration 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_hndhandle to the application context in the server. This handle is provided by server mqtt_server_app_register()
[in]topicUTF8 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_hndhandle to the application context in the server. This handle is provided by server mqtt_server_app_register()
[in]topicUTF8 based string for which the application needs to start getting the published data
[in]qosthe meximum QoS the application intends to receive data for this particular topic
Returns:
0 on sucess, otherwise a negative value on error.
Generated on Mon Nov 17 2014 12:12:08 for MQTT Server by  doxygen 1.7.4