Component: WebSocket (GENERIC) (Comms: Networking)
| Author | Matrix Ltd. |
| Version | 1.0 |
| Category | Comms: Networking |
WebSocket (GENERIC) component
WebSocket server and client component designed to work with the Network Comms abstraction layer. Server mode: use CreateServerSocket to listen, then poll CheckSocketActivity to accept a browser or client connection (RFC 6455 HTTP upgrade handshake) and receive frames. Client mode: use Connect to open a link to a remote WebSocket server, then poll CheckSocketActivity to receive frames. SendText / SendBinary and the GetRx macros work identically in both modes. Frames are masked automatically in client mode. Ping, pong and close control frames are handled automatically.
Detailed description
No detailed description exists yet for this component
Examples
No additional examples
Macro reference
CheckSocketActivity
|
CheckSocketActivity |
| Checks for activity on the WebSocket link. In server mode this accepts and upgrades new clients. In both modes it receives frames from the remote end. Also runs the keepalive: after Keepalive Ping idle calls it sends a ping, and after Dead Link idle calls with no reply it closes the link so a new client can be accepted. Any inbound frame resets the idle count. Returns: 0 = No activity, 1 = Client connected (server mode), 2 = Data frame received (see GetRxCount / GetRxString / GetRxByte), 3 = Remote end disconnected, 4 = Ping received (pong sent automatically) | |
 - BYTE
|
Return |
Connect
|
|
Connect |
| Client mode: connects to a remote WebSocket server and performs the HTTP upgrade handshake. Once connected use CheckSocketActivity to receive frames and SendText / SendBinary to transmit, exactly as in server mode. Returns: 1 = Connected / 0 = TCP connect failed / 2 = WebSocket handshake rejected | |
 - STRING
|
Address |
| IP address or host name of the server (used for the Host header too) | |
 - UINT
|
Port |
| Server port, usually 80 | |
| - STRING
|
Path |
| Resource path e.g. "/" or "/ws" | |
| - BYTE
|
Return |
CreateServerSocket
|
|
CreateServerSocket |
| Creates a listening socket on the selected port ready to accept incoming WebSocket connections. Returns: 1 = OK / 0 = Listen Err / 255 = Socket Open Err | |
| - UINT
|
Port |
| Default HTTP port = 80 | |
| - BYTE
|
Return |
Disconnect
|
|
Disconnect |
| Sends a close frame to the remote end and closes the connection. Works in both server and client mode. | |
 - VOID
|
Return |
GetRxByte
|
|
GetRxByte |
| Returns a single byte from the last received data frame payload. | |
| - UINT
|
Index |
| Byte index 0 to GetRxCount - 1 | |
| - BYTE
|
Return |
GetRxCount
|
|
GetRxCount |
| Returns the number of payload bytes received in the last data frame (limited to Max Frame Size - 1). | |
| - UINT
|
Return |
GetRxOpcode
|
|
GetRxOpcode |
| Returns the opcode of the last received frame: 0 = Continuation, 1 = Text, 2 = Binary, 8 = Close, 9 = Ping, 10 = Pong | |
| - BYTE
|
Return |
GetRxString
|
|
GetRxString |
| Returns the payload of the last received data frame as a string (up to 255 characters, use GetRxByte for larger frames or binary data). | |
| - STRING
|
Return |
Initialise
|
|
Initialise |
| Resets and initialises the WebSocket component. Defaults to server mode; calling Connect switches to client mode, CreateServerSocket switches back. | |
| - VOID
|
Return |
IsClientMode
|
|
IsClientMode |
| Returns 1 if the component is operating as a WebSocket client (after Connect), 0 if operating as a server. | |
 - BOOL
|
Return |
IsConnected
|
|
IsConnected |
| Returns 1 if a WebSocket link is currently open (client connected to us in server mode, or we are connected to a server in client mode), else 0. | |
| - BOOL
|
Return |
Ping
|
|
Ping |
| Sends a ping frame to the connected client. The client should reply with a pong which is consumed by CheckSocketActivity. Returns 1 if sent, 0 = not connected. | |
| - BYTE
|
Return |
SendBinary
|
|
SendBinary |
| Sends a binary frame to the connected client. Returns the number of bytes sent, 0 = not connected or failed. | |
| - STRING
|
Data |
| Data array to send | |
| - UINT
|
Count |
| Number of bytes to send | |
| - UINT
|
Return |
SendText
|
|
SendText |
| Sends a text frame to the connected client. Returns the number of bytes sent, 0 = not connected or failed. | |
| - STRING
|
Data |
| String to send | |
| - UINT
|
Return |
Property reference
|
Properties |
|
Max Frame Size (B) |
| Number of bytes reserved for the payload of a received WebSocket frame. Larger frames are truncated. | |
|
|
Timeout (ms) |
| Number of milliseconds to wait for data when performing the CheckSocketActivity macro. | |
|
|
Keepalive Ping (calls) |
| Send a ping after this many consecutive CheckSocketActivity calls with nothing received, and use the same interval between retries. Browsers reply to pings automatically but never send their own. 0 disables the keepalive entirely, so a client that vanishes without a close frame will hold the server forever. When the link is idle each call takes about Timeout ms, so 100 calls at the default 120 ms is roughly 12 seconds. | |
|
|
Keepalive Retries |
| How many extra pings to send when the first goes unanswered before declaring the link dead and freeing the server to accept a new client. 0 means give up after the first unanswered ping. The link is dropped after Keepalive Ping x (Retries + 2) idle calls. | |
|
LinkTo |
Component Source Code
Please click here to download the component source project: FC_Comp_Source_WebSocket.fcfx
Please click here to view the component source code (Beta): FC_Comp_Source_WebSocket.fcfx