The HTTP Server API enables applications to communicate over HTTP without using Microsoft Internet Information Server (IIS). Applications can register to receive HTTP requests for particular URLs, receive WebSocket requests, and send WebSocket responses. The HTTP Server API includes SSL support so that applications can exchange data over secure HTTP connections without IIS. It is also designed to work with I/O completion ports.
The server supports the following protocols:
By default, this component requires that your application run as Administrator mode, for URL registration. If the URL have already be registered using an external tool like netsh, you can run without Admin rights, disable the property BindingOptions.ConfigureSSLCertificate to allow start the application without admin rights.
Set FastMM4/FastMM5 as the first unit of your project.
Follow the next steps to configure this component:
1. Drop a TsgcWebSocketServer_HTTPAPI component in the form
2. Define the listening address and port:
Server.Host := '127.0.0.1';
Server.Port := 80;
3. Set Specifications allowed, by default all specifications are allowed.
RFC6455: is standard and recommended WebSocket specification.
Hixie76: it's a draft and it's only recommended to establish Hixie76 connections if you want to provide support to old browsers like Safari 4.2
4. If you want, you can handle events:
OnConnect: every time a WebSocket connection is established, this event is fired.
OnDisconnect: every time a WebSocket connection is dropped, this event is fired.
OnError: every time there is a WebSocket error (like mal-formed handshake), this event is fired.
OnMessage: every time a client sends a text message and it's received by server, this event is fired.
OnBinary: every time a client sends a binary message and it's received by server, this event is fired.
OnHandhake: this event is fired after the handshake is evaluated on the server side.
OnException: this event is fired when HTTP Server throws an exception.
OnAuthentication: if authentication is enabled, this event is fired. You can check user and password passed by the client and enable/disable Authenticated Variable.
OnUnknownProtocol: this event doesn't work at the moment of write this document.
OnBeforeHeartBeat: if HeartBeat is enabled, allows to implement a custom HeartBeat setting Handled parameter to True (this means, standard websocket ping won't be sent).
OnAsynchronous: every time an asynchronous event has been completed, this event is called.
OnBeforeForwardHTTP: allows to forward a HTTP request to another HTTP server. Use forward property to enable this and set the destination URL.
OnAfterForwardHTTP: allows to know the result of the forwarded request.
OnTCPConnect: public event, is called AFTER the TCP connection and BEFORE Websocket handshake.
5. Create a procedure and set property Active = true
The HTTP.SYS server uses URL reservation to assign which URL endpoints will be used by the HTTP.SYS server.
Basic URL Reservation
This is the most easy simple mode to configure the Server, basically you only set the Host and Port that the HTTP.SYS server will handle.
Example: if your server runs on the IP 127.0.0.1 and Port 80, just set the following properties
Server.Host := '127.0.0.1';
Server.Port := 80;
If the server runs in more than one IP and you want bind to multiple IPS, use the NewBinding Method. First clear the Host and Bindings property and then use the NewBinding method to define all Server Bindings.
Server.Host := '';
Server.Bindings.Clear;
Server.Bindings.NewBinding('127.0.0.1', 80, '');
Server.Bindings.NewBinding('80.50.55.11', 80, '');If the server requires SSL connections, do the following to define the Host and Port which will be used to handle SSL connections.
Server.Host := '127.0.0.1';
Server.Port := 443;
Server.SSL := True;
Server.SSLOptions.Hash := 'CERTIFICATE_HASH';If the server requires SSL connections with multiple IP Addresses, first clear the Host and Bindings property and the register the new Bindings.
Server.Host := '';
Server.Bindings.Clear;
Server.Bindings.NewBinding('127.0.0.1', 443, '', true, 'CERTIFICATE_HASH1');
Server.Bindings.NewBinding('80.50.55.11', 443, '', true, 'CERTIFICATE_HASH2');
Host: if the property has a value, it will be used to register the URL. If you use the Bindings property to define the server bindings, clear the value of this property.
Port: the default listening port, if the Host property has a value, the Host + Port will be used to register the URL.
Timeouts: allows overriding default timeouts of HTTP API Server.
EntityBody: the time, in seconds, allowed for the request entity body to arrive.
DrainEntityBody: The time, in seconds, allowed for the HTTP Server API to drain the entity body on a Keep-Alive connection.
RequestQueue: The time, in seconds, allowed for the request to remain in the request queue before the application picks it up.
IdleConnection: The time, in seconds, allowed for an idle connection.
HeaderWait: The time, in seconds, allowed for the HTTP Server API to parse the request header.
MinSendRate: The minimum sends rate, in bytes-per-second, for the response. The default response sends rate is 150 bytes-per-second.
MaxConnections: maximum number of connections (zero means unlimited, value by default).
MaxBandwidth: maximum allowed bandwidth rate in bytes per second (zero means unlimited, value by default).
ThreadPoolSize: by default 32 (max recommended value 64), allows setting number of threads of HTTP API Server.
ReadBufferSize: by default 16384, allows to modify the size of the buffer size when read socket data.
WriteTimeOut: only applies when Asynchronous = False, the value is measured in milliseconds. When this property is greater than zero, if the time to send a message is greater than the value set in the property, the request is cancelled and the connection is closed. By default, is zero, so there is no timeout writing a message. The internal thread that handles the timeouts, by default uses an interval of 10 seconds, so it means that every 10 seconds checks if there is any message that have exceeded the timeout. You can modify the value of the interval setting the value in the property WriteTimeoutInterval (in seconds, the value must be greater or equal to 5 seconds).
Asynchronous: by default is disabled, if enabled, messages sent don't wait till completed. You can check when asynchronous is completed OnAsynchronous event.
SSLOptions: here you can customize ssl properties.
CertStoreName: (optional) allows to set the name of certificate store where is certificate. If no value is set, 'MY' is assumed as default name.
Hash: this is the hexadecimal thumbprint value of certificate and is required by server to retrieve certificate. You can find hash of certificate using powershell, running a "dir" comand on the certificates store, example: dir cert:\localmachine\my.
Broadcast: sends a message to all connected clients.
Message / Stream: message or stream to send to all clients.
Channel: if you specify a channel, the message will be sent only to subscribers.
Protocol: if defined, the message will be sent only to a specific protocol.
Exclude: if defined, list of connection guid excluded (separated by comma).
Include: if defined, list of connection guid included (separated by comma).
WriteData: sends a message to a single or multiple clients. Every time a Client establishes a WebSocket connection, this connection is identified by a Guid, you can use this Guid to send a message to a client.
Ping: sends a ping to all connected clients.
DisconnectAll: disconnects all active connections.
HTTPUploadFiles: by default when a client sends a file using a POST stream, the file is saved in memory. If you want to save these streams directly as files to avoid memory problems, you set the StreamType to pstFileStream and the files will be saved in the hard disk. Read more about Post Big Files.
MinSize: Minimum size in bytes of the stream to be saved as a file stream. By default is zero, which means all streams will be saved as FileStreams (if StreamType = pstFileStream).
RemoveBoundaries: the files uploaded using POST multipart/form-data, are encapsulated in boundaries, if this property is enabled, the files will be extracted from boundaries and saved in the hard disk.
SaveDirectory: the folder where the files will be saved. If empty, will be saved in the same folder where is the application.
StreamType: the type of the stream where the stream will be saved, by default memory.
pstMemoryStream: as memory stream.
pstFileStream: as file stream.