(System Library)
| Application-GUID |
| Required text. The 36-byte textual GUID of the application registering with HTTPServer. |
| Address |
| Required text. The consumer’s addressing string defining the tail of the Request-URI match, for which this consumer wishes to be called-back. |
| Authenticate |
|
Optional Boolean. If TRUE, VTScada's HTTP server will authenticate the request. If FALSE or Invalid, HTTPServer performs no authentication, leaving this to the consumer. Should be left Invalid if CallbackScope is also Invalid. |
| CallbackScope |
|
Optional object reference. Specifies an object value, immediately subordinate to which are a set of subroutines that will receive various call-backs from HTTPServer, as follows. Providing Invalid for this parameter removes any previous registration for the Application-GUID and Address. |
| Comments: |
The account being used to authenticate the WebSocket request needs to have "Thin Client Access" privilege. Once registered, HTTPServer will call the NewRequest and NewWebSocket subroutines in the CallbackScope object every time a new request to create a WebSocket is received. Templates for NewRequest and NewWebSocket follow. |
NewRequest(Request, Headers, Protocol, Identifier)
This user-defined subroutine is called when a WebSocket upgrade request is received from the remote entity and has passed HTTPServer’s initial checks.
Create this module with the following parameters:
Request
This is a structure of information about the HTTP request. From this you can obtain the string holding the Request-URI from the WebSocket upgrade request.
Headers
This is a dictionary, keyed by header name, holding the complete set of HTTP headers provided in the WebSocket upgrade request.
Of note are the Authorization, Origin and Sec-WebSocket-Protocol headers.
The Authorization header should be validated to carry an acceptable authentication token, unless HTTPServer has been requested to validate this. In either case, the consumer should validate that the authentication token identifies an account with authorization to upgrade to a WebSocket. Authentication may be carried out by the consumer of the connection or by HTTPServer invoking SecurityManager. The authentication source is determined by the consumer.
Protocol
This is a pointer to a value in HTTPServer that receives the selected protocol if the consumer is going to accept the connection.
The Sec-WebSocket-Protocol header should be validated by the consumer to ensure it contains a protocol identifier that is supported by the consumer. If it does, the protocol that the consumer wishes to use is stored in the value addressed by this parameter.
Identifier
This is a pointer to a value in HTTPServer that receives a unique identifier for this connection. This identifier is passed into the NewWebSocket call-back. If the consumer accepts the upgrade, the identifier must be set.
The consumer must also decide whether to accept the request based on the number of open connections it currently has.
Return Value:
The consumer returns an integer HTTP status code from this call-back method, as follows:
- 101 - The upgrade is to be accepted. The Protocol and Identifier values addressed by the corresponding parameters must be set.
- 401 - Authentication required but not supplied.
- 403 - Forbidden.
HTTPServer will complete the handshake with the remote entity (in the case of a 101 response) as per RFC 6455, activate the WebSocket filter and call the next call-back, NewWebSocket. Error codes will cause HTTPServer to respond with the appropriate status code.
NewWebSocket(Identifier, Stream)
NewWebSocket is a user-defined module, called after a NewRequest call-back returns with a status code of 101, accepting the WebSocket upgrade request.
Create this module with the following parameters:
Identifier
The unique identifier that was provided by the consumer in the NewRequest call-back. The consumer can use this to identify which NewRequest call-back this call-back corresponds to.
Stream
This is a bi-directional stream that communicates with the remote entity using WebSocket protocol.
Ownership of the WebSocket stream belongs to the consumer and HTTPServer will take no further part in processing the stream.
When the consumer no longer requires the stream, it should be closed off, either by invalidating the last reference to the stream (resulting in a graceful close of the socket) or by CloseStream, where there is an option to forcibly close the stream via a TCP RST.
Note that data arriving at this socket from the remote entity are presented as complete messages to the stream – i.e., message fragments received from the remote entity are reassembled into a complete message before being presented to script code. Similarly, writes to this stream must be complete messages.
Like UDP, the length of the stream reported by the engine is the number of unread bytes in the current message. Messages are queued and once a message has been entirely read, the length of the stream reported by the engine will be the length of the next message (if any).
