Websocket API
Protocols > HTTP Server Data Stream

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
Examples:
demo/3d_demo/main.c , demo/accelerometer_stream/main.c , hurricane/arducam/network.c , and network/http_server_stream/main.c .

◆ 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
Examples:
demo/3d_demo/main.c , demo/accelerometer_stream/main.c , hurricane/arducam/camera.c , and network/http_server_stream/main.c .