Indicates if the server is running and listening for client connections.
property Active: Boolean;
Active is a Boolean property that indicates the current state of the TIdCustomTCPServer for accepting and servicing client connections.
When it is Active, the server will listen for client connections requests, allocate socket handles and executable tasks for client connections, and respond to execution of client connection tasks in Contexts in the manner prescribed by the TIdCustomTCPServer.
When Active is set to True, a number of actions required to start the TCP server are performed.
The Bindings collection is examined to determine if at least one IP address and port number has been configured for the listener thread in the TCP server. If no items exist in Bindings, a binding is configured that will be used to listen for connection requests using IPv4 addresses. If the protocol stack hosting the Indy library supports IPv6 addresses, an additional binding will be configured that will be used to listen for connection requests using IPv6 addresses.
TIdCustomTCPServer requires that a server IOHandler be assigned for proper operation of the TCP server. If a TIdServerIOHandlerStack instance has not been assigned for the IOHandler property, an instance is created and initialized using the TCP server as the owner of the object instance. In addition, the ImplicitIOHandler property is set to True to indicate that the IOHandler is managed by the TIdCustomTCPServer instance.
TIdCustomTCPServer requires that a Scheduler be assigned to allow creating and managing the executable tasks for client connections to the server. If a TIdScheduler (or descendant class) instance has not been assigned to the Scheduler property, an instance of TIdSchedulerOfThreadDefault is created and assigned to the property. The ImplicitScheduler property is set to True to indicate that the Scheduler is managed by the TIdCustomTCPServer instance. The default Scheduler (TIdSchedulerOfThreadDefault) allows creating and executing Thread-based tasks for client connections to the Server.
Finally, the listener thread(s) used for accepting connection requests for the server instance are initialized and started.
Initializing listener threads requires that each item in Bindings have a valid socket handle allocated, that socket options for the socket handle be set, and that the IP address and port number for the socket descriptor be bound to the socket handle.
If an exception occurs during initialization of any socket handle in Bindings, all socket handles for the server instance are closed and the exception is re-raised. The value in Active will continue to contain False.
On successful initialization of the socket handles for the listener threads, the OnAfterBind event handler is signalled.
Each socket handle in Bindings is then instructed to listen for connection requests using the backlog specified in ListenQueue. A TIdListenerThread instance is created that uses the socket handle in the Binding. The priority for listener thread instances is set to tpHighest to give preference to responding to connection requests over execution of tasks for client connections. The OnBeforeListenerRun event handler in the server is assigned to the OnBeforeRun event handler in each of the listener threads. The listener threads are then added to the internal TIdThreadList for the server, and each listener thread is started.
The value in the Active property is updated as the final step in server startup. At this point, connection requests on listener threads should be handled normally using values specified in Scheduler, ContextClass, Contexts, and OnExecute (in TIdTCPServer).
All configuration options for the server instance (other than the defaults values and actions as described above) should be performed before starting the server (by setting the Active property to True). Changed properties values are often ignored after setting Active to True, while other property value changes may result in Exceptions being raised. Explicit assignments to the following properties should be performed before server startup:
While Active remains set to True, TIdCustomTCPServer uses listener thread(s) to detect and accept client connection requests. When a connection request is detected, the Scheduler in the server instance is used to acquire the thread or fiber that controls execution of the task for the client connection. The IOHandler in the server is used to get an IOHandler for the client connection.
A client connection request can be refused for a number of reasons. The listener thread may get stopped during processing of the request, or the attempt to create a client IOHandler fails because of an invalid socket handle.
The most common error occurs when the number of client connections in Contexts exceeds the number allowed in MaxConnections. In this situation, an message is written to the client connection that indicates the condition and the client connection is disconnected.
If the connection is refused due to any other exception, the OnListenException is triggered.
If no error or exception is detected for the connection request, a TIdContext is created for the client connections executable task. Procedures that trigger the OnConnect, OnDisconnect, and OnExecute event handlers are assigned to the context. The context is then given to the Scheduler for execution using its native thread or fiber support.
At this point, the client connections executable task is fully self-contained and controlled using the OnConnect, OnDisconnect, and OnExecute event handlers. OnConnect and OnDisconnect are optional, and should be used only to perform simple tasks that are not time consuming. Using Synchronized method calls that access the main VCL thread are highly discouraged. Use OnExecute to control the interaction between the client and the server during the lifetime of the client connection.
A Number of actions required to stop the server are performed when the Active property is set to False. These actions include steps needed to stop all listener threads for the server instance, and to terminate all executable tasks for client connections to the server.
Listener threads are terminated and removed from the internal thread list to prevent any additional connection requests from being accepted during the ShutDown process. Each TIdListenerThread instance in the internal TIdThreadList is halted, and the socket handle for the listener thread is closed and invalidated. When the thread has completed execution, it is freed. The internal TIdThreadList for a TIdListenerThread instance is freed.
Any existing executable tasks for client connections found in Contexts are terminated by Disconnecting the Connection for the TIdContext instances, and by terminating all threads or fibers under control of the Scheduler for the server instance. If the Scheduler is managed by the server instance (Implicit Scheduler contains True), it is freed and released.
Changing the value in Active using the IDE (design-time) has no effect other than storing the property value that is used at runtime and during component streaming.
Copyright © 1993-2006, Chad Z. Hower (aka Kudzu) and the Indy Pit Crew. All rights reserved.
Post feedback to the Indy Docs Newsgroup.