Sending Message
- Former user (Deleted)
- Former user (Deleted)
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.