Message
Device Management Server (DMS)

DMS device stream messages. More...

Functions

void gos_dms_set_message_fallback_handler ( gos_handler_t handler)
Fallback DMS message handler. More...
gos_result_t gos_dms_set_message_stream_state_handler ( gos_network_handler_t handler)
Message stream state handler. More...
gos_result_t gos_dms_message_write_buffer (const void *msgpack_buffer, uint32_t length, gos_handler_t handler, uint32_t timeout_ms)
Write msgpack buffer to DMS. More...
gos_result_t gos_dms_message_write_init ( gos_msgpack_context_t **msgpack_ptr, const gos_dms_messsage_config_t *config)
Initialize a write message context. More...
gos_result_t gos_dms_message_write_raw ( gos_msgpack_context_t *msgpack, const void *buffer, uint32_t length)
Directly write raw data to message. More...
gos_result_t gos_dms_message_write_flush ( gos_msgpack_context_t *msgpack)
Send message to DMS. More...
gos_result_t gos_dms_message_context_destroy ( gos_msgpack_context_t *msgpack)
Cleanup unsent message. More...
gos_result_t gos_dms_message_register_action_listener (const char *action_name, gos_handler_t handler)
Register an action listener. More...
gos_result_t gos_dms_message_unregister_action_listener (const char *action_name)
Unregister action listener. More...

Detailed Description

DMS device stream messages.

Function Documentation

◆ gos_dms_message_context_destroy()

gos_result_t gos_dms_message_context_destroy ( gos_msgpack_context_t * msgpack )

Cleanup unsent message.

This cleans up a gos_msgpack_context_t initialized with gos_dms_message_write_init() .

This should be used if a message needs to be aborted before gos_dms_message_write_flush() is called.

Parameters
[in] msgpack Initialized, unset msgpack context to clean up
Returns
Result of API, see gos_result_t
Examples:
dms/messages/main.c .

◆ gos_dms_message_register_action_listener()

gos_result_t gos_dms_message_register_action_listener ( const char * action_name,
gos_handler_t handler
)

Register an action listener.

This registers a handler to be invoked when a corresponding action message is received from the DMS.

The handler executes in the User App thread. The argument to the response handler is gos_msgpack_object_t containing the parsed response.

Note
The handler is responsible for cleaning the message with gos_msgpack_free_objects()

This API may be called at any time and will persistent until the device is rebooted.

Use gos_dms_message_unregister_action_listener() to unregister the handler.

Parameters
[in] action_name Name of 'action' to register handler with
[in] handler Handler to invoke when corresponding action is received from DMS
Returns
Result of API, see gos_result_t
Examples:
dms/messages/main.c .

◆ gos_dms_message_unregister_action_listener()

gos_result_t gos_dms_message_unregister_action_listener ( const char * action_name )

Unregister action listener.

This unregisters an action listener than was registered with gos_dms_message_register_action_listener()

Parameters
[in] action_name Name of 'action' to unregister corresponding handler
Returns
Result of API, see gos_result_t

◆ gos_dms_message_write_buffer()

gos_result_t gos_dms_message_write_buffer ( const void * msgpack_buffer,
uint32_t length,
gos_handler_t handler,
uint32_t timeout_ms
)

Write msgpack buffer to DMS.

This sends a pre-populated, msgack buffer to the DMS.

See the Write APIs for populating the buffer.

Note
The root object of the msgpack buffer must be a dictionary (see gos_msgpack_write_dict_marker() )
The DMS websocket must be opened before using this API, see dms.auto_start_enabled

Optionally receive a message response from the DMS by supplying a handler argument. This response handler will execute in the User App thread when a response is received from the DMS. The argument to the response handler is gos_msgpack_object_t containing the parsed response.

Note
The handler is responsible for cleaning the message with gos_msgpack_free_objects()

If no response is received after timeout_ms then the handler is invoked with a NULL argument.

Parameters
[in] msgpack_buffer Buffer containing msgpack formatted message data
[in] length Length of buffer in bytes
[in] handler Handler to be invoked when a corresponding response is received from the DMS, or the response times out
[in] timeout_ms Time in milliseconds to wait for a response from the DMS
Returns
Result of API, see gos_result_t

◆ gos_dms_message_write_flush()

gos_result_t gos_dms_message_write_flush ( gos_msgpack_context_t * msgpack )

Send message to DMS.

Once a message is fully written, send it to the DMS with this API.

The msgpack argument should be initialized with gos_dms_message_write_init() .

Note
This API automatically cleans up the msgpack context on SUCCESS or failure.
Parameters
[in] msgpack Populated msgpack context to send to DMS
Returns
Result of API, see gos_result_t
Examples:
dms/messages/main.c .

◆ gos_dms_message_write_init()

gos_result_t gos_dms_message_write_init ( gos_msgpack_context_t ** msgpack_ptr,
const gos_dms_messsage_config_t * config
)

Initialize a write message context.

This initializes and returns a gos_msgpack_context_t to be used for populating a message to send to the DMS.

Note
The DMS websocket must be opened before using this API, see dms.auto_start_enabled

See gos_dms_messsage_config_t for more details on configuring the write context. If the config argument is NULL then no response handler is configured.

Once the context is initialized, use Write APIs for populating the context.

Note
The root object of the msgpack buffer must be a dictionary (see gos_msgpack_write_dict_marker() )

Once the message is fully written, use gos_dms_message_write_flush() to send the message to the DMS.

Note
If the message must be aborted before sending to the DMS, call gos_dms_message_context_destroy() to cleanup the write context.
Parameters
[out] msgpack_ptr Pointer to hold a gos_msgpack_context_t used for writing
[in] config Message context configuration, see gos_dms_messsage_config_t , leave NULL to use defaults
Returns
Result of API, see gos_result_t
Examples:
dms/messages/main.c .

◆ gos_dms_message_write_raw()

gos_result_t gos_dms_message_write_raw ( gos_msgpack_context_t * msgpack,
const void * buffer,
uint32_t length
)

Directly write raw data to message.

Typically the Write APIs are used for populated the message. This API allows for directly writing raw data without the msgpack APIs.

Note
The supplied msgpack argument should first be initialized by gos_dms_message_write_init()
The root element of the message MUST be a 16bit dictionary
Parameters
[in] msgpack msgpack context to directly write data to
[in] buffer Buffer data to write
[in] length Length of supplied buffer
Returns
Result of API, see gos_result_t

◆ gos_dms_set_message_fallback_handler()

void gos_dms_set_message_fallback_handler ( gos_handler_t handler )

Fallback DMS message handler.

This sets a handler to be invoked if a message received from the DMS is not handled internally.

The handler executes in the User App thread.

The argument of the handler is a gos_msgpack_object_t containing the parsed message.

Note
The handler is responsible for cleaning the message with gos_msgpack_free_objects()
Parameters
handler Handler to be executed when an unhandled message is received from the DMS
Examples:
dms/messages/main.c .

◆ gos_dms_set_message_stream_state_handler()

gos_result_t gos_dms_set_message_stream_state_handler ( gos_network_handler_t handler )

Message stream state handler.

This sets a handler to be invoked when the DMS message stream's (aka secure websocket) state changes.

The handler executes in the User App thread. The boolean argument to the handler indicates the stream state.

If the argument is 'true' the stream is UP and ready to send/receive messages.

If the argument is 'false' stream is DOWN and cannot send/receive messages.

Parameters
handler Handler to be executed when a the message stream's connection state changes
Examples:
dms/messages/main.c , and dms/telemetry/main.c .