Message reception
- Former user (Deleted)
- Former user (Deleted)
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 Message | Data Message |
|---|---|
| Close | Text |
| Ping | Binary |
| 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 Type | WebSocket Module Behavior |
|---|---|
| Close | When 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 |
| Ping | When a Ping message is received from the remote server, the WebSocket module will reply the correct Pong message. The application won't be notify. |
| Pong | When 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 | |
|---|---|
| Text | The content must respected UTF-8 standard. |
| Binary | The 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()).
| Name | Description | Object | Parameter Type |
|---|---|---|---|
| On Message Reception Initialization | Called at the beginning of the WebSocket Data Type message reception. | HTTPc_WEBSOCK_OBJ | HTTPc_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_OBJ | HTTPc_PARAM_TYPE_WEBSOCK_ON_MSG_RX_DATA |
| On Message RX Complete | Called when the Data message is completely received. | HTTPc_WEBSOCK_OBJ | HTTPc_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.
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