Sending Message

The user can send a WebSocket message with HTTPc_WebSockSend() function and a properly initialized HTTPc_WEBSOCK_MSG_OBJ. To set the type, the payload content and length of a message, it is possible to either configure it with HTTPc_WebSockSend() parameters or with hooks configured for each message.

For message transmission, it's possible to send all the message type available :

HTTPc_WEBSOCK_MSG_TYPE_TXT
HTTPc_WEBSOCK_MSG_TYPE_BIN
HTTPc_WEBSOCK_MSG_TYPE_CLOSE
HTTPc_WEBSOCK_MSG_TYPE_PING
HTTPc_WEBSOCK_MSG_TYPE_PONG

Here a list of the available Transmission hooks.

Name	Description	Object	Parameter Type
On Message TX Initialization	Called when the message is ready to be sent.	HTTPc_WEBSOCK_OBJ	HTTPc_PARAM_TYPE_WEBSOCK_ON_MSG_TX_INIT
On Message TX Data	Called to set the internal connection buffer of a data chunk of a message to send.	HTTPc_WEBSOCK_OBJ	HTTPc_PARAM_TYPE_WEBSOCK_ON_MSG_TX_DATA
On Message TX Complete	Called when the message is completely transmitted.	HTTPc_WEBSOCK_OBJ	HTTPc_PARAM_TYPE_WEBSOCK_ON_MSG_TX_COMPLETE

Transmission Mode

The hooks described in the previous section can be use in many different ways. However, those can be group in three different mode.

Mode	Buffer used	Message Length	On Message TX Initialization	On Message TX Data	On Message TX Complete
Normal	External data buffer set when HTTPc_WebSockSend() is called.	Defined at the beginning when HTTPc_WebSockSend is called.	Not Used	Not Used	Optional
Hooks	Internal Connection data buffer is used to construct message to transmit.	Defined either when HTTPc_WebSockSend() is called or with On Message TX Initialization hook.	Optional	Used	Optional
Dynamic	Internal Connection data buffer is used to construct message to transmit.	Defined either when HTTPc_WebSockSend() is called or with On Message TX Initialization hook and MUST be HTTPc_WEBSOCK_TX_MSG_LEN_NOT_DEFINED	Optional	Used	Optional

Normal Mode

Normal mode only use HTTPc_WebSockSend() and doesn't required hook. The application must provide a pointer to the message payload data and its length that will be used during the transmission.

This mode is simple to use and suitable for non-complex application.

Hook Mode

Hook mode allows to use directly the connection buffer to send a message using hooks.

The application must provide the length of the message at the beginning either with HTTPc_WebSockSend() or with the On Message TX Initialization hook.
Then, On Message TX Data is called and provide the application a pointer to the internal connection buffer and the available length.
Once the application has set the buffer, it must return the total number of bytes used in this buffer.
On Message TX Data is called until the message is completely sent, thus the length set at the beginning is match the total length sent.

This mode allow to save memory space by using directly the connection buffer. However, the message length must be known at the beginning.

Dynamic Mode

Dynamic mode use the message fragmentation mechanism that the WebSocket protocol provides to transfer message. It allows to send a message without knowing the total message and to use directly the connection buffer to construct the message to send, thereby reducing the memory footprints.

To use this mode, two points are important:

The length of the message must be set to HTTPc_WEBSOCK_TX_MSG_LEN_NOT_DEFINED. It possible to either set it during HTTPc_WebSockSend() is called or using the On Message TX Initialization hook.
Then, On Message TX Data is called and provide the application a pointer to the internal connection buffer and the available length.
Each time the On Message TX Data is called, the application must set the buffer and return the numbers of bytes to be sent.
To complete the message, 0 value must be returned from this function.

This mode help saving memory space by using directly the connection buffer to construct messages and allows to start the data transmission without knowing the total message length.

Note that it is not possible to send Control Message (Close, Ping or Pong) in Dynamic Mode. Those messages must be sent either in Hook Mode or Normal Mode.

Non-Blocking Option

An non-blocking option is available when HTTPc_WebSockSend() is called by using the flag HTTPc_FLAG_WEBSOCK_NO_BLOCK . If used, On Message TX Complete hook must be set. It allows to queue message without having to wait the completion of each message transmission.