Indy 9 | Content | Index | Reference

TIdFTPServer
Hierarchy, Properties, Methods, Events, See Also, Unit: IdFTPServer
Implements a File Transfer Protocol (FTP) server.

    TIdFTPServer = class(TIdTCPServer)

Unit
IdFTPServer
Description
TIdFTPServer is a TIdTCPServer descendant that implements a multi-threaded File Transfer Protocol (FTP) server as described in the Internet Standards document:

- RFC 959 - File Transfer Protocol [FTP] (http://www.rfc-editor.org/rfc/rfc959.txt)

FTP is a basic file-sharing system for uploading and downloading files, as well as managing files and directories. The FTP protocol is commonly used for software distribution, uploading files to a web-server, and providing archives for various purposes.

TIdFTPServer implements properties that can be used to configure and control FTP server options, including:

- Permit anonymous login accounts.

- Specify the computer system to emulate in file and directory handling.

- Configure the reply used for the FTP HELP command.

- Specify the Home directory to use for use for client connections.

TIdFTPServer provides a default implementation that uses TIdCommandHandler instances and TIdCommand reply event handlers to perform file and directory handling functions. The server can also be implemented using the OnExecute event handler to respond to multi-threaded client connections when the CommandHandlersEnabled property is False.

TIdFTPServer provides a collection and event handlers to allow access to TIdUserAccount instances for Authentication of client accounts. There are also event handler that allow handling the FTP USER and PASS commands when User Accounts are maintained external to the FTP server implementation.

TIdFTPServer.AllowAnonymousLogin
TIdFTPServer
Indicates if "Anonymous" accounts are supported in the FTP server.

    property AllowAnonymousLogin: Boolean;

Description
AllowAnonymousLogin is a Boolean property that indicates if the FTP server implementation allows client connections using accounts names found in AnonymousAccounts. AllowAnonymousLogin is used in the command reply handler for the FTP USER command, and updates properties in the client connection thread to indicate the UserType for the account.

When AllowAnonymousLogin is False, accounts names and passwords will be authenticated using UserAccounts, or the OnUserLogin event handler when UsetrAccounts are not assigned.

The default value for AllowAnonymousLogin if False, as assigned in the Create constructor.

TIdFTPServer.AnonymousAccounts
TIdFTPServer
Contains account names considered to be "anonymous" accounts on the FTP server.

    property AnonymousAccounts: TStringList;

Description
AnonymousAccounts is a TStringList property that contains the account names considered to be "anonymous" or "guest" accounts for the FTP server implementation. If AllowAnonymousLogin is True, anonymous accounts are permitted in the FTP server implementation.

AnonymousAccounts is initialized in the Create constructor, and contains the default values 'anonymous' and 'guest'. Note: By default, AllowAnonymousLogin is set to False in Create.

AnonymousAccounts is freed and released in the Destroy destructor.

AnonymousAccounts is used in the FTP USER command action handler, when the server handles the user name for the account provided in the TIdCommand instance triggering the command action handler. The USER command action handler compares the value found in the TIdFTPServerThread.UnparsedParams against AnonymousAccounts, and sets the UserType and Username for the associated Thread in ASender when the user account is found.

Note: AnonymousAccounts is not used to authenicate anonymous logins in the FTP server implementation when UserAccounts has not been assigned. In this situation, OnUserLogin is signalled to perfrom username and password authentication.

TIdFTPServer.AnonymousPassStrictCheck
TIdFTPServer
Indicates that passwords for anonymous accounts must contain a valid email address.

    property AnonymousPassStrictCheck: Boolean;

Description
AnonymousPassStrictCheck is a Boolean property that indicates if passwords for anonymous user accounts require validation to insure that the password contains a valid email address. AnonymousPassStrictCheck is used in the FTP PASS command event handler when the client connection thread contains the value utAnonymousUser in TIdFTPServerThread.UserType.

When AnonymousPassStrictCheck check is True, and the password for the client connection is not blank, the password is checked to insure that the value contains an RFC-compliant email address. When the password is valid, the authentication status in TIdFTPServerThread.Authenticated is set to True.

When the password is blank for the anonymous account, UserType and Authenticated properties in the threaded client connection are reverted to their unauthenticated values.

The default value for AnonymousPassStrictCheck is True, as assigned in the Create constructor.

TIdFTPServer.DefaultDataPort
TIdFTPServer, See Also
Represents the data channel port number for threaded client connections.

    property DefaultDataPort: Integer;

Description
DefaultDataPort is an Integer property that represents the port number to use when initializing the data channel for threaded client connections to the FTP server. The default value for DefaultDataPort is IdPORT_FTP_DATA as assigned in the constructor for the object instance.

DefaultDataPort is used frequently in TIdFTPServer. DefaultDataPort is the value provided as a parameter when creating the TIdFTPServerThread instances for threaded client connections to the FTP server. In turn, DefaultDataPort is also used when the TIdFTPServerThread needs to create a TIdDataChannelThread or intitialize the data channel for the threaded client connection.

TIdFTPServer.EmulateSystem
TIdFTPServer
Indicates the computer system to emulate in file and directory handling operations.

    property EmulateSystem: TIdFTPSystems;

Description
EmulateSystem is a TIdFTPSystems property that indicates the computer system to emulate in file and directory handling operations for the FTP server implementation. EmulateSystem is also used when the FTP server generates responses for the LIST, SITE, and SYST FTP commands.

The default value for EmulateSystem is ftpsDOS, as assigned in the Create constructor.

TIdFTPServer.HelpReply
TIdFTPServer
Specifies text values sent in a response to the FTP HELP command.

    property HelpReply: Tstrings;

Description
HelpReply is a TStrings property that contains the textual value sent to an FTP client connection in response to the FTP HELP command. HelpReply is used as the values for the normal reply in the TIdCommandHandler for the FTP HELP command.

HelpReply contents are sent in responses using the Control channel for the client connection.

Applications should assign lines of text to the property that indicate the FTP commands supported in the server implementation, or to provide site-specific implementation status information.

TIdFTPServer.SystemType
TIdFTPServer
Indicates the host operating system and platform for the server implementation.

    property SystemType: string;

Description
SystemType is a String property that indicates the host operating system and platform for the FTP server implementation. SystemType is used when the command event handler for the FTP SYST command verb is executed.

SystemType is updated when the value in the EmulateSystem property is changed, and SystemType contains a standard value. SystemType will contain one of the following for the associated EmulateSystem value:

- ftpsDOS - 'Windows 9x/NT'.

- ftpsUNIX - 'UNIX type: L8'.

- ftpsVAX - 'UNIX type: L8'.

The default value for SystemType is 'Windows 9x/NT', as assigned in the Create constructor.

TIdFTPServer.UserAccounts
TIdFTPServer, See Also
Implements a container for user accounts managed by the FTP server.

    property UserAccounts: TIdUserManager;

Description
UserAccounts is a TIdUserAccounts property that represents the container used for managing TIdUserAccount instances for valid accounts on the FTP server. By default, UserAccounts are not used in the FTP server implementation. Use OnUserLogin to determine when the account has been Authenticated for access to the FTP server.

An application can create a TIdUserAccounts class instance for the property to enable use of UserAccounts and its AuthenticateUser, Accounts, and OnAuthentication properties and methods. The application must also free the resources allocated to UserAccount prior to destruction of the object instance.

UserAccounts is used by the command reply handlers for the FTP USER and PASS commands to perform authorization using the user name and password values from the corresponding CommandHandlers. UserAccounts should use its OnAuthenticate event handler to insure that valid accounts are added to the collection maintained by the component. A user account is accessed using the ItemsByUserName property, and provides values that indicate the user name, real name, password, and user-defined attributes associated with the account used by the threaded client connection.

TIdFTPServer.Create
TIdFTPServer, See Also
Constructor for the object instance.

    constructor Create(AOwner: TComponent); override;

Parameters
AOwner: TComponent
Owner of the object instance.
Description
Create is the constructor for the object instance, and calls the inherited Create method using the component specified in AOwner as the owner of the object instance.

Create assigns TIdFTPServerThread to the ThreadClass property used for creating new threaded client connections.

Create sets the default values for properties in the FTP server implementation, including:

- AllowAnonymousLogin - False.

- AnonymousPassStrictCheck - True.

- DefaultPort - IDPORT_FTP.

- EmulateSystem - ftpsDOS.

- Greeting - Numeric Code 220 with the text "Indy FTP Server ready".

- ReplyUnknownCommand - Numeric Code 500 with the constant text RSFTPCmdSyntaxError.

- SystemType - 'Windows 9x/NT.'

Create also allocates resources required for properties in the object instance, including the following:

- AnonymousAccounts - Anonymous account name; default values include 'anonymous' and 'guest'.

- HelpReply - Text used in response tot he FTP HELP command verb.

- UserAccounts - Nil; indicates user accounts are not maintained by the FTP server implementation.

When the FTP Server component is not being used in the IDE, Create will populate CommandHandlers with the TIdCommandHandler instances and command reply event handlers used to implement the FTP commands.

TIdFTPServer.Destroy
TIdFTPServer, See Also
Frees the object instance.

    destructor Destroy; override;

Description
Destroy is the destructor for the object instance. Destroy frees and releases resources allocated in the Create constructor, like AnonymousAccounts and HelpReply. Destroy calls the inherited Destroy method prior to exiting.

TIdFTPServer.OnAfterUserLogin
TIdFTPServer
Event handler signalled after authentication of a user account.

    property OnAfterUserLogin: TOnAfterUserLoginEvent;

Parameters
Sender
Command handler generating the event notification.
Description
OnAfterUserLogin is a TOnAfterUserLogin property that represents the event handler signalled when a user account has been successfully authenticated using UserAccounts in the FTP server implementation. OnAfterUserLogin is signalled from the command replay handler for the FTP PASS command when the user name and password have been read and Authenticated for a threaded client connection using values from UserAccounts.

OnAfterUserLogin canbe used to perform server logging, set default values or file system path based on the user account, or to perform additional processing required to maintain state for the client connection. Note: Applications must assign a procedure to the event handler to allow responding to the event notification.

TIdFTPServer.OnChangeDirectory
TIdFTPServer
Allows the server to select a file system path.

    property OnChangeDirectory: TOnDirectoryEvent;

Parameters
ADirectory
File system path to be used for the directory-related command.
ASender
Client connection for the event.
Description
OnChangeDirectory is a TOnDirectoryEvent property that represents the event handler signalled when the FTP server performs the FTP CWD or CDUP command verbs. OnChangeDirectory allows the server to perform platform-specific API calls needed to change the currently selected file system path to the desired location specified in ADirectory.

ASender is the threaded client connection for the event notification. ADirectory is the file system path to be selected after execution of the command event handler. ADirectory will contain the directory path after resolving the directory path using the file handling required for the system in EmulateSystem. When triggered for the FTP CDUP command, ADirectory contains the notation required to change to the parent directory in the local file system.

An FTP server implementation must assign a procedure to the event handler to allow responding to the event notifications. The TIdFTPServerThread.CurrentDir property will be updated to the value used by the event handler.

TIdFTPServer.OnDeleteFile
TIdFTPServer
Allows the server to remove a file from the server file system.

    property OnDeleteFile: TOnFileEvent;

Parameters
AFilename
File to be removed from the local file system.
ASender
Client connection for the event notification.
Description
OnDeleteFile is a TOnFileEvent property that represents the event handler signalled when the FTP server needs to remove a file located on the server file system. OnDeleteFile is used in the FTP DELE command event handler, and allows the server to perform the platform-specific API calls needed to delete the file specified in AFilename.
Notes
Applications must assign a procedure to the event handler to allow responding to the event notification. When an event handler has not been assigned, the message specified in RSFTPFileActionNotTakenand with a numeric result code of 550 is sent to the client connection.

TIdFTPServer.OnGetCustomListFormat
TIdFTPServer

    property OnGetCustomListFormat: TIdOnGetCustomListFormat;

Parameters
AItem
Directory listing item to be examined.
ASender
FTP server generating the event notification.
VText
Textual representation for the directory listing item.
Description
OnGetCustomListFormat is a TIdOnGetCustomListFormat property that represents the event handler signalled when an FTP server implementation needs to use a custom directory listing format. OnGetCustomListFormat is used in ListDirectory when event handlers have been assigned for OnListDirectory and EmulateSystem contains the value ftpsOther.

The event handler for OnGetCustomListFormat is also assigned to the TIdFTPListItems.OnGetCustomListFormat event handler and TIdFTPListItems.ListFormat is given the value flfCustom.

Applications must assign a procedure to the event handler to allow responding to the event notification. The procedure must examine the properties and/or raw data in AItem to generate the textual representation of the directory listing item in VText.

TIdFTPServer.OnGetFileSize
TIdFTPServer
Allows the server to retrieve the size for a file in the server file system.

    property OnGetFileSize: TOnGetFileSizeEvent;

Parameters
AFilename
File name requested.
AFileSize
Size of the requested file.
ASender
Client connection for the event notification.
Description
OnGetFileSize is a TOnGetFileSizeEvent property that represents the event handler signalled when the FTP server needs to determine the size of a file on the server file system. OnGetFileSize allows the FTP server implementation to perform the platform-specific API calls needed to retrieve the size of the file specified in AFilename.

OnGetFileSize is used when the command event handler is executed after receiving the FTP SIZE command verb from the client connection in ASender. AFileSize will contain the number of bytes in the file specified by AFilename, or -1 when the file size cannot be determined.

TIdFTPServer.OnListDirectory
TIdFTPServer
Allows the server to generate a formatted directory listing.

    property OnListDirectory: TOnListDirectoryEvent;

Parameters
ADirectoryListing
Collection of file items for the listing.
APath
File system directory for the listing.
ASender
Client connection for the event notification.
Description
OnListDirectory is a TOnListDirectoryEvent property that represents the event handler signalled when an FTP server implementation needs to prepare and process a directory listing for the client connection. OnListDirectory is triggered when the command event handler for the FTP LIST command verb is executed.

OnListDirectoryEvent allows the server to examine, validate, or maintain items that appear in the directory listing using the TIdFTPListItems.ListFormat as indicated by EmulateSystem.

OnListDirectoryEvent allows the server to use properties from the connection for the client thread specified in ASender, the current directory in APath, and the collection with file information in ADirectoryListing. The event handler can also add or delete TIdFTPListItem entries in ADirectoryListing. Use the platform-specific API calls needed to retrieve the list of files for the specified directory, and populate the contents of ADirectoryListing.

An FTP server implementation must assign a procedure to the event handler for the TOnListDirectoryEvent event to allow responding to the event notification. When a procedure has not been assigned to the event handler, an EIdTFTPException will be raised.

TIdFTPServer.OnMakeDirectory
TIdFTPServer
Allows the server to remove a directory from the server file system.

    property OnMakeDirectory: TOnDirectoryEvent;

Parameters
ADirectory
File system path to be used for the directory-related command.
ASender
Client connection generating the event.
Description
OnMakeDirectory is a TOnDirectoryEvent property that represents the event handler signalled when an FTP server needs to create a new directory in the server file system. OnMakeDirectory is triggered when the command event handler for the FTP MKD command verb is executed.

OnMakeDirectory allows the FTP server to perform the platform-specific API calls needed to create the resolved directory path in ADirectory on the server file system.

An FTP server implementation must assign a procedure to the event handler to allow responding to the event notification.

Use OnRemoveDirectory to implement removal of a directory on the server file system.

TIdFTPServer.OnRemoveDirectory
TIdFTPServer
Allows the server to remove a directory in the server file system.

    property OnRemoveDirectory: TOnDirectoryEvent;

Parameters
ADirectory
File system path to be used for the directory-related command.
ASender
Client connection generating the event.
Description
OnRemoveDirectory is a TOnDirectoryEvent property that represents the event handler signalled when an FTP server needs to remove a directory from the server file system. OnRemoveDirectory is triggered in the command event handler for the FTP RMD command verb.

OnRemoveDirectory allows the server to perform the platform-specific API calls need to removed the resolved file directory path specified in ADirectory.

An FTP server implementation must assign a procedure to the event handler to allow responding to the event notification.

TIdFTPServer.OnRenameFile
TIdFTPServer
Allows the server to rename a file in the server file system.

    property OnRenameFile: TOnRenameFileEvent;

Parameters
ARenameFromFile
Orignal filename.
ARenameToFile
New file name.
ASender
Threaded client connection for the event notification.
Description
OnRenameFile is a TOnRenameFileEvent property that represents the event handler signalled when the FTP server needs to rename a file on the server file system.

OnRenameFile is examined in the command event handler for the FTP RNFR command verb, and indicates that file renaming can be performed for the FTP server implementation. OnRenameFile is triggered when the command event handler for the FTP RNTO command verb is executed.

OnRenameFile allows the server to peform the platform-specific API calls need to rename the file. ARenameFromFile indicates the orginal file name in the server file system. ARenameToFile indicates the new file name in the server file system.

An FTP server implementation must assign a procedure to the event handler to allow responding to the event notification.

TIdFTPServer.OnRetrieveFile
TIdFTPServer
Allows the server to retrieve a file from the server file system.

    property OnRetrieveFile: TOnRetrieveFileEvent;

Parameters
AFilename
File to be retrieved.
ASender
Client thread for the event notification.
AStream
Destination for the contents of the file.
Description
OnRetrieveFile is a TOnRetrieveFileEvent property that represents the event handler signalled when the FTP server needs to retrieve a file stored on the server file system. OnRetrieveFile is triggered when the command event handler for the FTP RETR command verb is executed.

OnRetrieveFile allows the server to load the contents of the file specified in AFilename into the stream specified by AStream. OnRetrieveFile must create a stream to use for transferring the contents of the file, and assign the reference to AStream. OnRetrieveFile may also use the default value of AStream (Nil) to indicate that the specified file could not be found, or is not available for transfer to the client connection.

When the stream has been assigned in OnRetrieveFile, the restart position indicated in TIdFTPSErverThread.RESTPos is located in AStream prior to transfer of data on the data channel.

An FTP server implementation must assign a procedure to the event handler to allow responding to the event notification.

TIdFTPServer.OnStoreFile
TIdFTPServer
Allows the server to store a file on the server file system.

    property OnStoreFile: TOnStoreFileEvent;

Parameters
AAppend
Indicates data should be appended to an existing file.
AFilename
File to be loaded onto the local file system.
ASender
Client thread for the event notification.
AStream
Data read by the event handler.
Description
OnStoreFile is a TOnStoreFileEvent property that represents the event handler signalled when the server needs to store the contents of a file retrieved from the client connection on the server file system. OnStoreFile is triggered when the command event handlers for the FTP STOR, STOU, or APPE command verbs are executed.

OnStoreFile allows the server to perform the platform-specific API calls needed to load the data for the file specified in AFilename using the stream AStream constructed by the event handler. OnStoreFile responsible for determining if the authenticated client can store files on the local file system, and creating the stream used to load the contents of the file. AAppend indicates that data can be appended to the end of an existing file on the server file system.

An FTP server implementation must assign a procedure to the event handler to allow responding to the event notification.

TIdFTPServer.OnUserLogin
TIdFTPServer
Allows the server to perform user account authentication for a client connection.

    property OnUserLogin: TOnUserLoginEvent;

Parameters
AAuthenticated
Indicates if the client is authorized.
APassword
User credentials from the client.
ASender
Client thread for the event notification.
AUsername
User identity from the client.
Description
OnUserLogin is a TOnUserLoginEvent property that represents the event handler signalled when the FTP server needs to perform authentication for a threaded client connection. OnUserLogin is triggered when the command event handlers for the FTP USER and PASS command verbs have been executed.

OnUserLogin allows the server to perform authentication for the user account using the AUsername and APassword values supplied by the threaded client connection. OnUserLogin is used when the value in TIdFTPServerThread.UserType is utNormalUser, and UserAccounts have not been assigned for authenticating accounts in the server implementation.

OnUserLogin can be used to access resources external to the server to perform account authentication, and must set the value in AAuthenticated to indicate that the client has access to the FTP server.

When the account has been authenticated in the event handler, values in the TIdFTPServerThread client connection are updated to indicate the status and password used in the authorization process.

An FTP server implementation must assign a procedure to the event handler to allow responding to the event notification.

Use OnAfterUserLogin to perform server maintenance required after a successful authentication attempt for the client connection.

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