Message reception

In the WebSocket Protocol, data are exchanged using sequences of frame to form WebSocket Messages. The user doesn't need to know how the WebSocket data framing works since the µC/HTTP-client WebSocket module manages it internally. The µC/HTTP-client WebSocket API simplifies the application development by using the concept of message which can be summarized by its Type, Payload Length and Contents. 

WebSocket Messages can have 5 differents types divided in 2 groups.   

Control MessageData Message
CloseText
PingBinary
Pong 

Control Message

Control messages are intended to be used for protocol-level signaling. Note that their payload length cannot exceed 125 byte and they cannot be fragmented (only one frame per message).

Since it's more protocol related, they are managed directly by the WebSocket Module which provides hook to notify the application.  

Message TypeWebSocket Module Behavior
CloseWhen a Close message is received from the remote server, the WebSocket module will start the closing handshake. Once it's done, successfully or not, it will call the hook On Close
PingWhen a Ping message is received from the remote server, the WebSocket module will reply the correct Pong message. The application won't be notify.
PongWhen a Pong message is received from the remote server, the WebSocket module will simply call the hook On Pong.

Data Messages

Data messages are intended to transport information. Their length can vary from 0 to 2^64 and can be fragmented. They can be divided in two type.

Message Type 
TextThe content must respected UTF-8 standard.
BinaryThe content is not restricted.

Note that the µC/HTTP-client WebSocket module doesn't validate UTF-8 and must be done by the user application if necessary.

The reception of any Data Messages are done through hooks that are configured in the HTTPc_WEBSOCK_OBJ and that must be set before the connection upgrade request (HTTPc_WebSockUpgrade()).

NameDescriptionObjectParameter Type
On Message Reception Initialization

Called at the beginning of the WebSocket Data Type message reception.

HTTPc_WEBSOCK_OBJHTTPc_PARAM_TYPE_WEBSOCK_ON_MSG_RX_INIT
On Message RX Data

Called each time a chunk of the message is received is available.

HTTPc_WEBSOCK_OBJHTTPc_PARAM_TYPE_WEBSOCK_ON_MSG_RX_DATA
On Message RX CompleteCalled when the Data message is completely received.HTTPc_WEBSOCK_OBJHTTPc_PARAM_TYPE_WEBSOCK_ON_MSG_RX_COMPLETE

Note that only one Data Message is processed at a time. 

Data Message Reception Mode

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

Normal mode

Normal Mode use all of the three Data Message Reception hooks. It allow the user to be notify every time a message payload chunk is available with the On Message RX Data hook.Thus, the application can parse a message during its reception without having to copying it all in a buffer.

This mode is useful when the memory footprints is critical and the message length can be long or undefined. 

Normal Mode Example

Auto mode

Auto Mode only use two hooks. During On Message Reception Initialization, it is possible to set a pointer to the buffer where the message payload must be set. If the application do so, the message will be automatically copied to the specified buffer. Once the message is completely received, On Message RX Complete hook will be called and data will be available is the buffer previously set.

This mode is useful for simpler application which the message length received from other endpoint are small and size-limited 

Auto Mode Example