httpWriteWebSocket()
The function writes web sockets.
Synopsis
int httpWriteWebSocket(int idx, <string|blob|anytype>
message);
Parameter
| Parameter | Description |
|---|---|
| idx | The internal file descriptor of the opened TCP/IP connection in order to address the webSocket. |
| message | The message that is sent (written). See the example further below. |
Return value
The function httpWriteWebSocket returns 0 on success, otherwise -1.
Error
Wrong or missing arguments.
Description
In the WebSocket protocol the client (browser) establishes a connection to the server. The server can send data to the browser without a request from the browser. Equally, the browser can send data to the server. This provides a significant advantage: the server sends updates and notifications to the client without waiting for a client request. Furthermore, the webSockets do not contain header data like HTTP and less bandwith is required for the communication. The TCP connection remains active after the data transmission and a bidirectional transmission of data is still possible.
When the WebSocket functions are used, the function httpConnect() must be used with the specific "_websocket_" flag (see example further below). The specific flag "_websocket_" declares this URL as a webSocket in the function httpConnect().
This means that webSockets can only be used on the server-side. A webSocket connection to another server than the WinCC OA Server is not supported via CTRL.
If a client (web browser) addresses the URL as webSocket ("_websocket_"), the HTTP server starts the callback function in a thread and passes a mapping (see example further below).
The mapping contains:
| "idx"/int | The internal file descriptor of the opened TCP/IP connection in order to address the webSocket. |
| "headers"/mapping | All HTTP headers of the request to open the webSockets. |
| "user"/string | Authenticated user |
| "ip"/string | IP Address of the client |
For webSockets only text or binary messages are available. You can pass a string or a blob or either of them in an anytype/mixed. The text is passed in UTF-8 format. The text in the local project is converted via CTRL into the active project language encoding.
Example
The following example activates the HTTP server, registers the function "websocket" as a web resource and reads and writes WebSocket messages via the functions httpWriteWebSocket and httpReadWebSocket.
|
#uses "CtrlHTTP" void main() { httpServer(false,8080); /* Activates an HTTP server, authentication is not used, the port 8080 is used*/ httpConnect("websocket","/websocket","_websocket_"); /* The function registers the function "websocket" as web resource */ } dyn_mixed writeData; void websocket(mapping map) /*Function definition*/ { DebugN("WebSocket callback", map); mixed any; while ( httpReadWebSocket(map["idx"], any) == 0 ) { DebugN("message received", any); /*Reads and outputs the messages */ DebugN("sent message back", httpWriteWebSocket(map["idx"], any)); /*Sends the messages back*/ any = ""; } DebugN("webSocket closed"); } } |
Assignment
CTRL PlugIn
Availability
CTRL
