HTTP Server Stream
Protocols

HTTP server stream functions. More...

Modules

Types
HTTP server stream data types.
 
Macros
HTTP server stream macros.
 

Functions

zos_result_t zn_hs_stream_register_callback (const char *stream, zos_hs_stream_callback_t callback, void *arg)
 Register a stream and corresponding callback. More...
 
void zn_hs_stream_unregister_callbacks (void)
 Unregister call stream callbacks. More...
 
zos_result_t zn_hs_register_websocket_callbacks (zos_hs_ws_connect_callback_t connect, zos_hs_ws_disconnect_callback_t disconnect)
 Register websocket event handler. More...
 
zos_result_t zn_hs_stream_write (zos_hs_handle_t handle, const char *data_str, zos_bool_t final_write)
 Write data to a stream within callback. More...
 
zos_result_t zn_hs_stream_write_listener (zos_hs_handle_t handle, const char *stream, const char *data_str, zos_bool_t final_write)
 Asynchronously write data to a listening stream. More...
 
zos_result_t zn_hs_stream_read (zos_hs_handle_t handle, char **data_ptr, uint16_t *data_len)
 Read data from within a stream callback. More...
 

Detailed Description

HTTP server stream functions.

Function Documentation

zos_result_t zn_hs_register_websocket_callbacks ( zos_hs_ws_connect_callback_t  connect,
zos_hs_ws_disconnect_callback_t  disconnect 
)

Register websocket event handler.

These callbacks will be called when a websocket connects or disconnects.

Note
The 'connect' callback executes in the HTTP server thred context The 'disconnect' callback executes in the Zap thread context
Parameters
connectsee zos_hs_ws_connect_callback_t
disconnectsee zos_hs_ws_disconnect_callback_t
Returns
zos_result_t result of api call
zos_result_t zn_hs_stream_read ( zos_hs_handle_t  handle,
char **  data_ptr,
uint16_t *  data_len 
)

Read data from within a stream callback.

This should be called from within a stream callback. This reads data from the remote caller. This returns a pointer to the read data buffer. The format of the data is dependent on the remote caller. Optionally use json_decode_buffer or base64_decode to decode the data string.

Parameters
handleStream handle supplied by the zos_hs_stream_callback_t callback with HS_STREAM_READ method
data_ptrBuffer to hold pointer to data string
data_lenOptional, pointer to hold length of data string. Leave NULL if unused
Returns
zos_result_t result of api call
zos_result_t zn_hs_stream_register_callback ( const char *  stream,
zos_hs_stream_callback_t  callback,
void *  arg 
)

Register a stream and corresponding callback.

Note
If using the REST implementation, callback is in HTTP server thread context, if using the websocket implementation, callback is in Zap thread context
Parameters
streamThe name of the stream
callbackPointer to function callback. This will be called whenever a remote client issues a request
argOptional, argument to be supplied to callback
Returns
zos_result_t result of api call
void zn_hs_stream_unregister_callbacks ( void  )

Unregister call stream callbacks.

Returns
zos_result_t result of api call
zos_result_t zn_hs_stream_write ( zos_hs_handle_t  handle,
const char *  data_str,
zos_bool_t  final_write 
)

Write data to a stream within callback.

This should be called from within a stream callback. This will send data to the remote caller. This may be called multiple times within the same callback. The parameter final_write should be set to ZOS_TRUE on the final write.

Note
The data argument MUST be a valid JSON string. Use json_encode_buffer or base64_encode to encode the supplied data string.
Parameters
handleStream handle supplied by the zos_hs_stream_callback_t callback with HS_STREAM_WRITE method
data_strnull terminated data string with valid JSON encoding
final_writeZOS_TRUE if final write, ZOS_FALSE if more calls to zn_hs_stream_write() will follow
Returns
zos_result_t result of api call
zos_result_t zn_hs_stream_write_listener ( zos_hs_handle_t  handle,
const char *  stream,
const char *  data_str,
zos_bool_t  final_write 
)

Asynchronously write data to a listening stream.

This allows for asynchronously writing a stream. HS_STREAM_LISTEN must have been previously called before using this API.

This may be called anytime after HS_STREAM_LISTEN has been sent for a given stream. This will send data to the remote caller. This may be called multiple times for a given stream. The parameter final_write should be set to ZOS_TRUE on the final write.

Note
The data argument MUST be a valid JSON string. Use json_encode_buffer or base64_encode to encode the supplied data string.
Parameters
handleHandle supplied by a HS_STREAM_LISTEN callback
streamName of a listening stream
data_strnull terminated data string with valid JSON encoding
final_writeZOS_TRUE if final write, ZOS_FALSE if more calls to zn_hs_stream_write() will follow
Returns
zos_result_t result of api call