Implements a multi-threaded TCP Server.

TIdTCPServer = class(TIdComponent)

TIdTCPServer encapsulates a complete, multi-threaded TCP (Transmission Control Protocol) server. TIdTCPServer uses one or more threads to listen for client connections, and in conjunction with a TIdThreadMgr, allocates a separate thread to handle each client connection to the server. A list of active ThreadClass instances are maintained in Threads.

TIdTCPServer provides options that allow configuration of the server listener threads, including:

• DefaultPort

• ListenQueue

• OnListenException

• ReuseSocket

• MaxConnections

• MaxConnectionReply

TIdTCPServer also provides properties and methods to control protocol specific options, including:

• Greeting

• ReplyExceptionCode

• ReplyUnknownCommand

The TIdTCPServer architecture also implements two mechanisms for servicing peer connections. The first method uses event handlers that execute in the context of the threaded peer connection. The server implementation can assign procedures to the event handlers to respond to the following events:

• OnConnect

• OnExecute

• OnDisconnect

• OnException

The other method uses a collection of TIdCommandHandler objects to recognizing valid server commands, and provides methods and properties needed to handle parameters, perform actions, and formulate error and success responses. The properties and method realted to CommandHandler usgae include the following:

• CommandHandlers

• CommandHandlersEnabled

• OnNoCommandHandler

• OnAfterCommandHandler

• OnBeforeCommandHandler

Server implementors can choose between using server-based event handlers and command handlers to provide finer control over the operation of the server and protocol.

TIdTCPServer can be used as a base class to create custom TCP server descendants that support specific protocols. Many of the Indy server components, such as TIdChargenServer, TIdDayTimeServer, TIdDICTServer, TIdEchoServer, TIdFingerServer, TIdGopherServer, TIdHostNameServer, TIdHTTPServer, TIdIRCServer, TIdNNTPServer, TIdQUOTDServer, TIdTelnetServer, and TIdWhoisServer, are descendants of the TIdTCPServer component.

Specifies that the server is running and listening for connections.

property Active: Boolean;

Active is a Boolean property that indicates the current state of the TIdTCPServer.

When Active is True, the server will listen for client connections, allocate threads and socket handles for connections, and respond to thread execution in the manner prescribed by the TIdTCPServer or descendant. When Active is False, connections and socket handles will be closed, peer threads will be terminated and freed, the thread manager will be released, and the listener thread will be terminated and freed.

Active uses the protected write procedure SetActive to implement changes in the value of the property.

Container for socket handles allocated by the server.

property Bindings: TIdSocketHandles;

Bindings is a TIdSocketHandles property and a collection of TIdSocketHandle instances. Bindings provides the DefaultPort number for the TCP server and is used by the TIdListenerThread to gain access to socket handles and low-level access methods provided by the TCP/IP protocol stack.

Container for command handlers used for the server.

property CommandHandlers: TIdCommandHandlers;

CommandHandlers is a TIdCommandHandlers property that is a container for TIdCommandHandler instances that identify commands, replies, and actions for the server. CommandHandlers is used when the thread peer connection is executed to examine and respond to commands from the peer connection. CommandHandlersEnabled must be True to allow use of the CommandHandlers for the server.

Use OnExecute to provide alternate event handling for the execution of peer threads.

Indicates if CommandHandlers are used during peer thread execution.

property CommandHandlersEnabled: boolean;

CommandHandlersEnabled is a Boolean property that indicates if CommandHandlers are used during execution of peer thread connections. When CommandHandlersEnabled is True, CommandHandlers should contain valid TIdCommandHandler instances to allow responding to commands received from the peer connection.

Use OnExecute, when CommandHandlersEnabled is False, to provide alternate event handling for the execution of peer threads.

Identifies the default port number for new connections.

property DefaultPort: integer;

DefaultPort is an Integer property that identifies the port number used to listen for new client connections. The value of DefaultPort is read from and written to Bindings.DefaultPort.

TIdTCPServer uses the DefaultPort number to bind allocated sockets handles when the Active property to set to True.

Banner message sent after accepting threaded client connections.

property Greeting: TIdRFCReply;

Greeting is a TIdRFCReply property that contains the banner message sent to a peer when the threaded client connection has been accepted by the listener thread. Greeting is written to the client just prior to triggering the OnConnect event and starting execution of the TIdPeerThread.

Greeting is initialized in the Create constructor, and freed in Destroy.

Indicates if the IO handler was created when the server became active.

property ImplicitIOHandler: Boolean;

Boolean - True when created during activation.

ImplicitIOHandler is a read-only Boolean property that indicates if the IOHandler for the server was created as as result of the server becoming Active. ImplicitIOHandler will contain True when an object instance is assigned during activation of the listening thread for the server. ImplicitIOHandler will contain False when the server IOHandler has been expressedly assigned by the application.

ImplicitIOHandler is used in the Destroy destructor to determine if the object instance must free the resources allocated in server IOHandler prior to destruction.

Indicates if the thread manager was created when the server became active.

property ImplicitThreadMgr: Boolean;

Boolean - True when created during activation.

ImplicitThreadMgr is a read-only Boolean property that indicates if ThreadMgr was created as as result of the server becoming Active. ImplicitThreadMgr will contain True when an object instance is assigned during creation and activation of the listening thread for the server. ImplicitThreadMgr will contain False when the ThreadMgr has been expressedly assigned by the application.

ImplicitThreadMgr is also used when the serve becomes inactive to determine if the object instance must free the resources allocated in ThreadMgr prior to stopping the server.

Identifies the socket data handler.

property Intercept: TIdServerIntercept;

Intercept is a TIdServerIntercept property that implements support for detecting when data is sent or data is received using a socket connection. Intercept provides an extensible mechanism to manipulate the socket connection or the data sent and received over the connection prior to use by a client.

Intercept allows a developer to create TIdIntercept descendants to encrypt and decrypt data or to compress and decompress messages. One common use of TIdIntercept is to provide support for the Secure Socket Layer (SSL) protocol, using a TIdServerInterceptOpenSSL instance, in TIdTCPServer and descendants.

Intercept is used by TIdListenerThread to insure that the peer TIdTCPServerConnection receives an appropriate socket handle binding from Intercept.Accept. The peer connection should receive a TIdConnectionIntercept descendant appropriate to the TIdServerIntercept that accepts the connection, or the socket connection will not be able to communicate properly.

Represents the IOHandler used by the listener thread for the server.

property IOHandler: TIdServerIOHandler;

IOHandler is a TIdServerIOHandler property that represents the input / output handler used by listener threads that accept client connections for the server. IOHandler will get an instance of TIdServerIOHandlerSocket assigned to the property when the server becomes Active, if another class instance has not already been assigned. Applications can assign another TIdServerIOHandler descendant to the property prior to setting Active to True.

TIdListenerThread uses the IOHandler for the server when the listener thread is executed.

Inicates the mximum number of unresolved connection attempts allowed.

property ListenQueue: integer;

ListenQueue is an Integer property that indicates the maximum number of unresolved connection attempts allowed for listener threads before exception is raised. ListenQueue is used as an argument when socket descriptors for ListenerThreads are during created during server activation.

Use OnListenException to provide an event handler for notifications of exceptions raised when ListenQueue is exceeded.

The default value for ListenQueue is IdListenQueueDefault as assigned in the Create constructor.

Represents the message used when peer connections exceed their limit.

property MaxConnectionReply: TIdRFCReply;

MaxConnectionReply is a TIdRFCReply property that represents the RFC message response to use when the number of peer connections to the server exceeds MaxConnections. MaxConnectionReply is used when a TIdListenerThread cannot accept a new connection due to the condition. The generated reply from MaxConnectionReply is written to the peer connection, and the peer is Disconnected.

Use MaxConnections to establish the connection limit for the server implementation.

Indicates the maximum numer of peer connections allowed for the server.

property MaxConnections: Integer;

MaxConnections is an Integer property that indicates the maximum number of simultaneous peer connections allowed for the server implementation. MaxConnections can be used to insure that a pre-determined memory or bandwidth threshold is not exceeded. When MaxConnection is 0 (zero), the server does not impose a limit on the maximum number of client connections.

MaxConnections is used when a TIdListenerThread for the server detects a new connection request. If the MaxConnections limit has been exceeed, the MaxConnectionReply message is written to the peer connection and the socket is Disconnected.

Specifies the numeric result code used after an exception.

property ReplyExceptionCode: Integer;

ReplyExceptionCode is an Integer property that specifies the numeric result code used when an exception is raised in the server context during dispatch and execution of a command handler in IdCommandHandler.Check. An exception may also use the ReplyExceptionCode in a command handler, if the exception occurs during execution of the associated TIdCommand.

ReplyExceptionCode and the text from the exception message are written to the client connection when the exception is trapped.

Represents protocol responses used in the server implementation.

property ReplyTexts: TIdRFCReplies;

ReplyTexts is a TIdRFCReplies property that represents the RFC-compliant protocol responses used in the implementation of TIdTCPServer and descendant proptocol servers. ReplyTexts is used extensively in TIdNNTPServer.

ReplyTexts is initializecd in Create, and freed in Destroy. ReplyTexts is used to generate the TIdTCPServer.Greeting message senst when a threaded client is connected to the server. ReplyTexts is also used in TIdCommand.SendReply to update the TIdCommand.Reply descriptive text written in response to a TIdCommandHandler used in the server implementation.

Represents an RFC response message used for an unkown command.

property ReplyUnknownCommand: TIdRFCReply;

ReplyUnknownCommand is a TIdRFCReply property that represents the RFC response to use when an unknown command is received from a client connection. The OnNoCommandHandler event handler, when assigned, takes precendence over use of ReplyUnknownCommand.

Indicates reuse of local addresses for listener threads.

property ReuseSocket: TIdReuseSocket;

ReuseSocket is a TIdReuseSocket property that indicates if socket IP addresses and port numbers can be reused for TIdListenerThread instances used by the server. ReuseSocket is used as an option for SetSockOpt when allocating the listener thread(s) after the server becomes Active.

The default value for ReuseSocket is rsOSDependent, as assigned in the Create constructor.

Specifies the time a server should wait for terminating threads.

property TerminateWaitTime: Integer;

TerminateWaitTime is an Integer property that identifies the total number of milliseconds that the server should wait, in TerminateAllThreads, for all threads to complete termination. TerminateWaitTime is an aggregate delay time, and allows TerminateAllThreads to monitor the Threads list every 250ms until TerminateWaitTime has elapsed.

The default value for TerminateWaitTime is 5000 (5 seconds). Use a larger value for TerminateWaitTime when the server handles a large number of peer connection threads, or when OnDisconnected event handling for the peer connection involves time intensive operations.

Specified the thread class type for the thread manager.

property ThreadClass: TIdThreadClass;

ThreadClass is a TIdThreadClass property used to identify the class type used by ThreadMgr when creating new peer threads for the TCP server. The default ThreadClass for TIdTCPServer is TIdPeerThread as asssigned in the Create constructor.

Identifies the thread manager used by the server.

property ThreadMgr: TIdThreadMgr;

ThreadMgr is a TIdThreadMgr property that provides an extensible mechanism for thread management.

ThreadMgr can accept an explicit reference to one of the TIdThreadMgr descendants, such as TIdThreadMgrDefault or TIdThreadMgrPooled. ThreadMgr will be implicitly created, using a TIdThreadMgrDefault instance, if no other thread manager is assigned when Active is set to True.

ThreadMgr is used by TIdListenerThread.Run get the TIdPeerThread that will act as the thread of execution for new client connections. ThreadMgr uses ThreadClass to determine the class instance returned to the listener thread.

ThreadMgr is used by TIdPeerThread.AfterRun to perform the TIdThreadMgr.ReleaseThread method.

Container for peer threads connecting to the server.

property Threads: TThreadList;

Threads is a read-only TThreadList property that acts as a container for TIdPeerThread items created in the listener thread.

Create is the constructor for TIdTCPServer.

constructor Create(AOwner: TComponent); override;

Owner of the instance.

Create relies on the inherited Create method, and allocates object instances used in the folowing properties:

• Greeting

• MaxConnectionReply

• Threads

• ThreadClass (TIdPeerThread)

• ReplyUnknownCommand

Create also sets the default values for the following properties:

• CommandHandlersEnabled - IdCommandHandlersEnabledDefault

• TerminateWaitTime - 5000

• ListenQueue - IdListenQueueDefault

Destructor for the class instance.

destructor Destroy; override;

Destroy is the destructor for the TIdTCPServer instance, and sets Active to False. Destroy frees any Bindings allocated for listener threads or peer connections. Destroy frees other resources allocated in the Create constructor prior to calling the inherited Destroy method.

Specifies that the component has been completely loaded from the component stream.

procedure Loaded; override;

Loaded allows the TIdTCPServer to initialize itself after all its parts have been loaded using Delphi component streaming conventions, including a call to the inherited Loaded method.

Loaded intercepts any change to the Active property until all other properties and sibling components have been read from the component stream.

If the TIdTCPServer should be active, Loaded then sets the Active property to True to force initialization of Bingings and ThreadMgr properties, as well as the TIdTListenerThread used by TIdTCPServer.

Represents the event handler signalled after CommandHandler usgage.

property OnAfterCommandHandler: TIdAfterCommandHandlerEvent;

OnAfterCommandHandler is a TIdAfterCommandHandlerEvent property that represents the event handler signalled after CommandHandlers have been used to service an executing peer thread connection. Note: OnAfterCommandHandler does not indicate that a TIdCommandHandler was located for a command from the client.

Use OnNoCommandHandler to respond to event notifications when a command handler cannot be located for a client command.

Represents the event handler signalled before CommandHandler usgage.

property OnBeforeCommandHandler: TIdBeforeCommandHandlerEvent;

OnBeforeCommandHandler is a TIdBeforeCommandHandlerEvent property that represents the event handler signalled before CommandHandlers is used to service an executing peer thread connection. Note: OnBeforeCommandHandler does not indicate that a TIdCommandHandler will located for a command from the client.

Use OnNoCommandHandler to respond to event notifications when a command handler cannot be located for a client command. Use OnAfterCommandHandler to respond to event notifications after command handler useage has been completed.

Event handler for peer thread connection attempts.

property OnConnect: TIdServerThreadEvent;

OnConnect is an event handler for TIdServerThreadEvents. OnConnect occurs when a TIdPeerThread attempts to connect to a TIdTCPServer.

OnConnect receives AThread as a parameter, representing the TIdPeerThread thread that is requesting the connection.

Assign a TIdServerThreadEvent event handler procedure to OnConnect.

Event handler for peer thread disconnection.

property OnDisconnect: TIdServerThreadEvent;

OnDisconnect is an event handler for a TIdServerThreadEvent event, and occurs when the TIdPeerThread attempts to disconnect from a TCP server. OnDisconnect receives the parameter AThread, and represents the TIdPeerThread thread requesting to be disconnected. OnDisconnect is triggered when Athread has finished execution, and just prior to the TIdPeerThread being released by the thread manager specified in ThreadMgr.

Note: Do not call Synchronized method in the OnDisconnect event handler. Only inherited Notification calls are safe for use in OnDisconnect. This is important because OnDisconnect is called for active client threads when the server sets Active to False. Using synchronized methods in OnDisconnect can result in a deadlock condition, caused when the thread is suspended while the method is executing in the main VCL thread.

TIdTCPServer will detect the deadlock condition, but a timeout error will be raised while trying to terminate the active threads. Use Thread.Notification to act on the notification that a component is being inserted or removed. For example, if a component has object fields or properties that contain references to other components, it can check the notifications of component removals and invalidate those references as needed.

Assign a TIdServerThreadEvent event handler procedure to OnDisconnect to allow responding to the event notification.

Event handler for exceptions raised in a peer thread.

property OnException: TIdServerThreadExceptionEvent;

OnException is a TIdServerThreadExceptionEvent property that represents the vent handler signalled when an Exception is raised during execition of a peer thread. OnException is called from TIdPeerThread using the Server context for the thread.

Applications must assign a procedure to the event handler to allow a response to the event notification.

Event handler for peer thread execution.

property OnExecute: TIdServerThreadEvent;

OnExecute is an event handler for TIdServerThreadEvents. OnExecute occurs when a TIdPeerThread attempts to perform the TIdPeerThread.Run method. OnExecute receives AThread as a parameter, representing the TIdPeerThread thread that will be started.

Assign a TIdServerThreadEvent event handler procedure to OnExecute to respond to the event notification.

Use CommandHandlers and CommandHandlersEnabled to provide finer control over commands executed for a peer thread connection.

Event handler for an exception in a listener thread.

property OnListenException: TIdListenExceptionEvent;

OnListenException is a TIdListenExceptionEvent property that represents the event handler signalled when an exception is raised during execution of a TIdListenerThread. OnListenException is accessed using the server context in the listener thread.

Applications must assign a procedure to the event handler to allow a response to the event notification.

Event handler signalled when a command handler cannot be located.

property OnNoCommandHandler: TIdNoCommandHandlerEvent;

OnNoCommandHandler is a TIdNoCommandHandlerEvent property that represents the event handler signalled when a TIdCommandHandler cannot be located for an executing peer thread connection. OnNoCommandHandler will not be triggered when CommandHandlersEnabled is False.

Applications must assign a procedure to the event handler to allow a response to the event notification.