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
interfaceThe network interface to open connect
hostThe remote websocket server's URL
handle_ptrThe 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
configWebsocket client configuration
handle_ptrThe 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]handleHandle 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]handleClient stream handle
[in]host_bufferBuffer to hold client host domain or IP address string
[in]host_buffer_lenLength of host_buffer
[in]local_port_ptrPointer to hold client's local port, leave NULL to ignore
[in]remote_port_ptrPointer 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]handleHandle of stream to poll
[out]rx_bytes_availablePointer to hold number of bytes available to read
[out]tx_bytes_availablePointer 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]handleStream handle returned by API call
[out]dataBuffer to hold read data
[in]max_sizeMaximum amount of data to read
[out]bytes_read_ptrPointer 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
handleStream handle
bufferBuffer 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
handleStream handle of websocket client stream (returned by gos_websocket_connect() )
disconnectWebsocket client disconnect event handler
receiveWebsocket 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
connectWebsocket client connect event handler
disconnectWebsocket client disconnect event handler
receiveWebsocket 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
handleHandle of websocket client/server stream
dataOptional ping data payload, leave NULL if unused
sizeSize 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]handleStream handle returned by API call
[in]dataData to write to stream
[in]sizeSize of data in bytes to write
[in]continue_frameIf 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.