WebSocket Client/Server

WebSocket client/server functions. More...

Modules

Types
WebSocket data types.

Functions

gos_result_t gos_websocket_connect ( gos_interface_t interface, const char *host, gos_handle_t *handle_ptr)
Connect to a remote websocket server. More...
gos_result_t gos_websocket_connect_with_config (const gos_websocket_config_t *config, gos_handle_t *handle_ptr)
Connect to a remote websocket server with configuration. More...
gos_result_t gos_websocket_read ( gos_handle_t handle, void *data, uint32_t max_size, uint32_t *bytes_read_ptr)
Read websocket stream data. More...
gos_result_t gos_websocket_read_with_buffer ( gos_handle_t handle, gos_buffer_t *buffer)
Read websocket stream data into buffer. More...
gos_result_t gos_websocket_write ( gos_handle_t handle, const void *data, uint32_t size, bool continue_frame)
Write websocket stream data. More...
gos_result_t gos_websocket_disconnect ( gos_handle_t handle)
Close websocket stream. More...
gos_result_t gos_websocket_poll ( gos_handle_t handle, uint32_t *rx_bytes_available, uint32_t *tx_bytes_available)
Poll websocket stream for RX data. More...
gos_result_t gos_websocket_send_ping ( gos_handle_t handle, const void *data, uint32_t size)
Send a 'Ping' to Websocket client or server. More...
gos_result_t gos_websocket_client_read_frame ( gos_handle_t handle, gos_websocket_frame_t *frame, uint32_t timeout_ms)
Read complete websocket frame. More...
void gos_websocket_register_server_event_handlers ( gos_stream_event_handler_t connect, gos_stream_event_handler_t disconnect, gos_stream_event_handler_t receive)
Register websocket server event handlers. More...
void gos_websocket_register_client_event_handlers ( gos_handle_t handle, gos_stream_event_handler_t disconnect, gos_stream_event_handler_t receive)
Register websocket client event handlers. More...
gos_result_t gos_websocket_get_client_info ( gos_handle_t handle, char *host_buffer, uint32_t host_buffer_len, uint16_t *local_port_ptr, uint16_t *remote_port_ptr)
Get Websocket client info. More...

Detailed Description

WebSocket client/server functions.

Function Documentation

gos_websocket_client_read_frame()

gos_result_t gos_websocket_client_read_frame ( gos_handle_t handle,
gos_websocket_frame_t * frame,
uint32_t timeout_ms
)

Read complete websocket frame.

Note
Stream handles start at 1, max handle value is GOS_MAX_STREAMS

gos_websocket_connect()

gos_result_t gos_websocket_connect ( gos_interface_t interface,
const char * host,
gos_handle_t * handle_ptr
)

Connect to a remote websocket server.

This opens a websocket client stream.

See Gecko OS Command API documentation: websocket_client .

Parameters
interface The network interface to open connect
host The remote websocket server's URL
handle_ptr The stream handle of the opened websocket client stream
Returns
gos_result_t result of api call
Examples:
network/websocket_client/main.c .

gos_websocket_connect_with_config()

gos_result_t gos_websocket_connect_with_config ( const gos_websocket_config_t * config,
gos_handle_t * handle_ptr
)

Connect to a remote websocket server with configuration.

See Gecko OS Command API documentation: websocket_client .

This does the same thing as gos_websocket_connect() but allows for additional configuration. See gos_websocket_config_t for optional configuration settings.

Parameters
config Websocket client configuration
handle_ptr The stream handle of the opened websocket client stream
Returns
gos_result_t result of api call

gos_websocket_disconnect()

gos_result_t gos_websocket_disconnect ( gos_handle_t handle )

Close websocket stream.

See Gecko OS Command API documentation: stream_close .

Note
Stream handles start at 1, max handle value is GOS_MAX_STREAMS
Parameters
[in] handle Handle of stream to close
Returns
gos_result_t result of api call
Examples:
network/websocket_client/main.c .

gos_websocket_get_client_info()

gos_result_t gos_websocket_get_client_info ( gos_handle_t handle,
char * host_buffer,
uint32_t host_buffer_len,
uint16_t * local_port_ptr,
uint16_t * remote_port_ptr
)

Get Websocket client info.

See Gecko OS Command API documentation: stream_list .

Note
Stream handles start at 1, max handle value is GOS_MAX_STREAMS
Parameters
[in] handle Client stream handle
[in] host_buffer Buffer to hold client host domain or IP address string
[in] host_buffer_len Length of host_buffer
[in] local_port_ptr Pointer to hold client's local port, leave NULL to ignore
[in] remote_port_ptr Pointer to hold client's remote port, leave NULL to ignore
Returns
gos_result_t result of api call
Examples:
network/websocket_server/main.c .

gos_websocket_poll()

gos_result_t gos_websocket_poll ( gos_handle_t handle,
uint32_t * rx_bytes_available,
uint32_t * tx_bytes_available
)

Poll websocket stream for RX data.

Note
Stream handles start at 1, max handle value is GOS_MAX_STREAMS
Parameters
[in] handle Handle of stream to poll
[out] rx_bytes_available Pointer to hold number of bytes available to read
[out] tx_bytes_available Pointer to hold available TX buffer space
Returns
gos_result_t result of api call
Examples:
network/websocket_client/main.c .

gos_websocket_read()

gos_result_t gos_websocket_read ( gos_handle_t handle,
void * data,
uint32_t max_size,
uint32_t * bytes_read_ptr
)

Read websocket stream data.

See Gecko OS Command API documentation: stream_read .

Note
Stream handles start at 1, max handle value is GOS_MAX_STREAMS
Parameters
[in] handle Stream handle returned by API call
[out] data Buffer to hold read data
[in] max_size Maximum amount of data to read
[out] bytes_read_ptr Pointer to hold actual amount of data read (set NULL if not used)
Returns
gos_result_t result of api call

gos_websocket_read_with_buffer()

gos_result_t gos_websocket_read_with_buffer ( gos_handle_t handle,
gos_buffer_t * buffer
)

Read websocket stream data into buffer.

See gos_read_with_buffer() for more information.

Note
Stream handles start at 1, max handle value is GOS_MAX_STREAMS
Parameters
handle Stream handle
buffer Buffer to specify how much data to read, then return how much data was read with pointer to data
Returns
gos_result_t result of api call
Examples:
network/websocket_client/main.c , and network/websocket_server/main.c .

gos_websocket_register_client_event_handlers()

void gos_websocket_register_client_event_handlers ( gos_handle_t handle,
gos_stream_event_handler_t disconnect,
gos_stream_event_handler_t receive
)

Register websocket client event handlers.

The corresponding event handlers will be called on the given websocket clients event. See gos_websocket_connect() to open a websocket client.

Note
The event handlers execute in the app thread context
Stream handles start at 1, max handle value is GOS_MAX_STREAMS
Parameters
handle Stream handle of websocket client stream (returned by gos_websocket_connect() )
disconnect Websocket client disconnect event handler
receive Websocket client data received event handler
Examples:
network/websocket_client/main.c .

gos_websocket_register_server_event_handlers()

void gos_websocket_register_server_event_handlers ( gos_stream_event_handler_t connect,
gos_stream_event_handler_t disconnect,
gos_stream_event_handler_t receive
)

Register websocket server event handlers.

The following event handler will be called on the corresponding websocket server events. Set to NULL to disable the event handler.

Note
The event handlers execute in the app thread context
Parameters
connect Websocket client connect event handler
disconnect Websocket client disconnect event handler
receive Websocket client data received event handler
Examples:
network/websocket_server/main.c .

gos_websocket_send_ping()

gos_result_t gos_websocket_send_ping ( gos_handle_t handle,
const void * data,
uint32_t size
)

Send a 'Ping' to Websocket client or server.

This sends a 'Ping' with an optional data payload to the websocket client/server. If no data payload is required then leave the 'size' paramater zero.

Note
Stream handles start at 1, max handle value is GOS_MAX_STREAMS
Parameters
handle Handle of websocket client/server stream
data Optional ping data payload, leave NULL if unused
size Size of optional data payload, leave zero if unused
Returns
gos_result_t result of api call

gos_websocket_write()

gos_result_t gos_websocket_write ( gos_handle_t handle,
const void * data,
uint32_t size,
bool continue_frame
)

Write websocket stream data.

See Gecko OS Command API documentation: stream_write .

Note
Stream handles start at 1, max handle value is GOS_MAX_STREAMS
Parameters
[in] handle Stream handle returned by API call
[in] data Data to write to stream
[in] size Size of data in bytes to write
[in] continue_frame If true then sends 'continued' websocket frame, false send 'final' websocket frame
Returns
gos_result_t result of api call
Examples:
network/websocket_client/main.c , and network/websocket_server/main.c .