Indy 9 | Content | Index | Reference

TIdTCPServer
Hierarchy, Properties, Methods, Events, See Also, Unit: IdTCPServer
Implements a multi-threaded TCP Server.

    TIdTCPServer = class(TIdComponent)

Unit
IdTCPServer
Description
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.

TIdTCPServer.Active
TIdTCPServer
Specifies that the server is running and listening for connections.

    property Active: Boolean;

Description
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.

TIdTCPServer.Bindings
TIdTCPServer, See Also
Container for socket handles allocated by the server.

    property Bindings: TIdSocketHandles;

Description
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.

TIdTCPServer.CommandHandlers
TIdTCPServer, See Also
Container for command handlers used for the server.

    property CommandHandlers: TIdCommandHandlers;

Description
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.

TIdTCPServer.CommandHandlersEnabled
TIdTCPServer, See Also
Indicates if CommandHandlers are used during peer thread execution.

    property CommandHandlersEnabled: boolean;

Description
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.

TIdTCPServer.DefaultPort
TIdTCPServer, See Also
Identifies the default port number for new connections.

    property DefaultPort: integer;

Description
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.

TIdTCPServer.Greeting
TIdTCPServer
Banner message sent after accepting threaded client connections.

    property Greeting: TIdRFCReply;

Description
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.

TIdTCPServer.ImplicitIOHandler
TIdTCPServer, See Also
Indicates if the IO handler was created when the server became active.

    property ImplicitIOHandler: Boolean;

Return Value
Boolean - True when created during activation.
Description
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.

TIdTCPServer.ImplicitThreadMgr
TIdTCPServer, See Also
Indicates if the thread manager was created when the server became active.

    property ImplicitThreadMgr: Boolean;

Return Value
Boolean - True when created during activation.
Description
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.

TIdTCPServer.Intercept
TIdTCPServer, See Also
Identifies the socket data handler.

    property Intercept: TIdServerIntercept;

Description
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.

TIdTCPServer.IOHandler
TIdTCPServer, See Also
Represents the IOHandler used by the listener thread for the server.

    property IOHandler: TIdServerIOHandler;

Description
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.

TIdTCPServer.ListenQueue
TIdTCPServer, See Also
Inicates the mximum number of unresolved connection attempts allowed.

    property ListenQueue: integer;

Description
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.

TIdTCPServer.MaxConnectionReply
TIdTCPServer, See Also
Represents the message used when peer connections exceed their limit.

    property MaxConnectionReply: TIdRFCReply;

Description
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.

TIdTCPServer.MaxConnections
TIdTCPServer, See Also
Indicates the maximum numer of peer connections allowed for the server.

    property MaxConnections: Integer;

Description
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.

TIdTCPServer.ReplyExceptionCode
TIdTCPServer, See Also
Specifies the numeric result code used after an exception.

    property ReplyExceptionCode: Integer;

Description
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.

TIdTCPServer.ReplyTexts
TIdTCPServer, See Also
Represents protocol responses used in the server implementation.

    property ReplyTexts: TIdRFCReplies;

Description
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.

TIdTCPServer.ReplyUnknownCommand
TIdTCPServer, See Also
Represents an RFC response message used for an unkown command.

    property ReplyUnknownCommand: TIdRFCReply;

Description
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.

TIdTCPServer.ReuseSocket
TIdTCPServer, See Also
Indicates reuse of local addresses for listener threads.

    property ReuseSocket: TIdReuseSocket;

Description
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.

TIdTCPServer.TerminateWaitTime
TIdTCPServer, See Also
Specifies the time a server should wait for terminating threads.

    property TerminateWaitTime: Integer;

Description
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.

TIdTCPServer.ThreadClass
TIdTCPServer, See Also
Specified the thread class type for the thread manager.

    property ThreadClass: TIdThreadClass;

Description
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.

TIdTCPServer.ThreadMgr
TIdTCPServer, See Also
Identifies the thread manager used by the server.

    property ThreadMgr: TIdThreadMgr;

Description
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.

TIdTCPServer.Threads
TIdTCPServer, See Also
Container for peer threads connecting to the server.

    property Threads: TThreadList;

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

TIdTCPServer.Create
TIdTCPServer, See Also
Create is the constructor for TIdTCPServer.

    constructor Create(AOwner: TComponent); override;

Parameters
AOwner: TComponent
Owner of the instance.
Description
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

TIdTCPServer.Destroy
TIdTCPServer, See Also
Destructor for the class instance.

    destructor Destroy; override;

Description
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.

TIdTCPServer.Loaded
TIdTCPServer, See Also
Specifies that the component has been completely loaded from the component stream.

    procedure Loaded; override;

Description
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.

TIdTCPServer.OnAfterCommandHandler
TIdTCPServer, See Also
Represents the event handler signalled after CommandHandler usgage.

    property OnAfterCommandHandler: TIdAfterCommandHandlerEvent;

Description
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.

TIdTCPServer.OnBeforeCommandHandler
TIdTCPServer, See Also
Represents the event handler signalled before CommandHandler usgage.

    property OnBeforeCommandHandler: TIdBeforeCommandHandlerEvent;

Description
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.

TIdTCPServer.OnConnect
TIdTCPServer, See Also
Event handler for peer thread connection attempts.

    property OnConnect: TIdServerThreadEvent;

Description
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.

TIdTCPServer.OnDisconnect
TIdTCPServer, See Also
Event handler for peer thread disconnection.

    property OnDisconnect: TIdServerThreadEvent;

Description
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.

TIdTCPServer.OnException
TIdTCPServer, See Also
Event handler for exceptions raised in a peer thread.

    property OnException: TIdServerThreadExceptionEvent;

Description
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.

TIdTCPServer.OnExecute
TIdTCPServer, See Also
Event handler for peer thread execution.

    property OnExecute: TIdServerThreadEvent;

Description
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.

TIdTCPServer.OnListenException
TIdTCPServer, See Also
Event handler for an exception in a listener thread.

    property OnListenException: TIdListenExceptionEvent;

Description
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.

TIdTCPServer.OnNoCommandHandler
TIdTCPServer, See Also
Event handler signalled when a command handler cannot be located.

    property OnNoCommandHandler: TIdNoCommandHandlerEvent;

Description
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.

Created with Doc-O-Matic 2 donated to Project JEDI. Commercial license available from the Doc-O-Matic site.