Difference between revisions of "TWSocketServer"

From Overbyte
Jump to navigation Jump to search
Line 26: Line 26:
 
| valign="top" | [[TWSocketServer.BannerTooBusy | BannerTooBusy]] |||| A short message sent when a client connects and the number of clients already exceeds the MaxClients limit.
 
| valign="top" | [[TWSocketServer.BannerTooBusy | BannerTooBusy]] |||| A short message sent when a client connects and the number of clients already exceeds the MaxClients limit.
 
|-
 
|-
| valign="top" | [[TWSocketServer.Client | Client]] |||| Indexed property giving access to all connected clients.
+
| valign="top" | [[TWSocketServer.Client | Client]] |||| Currently active clients of ClientClass, indexed base zero.  Note the index value may change each time a new client connects or disconnects, so check CliId to confirm it's the correct one.
 
|-
 
|-
| valign="top" | [[TWSocketServer.ClientClass | ClientClass]] |||| Class the component use to handle each incoming connection.
+
| valign="top" | [[TWSocketServer.ClientClass | ClientClass]] |||| The class type the application has derived from TSslWSocketClient for client application code.
 
|-
 
|-
 
| valign="top" | [[TWSocketServer.ClientCount | ClientCount]] |||| Number of connected clients.
 
| valign="top" | [[TWSocketServer.ClientCount | ClientCount]] |||| Number of connected clients.
Line 40: Line 40:
 
| valign="top" | [[TWSocketServer.LastError | LastError]] |||| Last error which occurred.
 
| valign="top" | [[TWSocketServer.LastError | LastError]] |||| Last error which occurred.
 
|-
 
|-
| valign="top" | [[TWSocketServer.ListenBacklog | ListenBacklog]] |||| How many pending connection the system has to accept before denying access.
+
| valign="top" | [[TWSocketServer.ListenBacklog | ListenBacklog]] |||| How many new client connections should be queued by Windows while the server accepts them, before the server starts rejecting new connections by immediately closing them.  Recommended as 15 for heavy use servers, may be up to 250.
 
|-
 
|-
| valign="top" | [[TWSocketServer.MaxClients | MaxClients]] |||| Max number of connected client. All subsequent connections will be closed.
+
| valign="top" | [[TWSocketServer.MaxClients | MaxClients]] |||| Maximum number of simultaneous clients the server should accept if non-zero. Any further clients will receive then BannerTooBusy response and the connection closed, until earlier connections are closed.
 
|-
 
|-
 
| valign="top" | [[TWSocketServer.MultiListenSockets |MultiListenSockets]] |||| Allows one or more extra server listen IP addresses and ports to be specified, as type TWSocketMultiListenCollection, allowing server to listen on several IP addresses/ports at the same time, in addition to the that specified as Addr/Port props. Each TWSocketMultiListenItem has Addr, Port, SocketFamily, SslEnable and ListenBacklog properties. Better to use IcsHosts for new applications which does the same, ignored if any IcsHosts specified.
 
| valign="top" | [[TWSocketServer.MultiListenSockets |MultiListenSockets]] |||| Allows one or more extra server listen IP addresses and ports to be specified, as type TWSocketMultiListenCollection, allowing server to listen on several IP addresses/ports at the same time, in addition to the that specified as Addr/Port props. Each TWSocketMultiListenItem has Addr, Port, SocketFamily, SslEnable and ListenBacklog properties. Better to use IcsHosts for new applications which does the same, ignored if any IcsHosts specified.
Line 61: Line 61:
 
|-
 
|-
 
| valign="top" | [[TWSocketServer.State | State]] |||| Gives the state of the component.
 
| valign="top" | [[TWSocketServer.State | State]] |||| Gives the state of the component.
 +
|-
 +
| valign="top" | [[TWSocketServer.SocketErrs | SocketErrs ]] ||||How socket error messages should be presented as type TSocketErrs,
 +
              wsErrTech or wsErrFriendly.
 +
|-
 +
| valign="top" | [[TWSocketServer.ExclusiveAddr | ExclusiveAddr]] |||| True is other applications should be blocked from sharing the
 +
              server IP addresses.
 +
|-
 +
| valign="top" | [[TWSocketServer.RootCA | RootCA ]] |||| Specifying a file name containing a PEM bundle of trusted root SSL certificates allows validation of SSL server certificate chains. ICS includes RootCaCertsBundle.pem (large) and TrustedCABundle.pem (medium size), and a default built-in (small) that will be used if no file is specified.
 +
|-
 +
| valign="top" | [[TWSocketServer.DHParams | DHParams ]] ||||Specifies a DHParams file name, created using the PenTools sample, or use the provided dhparam1024.pem or dhparam2048.pem files. Used  for DH and DHE ciphers, but not needed for modern ECDHE ciphers. Rather than a file name, may be an ASCII PEM string containing the DHParams without any line endings.
 +
|-
 +
| valign="top" | [[TWSocketServer.SslCliCertMethod | SslCliCertMethod ]] |||| Allows server to request a client SSL certificate from the browser or remote application, as type TSslCliCertMethod, with sslCliCertNone, sslCliCertOptional or sslCliCertRequire. Require will close the connection unless a valid certificate is received and validated against RootCA. Beware requesting a client certificate usually causes the browser to prompt the user for which certificate to send which can be obtrusive.
 +
|-
 +
| valign="top" | [[TWSocketServer.CertExpireDays | CertExpireDays]] |||| When using IcsHosts, the number of days before an SSL server certificate is due to expire that warnings will be generated (by the method RecheckSslCerts, perhaps triggering automatic SSL certificate ordering.
 +
|-
 +
| valign="top" | [[TWSocketServer.SslCertAutoOrder | SslCertAutoOrder ]] |||| True if IcsHosts are allowed to order and install SSL certificates automatically.  Requires SslX509Certs property to be set, and CertSupplierProto set for any IcsHost that will order certificates.
 +
|-
 +
| valign="top" | [[TWSocketServer.SslX509Certs | SslX509Certs ]] |||| Assign to a TSslX509Certs component if automatic SSL certificate ordering is required.  Ir ia very important that the onCertProg is used to log progress messages from the certificate ordering process in case of errors.  The onCertsChallengeDNS event is called if a DNS server should be updated, onCertsOAuthAuthUrl if 0Auth2 authenication is needed, and onCertsNewCert when a new certificate is available which should be logged and the              RecheckSslCerts method called to cause the server to load it.
 +
 
|}
 
|}
  

Revision as of 19:26, 14 November 2018

Main page -> ICS component reference -> TWSocketServer and TSslWSocketServer

Overview

unit OverbyteIcsWSocketS.pas
inheritance TWSocket

TWSocketServer will normally be used to listen on a given TCP port. When a client connects, it will instantiate a new TWSocketClient component to handle communication with client. Normally you will derive your own component from TWSocketClient to add private data and methods to handle your processing needs. You tell TWSocketServer which component class it has to instantiate using ClientClass property. You have to initialize each instance created to handle each client from OnClientConnect event handler. TWSocketServer maintain a list of connected clients. You can access it using Client[] indexed property. ClientCount property is the size of Client[] array.

Since it is derived from TWSocket and TSslWSocket, lots of properties and events are unused and not listed here. Properties and events that have a meaning in both server or client component are listed here.

Note that TWSocketServer is only usable for incoming TCP connections. Use TWSocket if you need to use UDP.

Note: When a TWSocketClient is closed, it automatically frees itself. With a normal TWSocket, the programmer is responsible for freeing the object.

Properties

Addr Server listen IP address, IPv4 or IPv6, maybe 0.0.0.0 or :: to listen on all available addresses, ignored if any IcsHosts specified. IP address must exist and not be in use elsewhere for the same port.
Banner A short message line sent when each client connects. Should generally be blank.
BannerTooBusy A short message sent when a client connects and the number of clients already exceeds the MaxClients limit.
Client Currently active clients of ClientClass, indexed base zero. Note the index value may change each time a new client connects or disconnects, so check CliId to confirm it's the correct one.
ClientClass The class type the application has derived from TSslWSocketClient for client application code.
ClientCount Number of connected clients.
Handle Handle of the hidden window used for socket operation.
HSocket Underlying winsock socket handle.
IcsHosts Allows one or more TIcsHosts to be set, as TIcsHostCollection, an alternate way for specifying multiple listeners that allows multiple hosts to be specified, each with one or two IP addresses and non-SSL and SSL port bindings, SSL certificates and private key (perhaps combined in a bundle), SSL context and security level, and other web server host related properties (used by higher level components). Each IcsHost has one or more HostNames to which it will recognise, that can share IP addresses.
LastError Last error which occurred.
ListenBacklog How many new client connections should be queued by Windows while the server accepts them, before the server starts rejecting new connections by immediately closing them. Recommended as 15 for heavy use servers, may be up to 250.
MaxClients Maximum number of simultaneous clients the server should accept if non-zero. Any further clients will receive then BannerTooBusy response and the connection closed, until earlier connections are closed.
MultiListenSockets Allows one or more extra server listen IP addresses and ports to be specified, as type TWSocketMultiListenCollection, allowing server to listen on several IP addresses/ports at the same time, in addition to the that specified as Addr/Port props. Each TWSocketMultiListenItem has Addr, Port, SocketFamily, SslEnable and ListenBacklog properties. Better to use IcsHosts for new applications which does the same, ignored if any IcsHosts specified.
MultiListenIndex Read only, which listen socket accepted last connection, -1 if default Addr.Poprt used, 0 or above is index into MultiListenSockets collection.
Port TCP port or service name to listen to, usually 80 or 443, ignored if any IcsHosts specified.
PortNum Readonly property with numeric value corresponding to Port.
Proto Protocol used. Must be 'tcp'.
SocketFamily IP address socket family as TSocketFamily, from sfIPv4, sfIPv6.
SslEnable True if an SSL connection should be negotiated. ignored if any IcsHosts specified.
SslContext Assign to an TSslContext component for SSL support, where SSL certificates, keys, protocols and ciphers are specified, ignored if any IcsHosts specified.
State Gives the state of the component.
SocketErrs How socket error messages should be presented as type TSocketErrs,
              wsErrTech or wsErrFriendly.
ExclusiveAddr True is other applications should be blocked from sharing the
              server IP addresses.
RootCA Specifying a file name containing a PEM bundle of trusted root SSL certificates allows validation of SSL server certificate chains. ICS includes RootCaCertsBundle.pem (large) and TrustedCABundle.pem (medium size), and a default built-in (small) that will be used if no file is specified.
DHParams Specifies a DHParams file name, created using the PenTools sample, or use the provided dhparam1024.pem or dhparam2048.pem files. Used for DH and DHE ciphers, but not needed for modern ECDHE ciphers. Rather than a file name, may be an ASCII PEM string containing the DHParams without any line endings.
SslCliCertMethod Allows server to request a client SSL certificate from the browser or remote application, as type TSslCliCertMethod, with sslCliCertNone, sslCliCertOptional or sslCliCertRequire. Require will close the connection unless a valid certificate is received and validated against RootCA. Beware requesting a client certificate usually causes the browser to prompt the user for which certificate to send which can be obtrusive.
CertExpireDays When using IcsHosts, the number of days before an SSL server certificate is due to expire that warnings will be generated (by the method RecheckSslCerts, perhaps triggering automatic SSL certificate ordering.
SslCertAutoOrder True if IcsHosts are allowed to order and install SSL certificates automatically. Requires SslX509Certs property to be set, and CertSupplierProto set for any IcsHost that will order certificates.
SslX509Certs Assign to a TSslX509Certs component if automatic SSL certificate ordering is required. Ir ia very important that the onCertProg is used to log progress messages from the certificate ordering process in case of errors. The onCertsChallengeDNS event is called if a DNS server should be updated, onCertsOAuthAuthUrl if 0Auth2 authenication is needed, and onCertsNewCert when a new certificate is available which should be logged and the RecheckSslCerts method called to cause the server to load it.

Methods

Abort Abort current asynchronous operation.
Close Stops listening, does not disconnect connected clients.
CloseDelayed Same as Close however it's executed delayed, after current event has finished.
Create Create a new instance of the component.
Destroy Destroy the current instance.
IsClient Check if a component reference is one of the connected clients.
Listen Start accepting connections.
MessageLoop Internal message loop.
MessagePump Internal message pump.
ProcessMessage Process a single message.
ProcessMessages Process messages until message queue is empty.
Release Destroy the current instance after the current event is terminated.
ThreadAttach Detach from current thread.
ThreadDetach Attach to current thread.

Events

OnBgException When a background exception occurs.
OnChangeState When the component state changes.
OnClientConnect When a new client is connecting.
OnClientCreate When a new client component instance is created.
OnClientDisconnect When a client disconnects.
OnError When an error occurs. Better to use exception handling.
OnMessagePump To call your own external message pump instead of built-in one.

How to



ICS Components Reference