Message
DMS device stream messages. 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
◆ 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
- Examples:
- hurricane/security_camera/main.c .
◆ 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
◆ 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
◆ 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
- Examples:
- hurricane/security_camera/camera.c .
◆ 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 , dms/telemetry/main.c , and hurricane/security_camera/main.c .