Implements a collection item representing command handlers for a server implementation.

TIdCommandHandler = class(TCollectionItem)

TIdCommandHandler is a TCollectionItem descendant that implements a mechanism for recognizing valid commands for a Server, and provides methods and properties needed handle parameters, perform actions, and formulate error and success responses.

TIdCommandHandler implements an OnCommand event handler that receives a TIdCommandEvent event type representing the unique command to be executed. TIdCommandHandler implements the virtual Check method that handles creation of TIdCommand object instances, signalling of event notifications for the associated command object, as well as preparation of reply and response values for the associated threaded peer connection.

TIdCommandHandler is an optional feature for use with TIdTCPServer and descendant classes. TIdCommandHandler can be used when TIdTCPServer.CommandHandlersEnabled indicates that command handlers are desired, and the server has valid TIdCommandHandler instances assigned in the CommandHandlers collection. Under any other circumstance, TIdTCPServer reverts to the default behavior implemented using the TIdTCPServer.OnExecute event handler.

Identifies the delimiter character between the Command and parameter values.

property CmdDelimiter: Char;

CmdDelimiter is a Char property that identifies the delimiter character used to separate Command from any parameter values in data received from a peer connection. CmdDelimiter is used in Check when parameter values are detected in the received data. If CmdDelimiter contains any value other than CHAR0 (Decimal 0), both Command and CmdDelimiter are extracted from the received data. Any remaining data is used as parameter values for the associated TIdCommand object instance.

The default value for CmdDelimiter is ' ' (Decimal 32), as assigned in Create.

Text that causes the command handler to be invoked.

property Command: string;

Command is a String property that represents the text received from a peer connection that will result in the command handler being performed using optional parameter values. Command is examined in Check to determine if the command handler can be used with data received from a peer thread connection. Use OnCommand to implement the functionality needed in response to Command.

Storage slot for TObject data used by the command handler.

property Data: TObject;

Data is a TObject property that can be used as a storage slot for data used by the command handler, and can contain a reference to any TObject descendant. Data cn accessed by a command action handler or event handlers triggered through execution of the item in TIdCommandCommandHandlers.

Note: It is the responsibility of the application to cast Data to the class instance required, or an exception will be raised.

Data is not initialized in the Create constructor, nor is it released in the Destroy destructor. The application must assume all responsibility for maintaining Data when assigned.

Closes the connection to the peer after handling a command.

property Disconnect: boolean;

Disconnect is a Boolean property that indicates if the command handler should close the connection to the peer after the Enabled command handler is invoked. Disconnect is used in Check, after an associated TIdCommand object instance has been created, prepared, and signalled to the OnCommand event handler. When Disconnect is True, the peer thread connection is closed prior to exiting from the Check.

Indicates if the command handler can respond to the associated Command.

property Enabled: boolean;

Enabled is a Boolean property that indicates if the command handler instance can be used to execute the associated Command received from a peer connection. When Enabled is False, the command handler cannot be invoked by a thread of execution for the peer connection.

The default value for Enabled is IdEnabledDefault, as assigned in the Create constructor.

Identity for the item in the owner collection.

property Name: string;

Name is a String property that represents the identity for the collection item in a TIdCommandHandlers collection, and is also used as the DisplayName when the collection item is viewd in the Object Inspector. The default value for Name is assigned in the Create constructor, and contains the concatenated values of ClassName and the string representation of the inherited ID property.

Identifies the delimiter character between parameters.

property ParamDelimiter: Char;

ParamDelimiter is a Char property that identifies the delimiter character expected between parameter appearing in Command. ParamDelimiter is used in Check to separated values in Command into individual parameter values for a TIdCommand instance representing the command. ParamDelimiter is used when ParseParams is True. Otherwise, parameter parsing is not performed.

The default value for ParamDelimiter is the SPACE character (Decimal 32) as assigned in Create.

Indicates if parameter values are separated into individual line in Params.

property ParseParams: Boolean;

ParseParams is a Boolean property that indicates if the command handler should parse any parameters that occur after the command sent to the Check method. When ParseParams is True, values occurring after the command and optional CmdDelimiter are added to the Params property in the command object as individual lines when the ParamDelimiter character is encountered.

The default value for ParseParams is IdParseParamsDefault.

Represents the numeric code returned when an exception occurs in the command handler.

property ReplyExceptionCode: Integer;

ReplyExceptionCode is an Integer property that represents the Numeric result code used when an exception occurs after signalling the associated command object in Check. When an exception is raised, ReplyExceptionCode is used with the message text from the exception as the new value for Reply. The peer thread connection in the associated command object is used to send the reply using SendReply when PeformReply indicates that a reply is needed.

Note: An exception that occurs in Check can result in the OnException event handler for the server context being executed. Check examines the ReplyExceptionCode on the server to insure that either condition is detected.

Represents the reply indicating successful completion of the command handler.

property ReplyNormal: TIdRFCReply;

ReplyNormal is a TIdRFCReply property that contains the NumericCode and Text for the reply indicating successful completion of the command handler. ReplyNormal is used as the initial value for the reply in an associated TIdCommand object instance in the command handler.

ReplyNormal is used in the Check method prior to invoking execution of the command object of the command handler.

Contains string values used as the response for the command handler.

property Response: TStrings;

Response is a TStrings property that contains string values to be written in an RFC-complaint format as the response for the command. Response is used in Check when the associated TIdCommand.Response does not contain any values. Note: Check also examines the TIdCommand.Reply property to generate any values from the command object.

Response is sent to the peer connection in the current thread of execution using the TIdTCPConnection.WriteRFCStrings method.

Stores an Integer value.

property Tag: integer;

Tag is an Integer property that has no predefined meaning. The Tag property is provided for the convenience of developers. It can be used for storing an additional integer value, or it can be typecast to any value such as a component reference or a pointer.

TIdNNTPServer uses the Tag property to identify the index position of the NNTPCommand assigned to the TIdCommandHandler.

Handles dispatching and execution of the command for the command handler.

function Check(const AData: string; AThread: TIdPeerThread): boolean; virtual;

Data received from the peer connection.

Thread of execution for the peer connection.

Boolean - True

Check is a Boolean function that is used to create, prepare, and dispatch a TIdCommand object instance used in association with the command handler. Check examines AData for optional CmdDelimiter and parameter values.

Check creates a TIdCommand object instance used to represent the command handled by the command handler, and sets property values including the CommandHandler that created the object and the peer thread used for data and response messages.

Check parses parameter values into the TIdCOmmand object when ParseParams is True.

Check assigns the values in ReplyNormal as the default reply for the TIdCommand associated with the command handler.

Check signals the OnCommand event handler to allow execution of actions for the command.

If an exception occurs, Check updates the Reply from the command object to contain the value in ReplyExceptionCode and exception message text. Exception messages are then written to the peer thread connection.

When the command object completes execution, values in Reply and Response are sent to the peer thread connection. If Disconnect is True, the peer thread connection is closed prior to exiting from the method.

Constructor for the object instance.

constructor Create(ACollection: TCollection); override;

Collection that owns the command handler.

Create is the constructor for the object instance, and calls the inherited Create method to initialize property values. Create initializes the object instances used in the ReplyNormal and Response properties, and sets the following properties to their default values:

• CmdDelimiter - ' ' (Decimal 32)

• Enabled - IdEnabledDefault

• Name - Concatenated value of ClassName and ID

• ParamDelimiter - ' ' (Decimal 32)

• ParseParams - IdParseParamsDefault

Frees the object instance.

destructor Destroy; override;

Destroy is the Destructor for the object instance. Destroy is responsible for free resources allocated in the Create constructor prior to calling the inherited Destroy method.

Determines the text used to represent the collection item in the Object Inspector.

function GetNamePath: string; override;

GetNamePath is an overriden String function that determines the text used to represent the collection item in the Object Inspector. TIdCommandHandler returns the name of the owner of the collection, acessed using TIdCommandHandlers.OwnedBy, followed by a '.' character and the DisplayName for the collection item. When the collection owner is unassigned, GetNamePath calls the inherited method. GetNamePath is intended for internal use only.

Checks that a command handler has the specified name.

function NameIs(ACommand: string): Boolean;

Name to be compared to the property value.

Boolean - True when the command handler has the specified name.

NameIs is a Boolean function that allows comparison of the Name property to the value specified in ACommand. NameIs can be used to insure that a TIdCommandHandler contains the name desired before triggering a procedure used as an action handler.

Event handler that performs an action associated with a command handler.

property OnCommand: TIdCommandEvent;

OnCommand is a TIdCommandEvent property that represents the event handler signalled when the associated TIdCommand object instance is executed for the Command Handler. Applications must a procedure to the event handler that implements the functionality to be performed when the event handler is signalled for execution.