Websocket API
HTTP server stream general API for Websocket clients. More...
Functions |
|
gos_result_t | gos_hs_stream_ws_list ( gos_hs_stream_ws_client_t handle, gos_msgpack_object_t **object_ptr, uint32_t timeout_ms) |
gos_result_t | gos_hs_stream_ws_read ( gos_hs_stream_ws_client_t handle, const char *stream_name, gos_msgpack_object_t **object_ptr, uint32_t timeout_ms) |
gos_result_t | gos_hs_stream_ws_write ( gos_hs_stream_ws_client_t handle, const char *stream_name, gos_msgpack_context_t **msgpack_ptr) |
void | gos_hs_stream_ws_abort_write ( gos_msgpack_context_t *msgpack) |
gos_result_t | gos_hs_stream_ws_close ( gos_hs_stream_ws_client_t handle) |
gos_result_t | gos_hs_stream_ws_set_accept_callback ( gos_hs_stream_ws_accept_callback_t accept) |
gos_result_t | gos_hs_stream_ws_set_handlers ( gos_handler_t connect, gos_handler_t disconnect) |
Detailed Description
HTTP server stream general API for Websocket clients.
Function Documentation
◆ gos_hs_stream_ws_abort_write()
void gos_hs_stream_ws_abort_write | ( | gos_msgpack_context_t * |
msgpack
|
) |
Abort an asynchronous write
This aborts an asynchronous write to a websocket client. This is used to cleanup the gos_msgpack_context_t returned by gos_hs_stream_ws_write() .
- Parameters
-
[in] msgpack
Context to cleanup.
- Examples:
- hurricane/arducam/camera.c .
◆ gos_hs_stream_ws_close()
gos_result_t gos_hs_stream_ws_close | ( | gos_hs_stream_ws_client_t |
handle
|
) |
Close an open websocket client connection
This closes an open websocket client connection.
- Note
- Typically, the client connection is managed internally. This is only needed if the application needs to manually close the client connection.
- Parameters
-
[in] handle
Websocket client handle
- Returns
- gos_result_t result of api call
◆ gos_hs_stream_ws_list()
gos_result_t gos_hs_stream_ws_list | ( | gos_hs_stream_ws_client_t |
handle,
|
gos_msgpack_object_t ** |
object_ptr,
|
||
uint32_t |
timeout_ms
|
||
) |
List the streams a websocket client has registered
This returns an array of stream names a websocket client has registered.
- Parameters
-
[in] handle
Websocket client handle [out] object_ptr
gos_msgpack_object_t to hold stream name array [in] timeout_ms
Time in milliseconds to wait for client to respond with the listing
- Returns
- gos_result_t result of api call
- Examples:
- network/http_server_stream/main.c .
◆ gos_hs_stream_ws_read()
gos_result_t gos_hs_stream_ws_read | ( | gos_hs_stream_ws_client_t |
handle,
|
const char * |
stream_name,
|
||
gos_msgpack_object_t ** |
object_ptr,
|
||
uint32_t |
timeout_ms
|
||
) |
Asynchronously read data from a websocket client's stream
This reads data from a specific websocket client's stream.
- Note
- Once the data is no longer needed, the application MUST call gos_msgpack_free_objects() to cleanup the read data.
- Parameters
-
[in] handle
Websocket client handle [in] stream_name
Name of stream to read [out] object_ptr
gos_msgpack_object_t to hold read data object [in] timeout_ms
Time in milliseconds to wait for client to respond with the stream data
- Returns
- gos_result_t result of api call
- Examples:
- network/http_server_stream/main.c .
◆ gos_hs_stream_ws_set_accept_callback()
gos_result_t gos_hs_stream_ws_set_accept_callback | ( | gos_hs_stream_ws_accept_callback_t |
accept
|
) |
Set websocket client accept callback
This set the gos_hs_stream_ws_accept_callback_t callback which is called just before a websocket client connects. This callback allows for blocking clients from connecting.
- Parameters
-
[in] accept
Callback to be invoked before a websocket client connects
- Returns
- gos_result_t result of api call
- Examples:
- hurricane/arducam/network.c , and network/http_server_stream/main.c .
◆ gos_hs_stream_ws_set_handlers()
gos_result_t gos_hs_stream_ws_set_handlers | ( | gos_handler_t |
connect,
|
gos_handler_t |
disconnect
|
||
) |
Set websocket connect/disconnect handlers
This sets handlers to be invoked when a websocket client connects or disconnects.
The handlers execute in the application thread context.
The argument to the handler is the gos_hs_stream_ws_client_t handle of the client. The handle may be used with the following APIs:
- Parameters
-
[in] connect
Handler to be invoked when a websocket client connects [in] disconnect
Handler to be invoked when a websocket client disconnects
- Returns
- gos_result_t result of api call
◆ gos_hs_stream_ws_write()
gos_result_t gos_hs_stream_ws_write | ( | gos_hs_stream_ws_client_t |
handle,
|
const char * |
stream_name,
|
||
gos_msgpack_context_t ** |
msgpack_ptr
|
||
) |
Prepare context to asynchronously write data to a websocket client's stream
This initializes a gos_msgpack_context_t to asynchronously write data to a websocket client's stream. After this API returns, the msgpack APIs should be used to populate the given gos_msgpack_context_t . Once the data is populated, gos_hs_stream_flush() should be used to send the data to the websocket client.
- Note
-
The
gos_hs_stream_flush()
must be used to write the data to the remote websocket client. If the write needs to be aborted before it can be flush, the
msgpack_ptr
context MUST be cleaned up with gos_hs_stream_ws_abort_write() to avoid a memory leak. - Use GOS_HS_STREAM_WRITE_ALL to write to all connected clients.
- Parameters
-
[in] handle
Websocket client handle [in] stream_name
Name of stream to write [out] msgpack_ptr
Point to gos_msgpack_context_t
to be used to populate data
- Returns
- gos_result_t result of api call