General API
Protocols > HTTP Server Data Stream

HTTP server stream general API for both REST and Websocket clients. More...

Functions

gos_result_t gos_hs_stream_register (const char *stream_name, gos_hs_stream_handler_t handler, gos_hs_stream_permissions_t permissions, void *arg)
gos_result_t gos_hs_stream_unregister (const char *stream_name)
gos_result_t gos_hs_stream_flush ( gos_msgpack_context_t *msgpack, uint32_t timeout_ms)
gos_result_t gos_hs_stream_write_direct ( gos_msgpack_context_t *msgpack, const void *buffer, uint32_t length)

Detailed Description

HTTP server stream general API for both REST and Websocket clients.

Function Documentation

◆ gos_hs_stream_flush()

gos_result_t gos_hs_stream_flush ( gos_msgpack_context_t * msgpack,
uint32_t timeout_ms
)

Flush data to client

This is used to flush data back to a client.

Data should be flushed in two instances:

  1. Responding to a client read request
  2. Asynchronously writing to a websocket client

Responding to a client read request: When a client issues a read request, the corresponding stream handle gos_hs_stream_handler_t is invoked in the application thread context. In the handler, the application should use the msgpack APIs to populate the given gos_msgpack_context_t . Once the data is written to the gos_msgpack_context_t , it should be flushed using this API.

Note
When responding to a client read request, the timeout_ms argument is the amount of time to wait for the response to be transferred.

Asynchronously writing to a websocket client: The application can asynchronously write data to a websocket client. This is done by first creating a write request with the gos_hs_stream_ws_write() API. The gos_hs_stream_ws_write() API creates a gos_msgpack_context_t that the application should populate with the msgpack APIs. Once the message is populated, this flush API is used to send the data to the websocket client.

Note
When asynchronously writing a websocket client, the timeout_ms argument is the amount of time to wait for the client to respond with an acknowledgment that the packet was received. If timeout_ms is 0 then the client will NOT return an acknowledgment. This allows for faster data transfer as the device does not need to wait for a response for each transmitted data packet.
Parameters
[in] msgpack gos_msgpack_context_t to populate with data to send to remote client
[in] timeout_ms Amount of time in milliseconds to wait for either the data to be sent or the amount of time to wait for a response
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 .

◆ gos_hs_stream_register()

gos_result_t gos_hs_stream_register ( const char * stream_name,
gos_hs_stream_handler_t handler,
gos_hs_stream_permissions_t permissions,
void * arg
)

Register a stream handler

This registers a stream handler. Once a stream is registered, remote clients can issue read or write requests for the stream. When the client issues a request, the handler is invoked in the application thread context. See gos_hs_stream_handler_t for more details about how the handler works.

Parameters
[in] stream_name Name of stream to listen
[in] handler Handler to be invoked when remote client issues a read/write request for stream
[in] permissions Permissions clients are allowed for this stream
[in] arg Optional argument to be supplied to stream handler. Leave NULL if unused.
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 .

◆ gos_hs_stream_unregister()

gos_result_t gos_hs_stream_unregister ( const char * stream_name )

Unregister a stream handler

Unregister a stream handler that was previously registered with gos_hs_stream_register() .

Parameters
[in] stream_name Name of previously registered stream
Returns
gos_result_t result of api call

◆ gos_hs_stream_write_direct()

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

Directly write the msgpack context

Typically the msgpack APIs are used to populate the msgpack context. This API allows for directly writing msgpack-formatted data to the internal buffer.

Parameters
[in] msgpack gos_msgpack_context_t to populate with data to send to remote client
[in] buffer Msgpack-formatted data to write to context
[in] length Length of given buffer in bytes
Returns
gos_result_t result of api call
Examples:
hurricane/arducam/camera.c .