WebSocket Client/Server

WebSocket client/server functions. More...

Modules

Types
WebSocket data types.
 

Functions

zos_result_t zn_websocket_connect (zos_interface_t interface, const char *host, uint32_t *handle)
 Connect to a remote websocket server. More...
 
zos_result_t zn_websocket_connect_with_config (const zos_websocket_config_t *config, uint32_t *handle)
 Connect to a remote websocket server with configuration. More...
 
zos_result_t zn_websocket_get_info (uint32_t handle, char *host_buffer, uint8_t buffer_len, uint16_t *port)
 Return information about websocket stream. More...
 
zos_result_t zn_websocket_read (uint32_t handle, void *data, uint32_t max_size, uint32_t *bytes_read)
 Read websocket stream data. More...
 
zos_result_t zn_websocket_read_with_buffer (uint32_t handle, zos_buffer_t *buffer)
 Read websocket stream data into buffer. More...
 
zos_result_t zn_websocket_write (uint32_t handle, const void *data, uint32_t size, zos_bool_t continue_frame)
 Write websocket stream data. More...
 
zos_result_t zn_websocket_disconnect (uint32_t handle)
 Close websocket stream. More...
 
zos_result_t zn_websocket_poll (uint32_t handle, uint32_t *bytes_available)
 Poll websocket stream for RX data. More...
 
zos_result_t zn_websocket_send_ping (uint32_t handle, const void *data, uint32_t size)
 Send a 'Ping' to Websocket client or server. More...
 
zos_result_t zn_websocket_client_read_frame (uint32_t handle, zos_websocket_frame_t *frame, uint32_t timeout)
 Read complete websocket frame. More...
 
void zn_websocket_register_server_event_handlers (zos_stream_event_handler_t connect, zos_stream_event_handler_t disconnect, zos_stream_event_handler_t receive)
 Register websocket server event handlers. More...
 
void zn_websocket_register_client_event_handlers (uint32_t handle, zos_stream_event_handler_t disconnect, zos_stream_event_handler_t receive)
 Register websocket client event handlers. More...
 

Detailed Description

WebSocket client/server functions.

Function Documentation

zos_result_t zn_websocket_client_read_frame ( uint32_t  handle,
zos_websocket_frame_t frame,
uint32_t  timeout 
)

Read complete websocket frame.

Examples:
nxp/nfc3d/cloud_websocket.c.
zos_result_t zn_websocket_connect ( zos_interface_t  interface,
const char *  host,
uint32_t *  handle 
)

Connect to a remote websocket server.

This opens a websocket client stream.

See ZentriOS Command API documentation: websocket_client.

Parameters
interfaceThe network interface to open connect
hostThe remote websocket server's URL
handleThe stream handle of the opened websocket client stream
Returns
zos_result_t result of api call
zos_result_t zn_websocket_connect_with_config ( const zos_websocket_config_t config,
uint32_t *  handle 
)

Connect to a remote websocket server with configuration.

See ZentriOS Command API documentation: websocket_client.

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

Parameters
configWebsocket client configuration
handleThe stream handle of the opened websocket client stream
Returns
zos_result_t result of api call
zos_result_t zn_websocket_disconnect ( uint32_t  handle)

Close websocket stream.

See ZentriOS Command API documentation: stream_close.

Parameters
[in]handleHandle of stream to close
Returns
zos_result_t result of api call
Examples:
basic/websocket_client/websocket_client.c, and nxp/nfc3d/cloud_websocket.c.
zos_result_t zn_websocket_get_info ( uint32_t  handle,
char *  host_buffer,
uint8_t  buffer_len,
uint16_t *  port 
)

Return information about websocket stream.

See ZentriOS Command API documentation: stream_list.

Returns information about a websocket client or server stream.

Parameters
handleStream handle of opened websocket stream
host_bufferString buffer to hold websocket host info
buffer_lenLength of host_buffer buffer
portPointer to hold local port of websocket stream
Returns
zos_result_t result of api call
zos_result_t zn_websocket_poll ( uint32_t  handle,
uint32_t *  bytes_available 
)

Poll websocket stream for RX data.

Parameters
[in]handleHandle of stream to poll
[out]bytes_availablePointer to hold number of bytes available to read
Returns
zos_result_t result of api call
Examples:
nxp/nfc3d/cloud_websocket.c.
zos_result_t zn_websocket_read ( uint32_t  handle,
void *  data,
uint32_t  max_size,
uint32_t *  bytes_read 
)

Read websocket stream data.

See ZentriOS Command API documentation: stream_read.

Parameters
[in]handleStream handle returned by API call
[out]dataBuffer to hold read data
[in]max_sizeMaximum amount of data to read
[out]bytes_readPointer to hold actual amount of data read (set NULL if not used)
Returns
zos_result_t result of api call
Examples:
basic/websocket_client/websocket_client.c, and basic/websocket_server/websocket_server.c.
zos_result_t zn_websocket_read_with_buffer ( uint32_t  handle,
zos_buffer_t buffer 
)

Read websocket stream data into buffer.

See zn_read_with_buffer() for more information.

Parameters
handleStream handle
bufferBuffer to specify how much data to read, then return how much data was read with pointer to data
Returns
zos_result_t result of api call
void zn_websocket_register_client_event_handlers ( uint32_t  handle,
zos_stream_event_handler_t  disconnect,
zos_stream_event_handler_t  receive 
)

Register websocket client event handlers.

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

Note
The event handlers execute in the Zap thread context
Parameters
handleStream handle of websocket client stream (returned by zn_websocket_connect() )
disconnectWebsocket client disconnect event handler
receiveWebsocket client data received event handler
Examples:
basic/websocket_client/websocket_client.c, and nxp/nfc3d/cloud_websocket.c.
void zn_websocket_register_server_event_handlers ( zos_stream_event_handler_t  connect,
zos_stream_event_handler_t  disconnect,
zos_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 Zap thread context
Parameters
connectWebsocket client connect event handler
disconnectWebsocket client disconnect event handler
receiveWebsocket client data received event handler
Examples:
basic/websocket_server/websocket_server.c.
zos_result_t zn_websocket_send_ping ( uint32_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.

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
zos_result_t result of api call
zos_result_t zn_websocket_write ( uint32_t  handle,
const void *  data,
uint32_t  size,
zos_bool_t  continue_frame 
)

Write websocket stream data.

See ZentriOS Command API documentation: stream_write.

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 ZOS_TRUE then sends 'continued' websocket frame, ZOS_FALSE send 'final' websocket frame
Returns
zos_result_t result of api call
Examples:
basic/websocket_client/websocket_client.c, basic/websocket_server/websocket_server.c, and nxp/nfc3d/cloud_websocket.c.