SmartFTP FTP Library
IFTPConnection Interface Reference

import "sfFTPLib.idl";

Public Member Functions

HRESULT Abort ()
 Cancels the currently executing blocking operation.
HRESULT Continue ()
 Continues a pending operation.
HRESULT Close ()
 Closes the connection.
HRESULT Connect ()
 Establishes a connection to the configured remote host and port.
HRESULT Disconnect ()
 Gracefully disconnects from the remote host.
HRESULT ChangeDirectory ([in] BSTR directory)
 Changes the current working directory on the server.
HRESULT UpdateWorkingDirectory ()
 Synchronizes the local WorkingDirectory property with the server.
HRESULT DownloadFile ([in] BSTR remoteFile, [in] BSTR localFile, [in] long startPositionLo, [in] long startPositionHi)
 Downloads a file from the current working directory on the remote server.
HRESULT DownloadFromCommand ([in] BSTR command, [in] VARIANT localFile, [in] long remoteStartPosLo, [in] long remoteStartPosHi)
HRESULT DownloadFileEx ([in] BSTR remoteFile, [in] VARIANT localFile, [in] ULONGLONG startPosition, [in] ULONGLONG endPosition, [in] ITransferProgressEvents *progress)
 Downloads a file from the current working directory on the remote server with extended options.
HRESULT UploadFile ([in] BSTR localFile, [in] BSTR remoteFile, [in] long startPositionLo, [in] long startPositionHi)
 Uploads a local file to the current working directory on the remote server.
HRESULT UploadFileEx ([in] VARIANT localFile, [in] BSTR remoteFile, [in] ULONGLONG startPosition, [in] ITransferProgressEvents *progress)
 Uploads a file or stream to the remote server with extended options.
HRESULT NewFile ([in] BSTR file)
 Creates a new, empty (zero-byte) file on the remote server.
HRESULT ChangeDirectoryUp ()
 Changes the current working directory to the parent directory on the remote server.
HRESULT RenameFile ([in] BSTR fileFrom, [in] BSTR fileTo)
 Renames or moves a file on the server.
HRESULT DeleteFile ([in] BSTR file)
 Deletes a file from the current working directory on the server.
HRESULT RenameDirectory ([in] BSTR directoryFrom, [in] BSTR directoryTo)
 Renames or moves a directory on the server.
HRESULT RemoveDirectory ([in] BSTR directory)
 Removes a directory from the server.
HRESULT Command ([in] BSTR command)
 Sends a raw string command to the server.
HRESULT MakeDirectory ([in] BSTR directory)
 Creates a new directory on the server.
HRESULT GetFileSize ([in] BSTR file, [out, retval] ULONGLONG *retval)
 Retrieves the size of a specified file on the server.
HRESULT GetFileSize32 ([in] BSTR file, [out, retval] long *retval)
 Retrieves the size of a specified file on the server (for legacy applications).
HRESULT ReadDirectory ([out, retval] IFTPItems **retval)
 Retrieves the contents of the current working directory on the server.
HRESULT ReadDirectoryEx ([in] ITransferProgressEvents *progress, [out, retval] IFTPItems **retval)
HRESULT ReadDirectoryFromCommand ([in] BSTR command, [out, retval] IFTPItems **retval)
HRESULT ReadDirectoryRaw ([in] VARIANT localFile)
 Downloads the raw directory listing from the server to a local file.
HRESULT GetModifyTime ([in] BSTR file, [out, retval] FILETIME *retval)
 Retrieves the last modified time of a specified file on the server.
HRESULT GetModifyTimeAsDate ([in] BSTR file, [out, retval] VARIANT *retval)
 Retrieves the last modified time of a specified file on the remote server.
HRESULT GetMLST ([in] BSTR name, [out, retval] IFTPItem **retval)
HRESULT Stat ([in] BSTR name, [out, retval] IFTPItems **retval)
 Retrieves file status or a directory listing using the control connection.
HRESULT SetModifyTime ([in] BSTR file, [in] FILETIME time)
 Sets the modification timestamp of a file on the remote server.
HRESULT SetModifyTimeAsDate ([in] BSTR file, [in] VARIANT date)
 Sets the modification timestamp of a file using an OLE Automation Date.
HRESULT SetCreateTime ([in] BSTR file, [in] FILETIME time)
 Sets the creation timestamp of a file on the remote server.
HRESULT SetCreateTimeAsDate ([in] BSTR file, [in] VARIANT date)
 Sets the creation timestamp of a file using an OLE Automation Date.
HRESULT SetUnixPermissions ([in] BSTR name, [in] long permissions)
 Sets the Unix permissions (mode) of a remote file or directory.
HRESULT GetFileHash ([in] HashAlgo algo, [in] BSTR file, [in] ULONGLONG start, [in] ULONGLONG length, [out, retval] BSTR *retval)
 Retrieves the hash value of a file or portion specified with start and length.
HRESULT ClearCommandChannel ()
 Clears the command channel.
HRESULT InitializeTransfer ()
 Explicitly applies data transfer settings to the server.
HRESULT FXPDownloadFile ([in] BSTR remoteFile, [in] ULONGLONG startPosition)
 Initiates a server-to-server (FXP) file transfer from this server.
HRESULT FXPUploadFile ([in] BSTR remoteFile, [in] ULONGLONG startPosition)
 Initiates a server-to-server (FXP) file transfer to this server.
HRESULT GetSpaceAvailable ([in] BSTR path, [out, retval] ISFTPSpaceAvailable **retval)
 Retrieves the available disk space information for a specified path on the server.
HRESULT CopyFile ([in] BSTR sourceFile, [in] BSTR destinationFile)
HRESULT SetFileLogger ([out, retval] IFileLogger **fileLogger)
 Creates a file logger sfFTPLib::FileLogger and attaches it to the Logger property.

Properties

VARIANT_BOOL Busy [get]
 Indicates whether the connection is currently executing an operation.
VARIANT_BOOL Aborted [get]
 Indicates whether the last operation was explicitly cancelled by the user.
VARIANT_BOOL UseMessageLoop [get, set]
 Controls whether the component processes Windows messages during blocking operations.
long Timeout [get, set]
 Sets the maximum time (in seconds) to wait for a network operation to complete.
ConnectionStatus ConnectionStatus [get]
 Retrieves the current state of the SSH connection.
BSTR Host [get, set]
 Specifies the destination server address.
long Port [get, set]
 Specifies the TCP port number to connect to.
ProtocolFamily ProtocolFamilyPreference [get, set]
 Controls the preference for IPv4 or IPv6 during hostname resolution.
ProtocolFamily ProtocolFamily [get]
 Retrieves the network protocol family (IPv4 or IPv6) used for the active connection.
VARIANT_BOOL Login [get, set]
 Controls whether the component automatically performs the USER/PASS authentication sequence upon connection.
BSTR Username [get, set]
 Gets or sets the username used for authentication.
BSTR Password [get, set]
 Gets or sets the password used for authentication.
FTPProtocol Protocol [get, set]
 Gets or sets the security protocol used for the connection.
PortMode PortMode [get, set]
 Controls how the client determines the IP address sent in the PORT command (Active Mode).
BSTR PortIP [get, set]
 Specifies the IP address sent to the server during Active Mode (PORT) negotiations.
VARIANT_BOOL Passive [get, set]
 Controls whether the data connection is established in Passive (PASV) or Active (PORT) mode.
DataTransferType DataTransferType [get, set]
 Gets or sets the transfer mode (ASCII vs. Binary) for file operations.
DataProtection DataProtection [get, set]
DataProtection CommandProtection [get, set]
VARIANT_BOOL PROTFallback [get, set]
 Controls whether the client falls back to an unencrypted data channel if encrypted data transfer (PROT P) fails.
long CodePage [get, set]
PassiveMode PassiveMode [get, set]
 Controls how the client determines the target IP address for Passive Mode data connections.
VARIANT_BOOL LimitLocalPortRange [get, set]
 Enables the use of a specific pool of local ports for data connections.
VARIANT_BOOL UseMLSD [get, set]
 Controls whether the component uses the MLSD command if supported by the server.
DataTransferMode DataTransferMode [get, set]
 Gets or sets the transmission mode (Stream, Block, or Compressed) used for data transfer.
long LISTOption [get, set]
 Gets or sets the flags used for the FTP LIST command.
long DataTransferSpeedLimit [get, set]
 Sets a maximum bandwidth limit for data transfers.
VARIANT_BOOL SSCN [get, set]
 Enables or disables the sending of the SSCN command for secure FXP transfers.
FeatureDiscoveryMode FeatureDiscovery [get, set]
 Configures when the FEAT command is sent to discover server capabilities.
long FileBufferSize [get, set]
 Sets the size of the internal memory buffer used for local file I/O operations.
VARIANT_BOOL IdleKeepAlive [get, set]
 Enables automatic "keep-alive" packets to prevent connection timeouts during inactivity.
VARIANT_BOOL TransferKeepAlive [get, set]
 Enables the sending of NOOP commands on the Control Channel during active file transfers.
long KeepAliveInterval [get, set]
 Sets the time interval (in seconds) between automatic keep-alive packets.
IFTPClientId ClientId [get, set]
 Gets or sets the client identification information sent to the server via the CSID and CLNT commands.
VARIANT_BOOL HidePassword [get, set]
 Controls whether the password is masked in the component's log output.
BSTR WorkingDirectory [get]
 Retrieves the current remote working directory.
BSTR PeerName [get]
 Retrieves the IP address of the currently connected remote server.
IFTPServerState ServerState [get]
 Retrieves the interface used to inspect the current state of the server session.
IProxySettings Proxy [get]
 Accesses the proxy configuration settings for the connection.
ITlsSocket SSLSocketLayer [get]
 Retrieves the underlying TLS socket object used for secure communication.
ISocketSettings SocketSettings [get]
 Accesses the low-level TCP socket configuration.
ISpeedLimitSettings SpeedLimitSettings [get]
 Accesses the bandwidth throttling configuration for this specific connection.
ILogger Logger [set]
 Attaches a logging mechanism to the FTP session for debugging and auditing.
long CompressionLevel [get, set]
 Controls the aggressiveness of the zlib compression algorithm.
BSTR LastReply [get]
 Retrieves the raw text response received from the FTP server for the most recent command.
long LastReplyCode [get]
 Retrieves the numeric status code returned by the FTP server for the most recent command.
BSTR LastCommand [get]
 Retrieves the raw text of the most recent FTP command sent to the server.
HRESULT LastError [get]
 Retrieves the HRESULT error code of the most recent operation.
HRESULT LastDataConnectionError [get]
 Retrieves the specific error code encountered on the Data Channel socket.
ULONGLONG LastTransferBytes [get]
 Retrieves the total number of bytes transferred during the last SFTP transfer.
long LastTransferBytesLo [get]
 Retrieves the lower 32 bits of the last transfer size.
long LastTransferBytesHi [get]
 Retrieves the upper 32 bits of the last transfer size.
long LastTransferTime [get]
 Retrieves the duration of the last FTP transfer in milliseconds.
long LastTransferSpeed [get]
 Retrieves the average data transfer rate of the last FTP transfer.
BSTR PassiveAddress [get, set]
 Specifies or retrieves the IP address used for Server-to-Server (FXP) data connections.
BSTR Account [get, set]
 Gets or sets the account information used for the ACCT command.

Member Function Documentation

◆ Abort()

HRESULT IFTPConnection::Abort ( )

Cancels the currently executing blocking operation.

◆ ChangeDirectory()

HRESULT IFTPConnection::ChangeDirectory ( [in] BSTR directory)

Changes the current working directory on the server.

The CWD command is sent to request a directory change.

Parameters
[in]directoryThe relative or absolute path of the target directory.

◆ ChangeDirectoryUp()

HRESULT IFTPConnection::ChangeDirectoryUp ( )

Changes the current working directory to the parent directory on the remote server.

This method sends the standard CDUP (Change Directory Up) command. It is functionally equivalent to calling ChangeDirectory("..").

See also
ChangeDirectory

◆ ClearCommandChannel()

HRESULT IFTPConnection::ClearCommandChannel ( )

Clears the command channel.

Executes the 'CCC' (Clear Command Channel) command. If successful, the control connection continues in non-secure mode.

◆ Close()

HRESULT IFTPConnection::Close ( )

Closes the connection.

To ungracefully close the connection use the Disconnect method.

Remarks
Close is automatically called in the destructor of the object.

◆ Command()

HRESULT IFTPConnection::Command ( [in] BSTR command)

Sends a raw string command to the server.

Remarks
The library automatically appends the required CRLF (\r\n) terminators.
Parameters
[in]commandThe command string to send (e.g., "NOOP").

◆ Connect()

HRESULT IFTPConnection::Connect ( )

Establishes a connection to the configured remote host and port.

◆ Continue()

HRESULT IFTPConnection::Continue ( )

Continues a pending operation.

This method can resume an operation which returned with FTPLIB_E_PAUSED or FTPLIB_E_MOREDATA.

◆ CopyFile()

HRESULT IFTPConnection::CopyFile ( [in] BSTR sourceFile,
[in] BSTR destinationFile )

◆ DeleteFile()

HRESULT IFTPConnection::DeleteFile ( [in] BSTR file)

Deletes a file from the current working directory on the server.

Sends the 'DELE' command. Note that this method does not support full paths; the session must first be navigated to the target directory.

Parameters
[in]fileThe filename of the target to be removed (no path information).

◆ Disconnect()

HRESULT IFTPConnection::Disconnect ( )

Gracefully disconnects from the remote host.

Initiates a formal shutdown by sending the 'QUIT' command. The client will wait for a server response and a clean socket closure.

Remarks
  • Fallback: If the server fails to respond or close the connection within the timeout period, the client will perform an ungraceful close.
  • Abortion: Calling Abort during this process forces an immediate socket closure.
  • Ungraceful Close: For an immediate disconnect without the 'QUIT' handshake, use Close.

◆ DownloadFile()

HRESULT IFTPConnection::DownloadFile ( [in] BSTR remoteFile,
[in] BSTR localFile,
[in] long startPositionLo,
[in] long startPositionHi )

Downloads a file from the current working directory on the remote server.

Opens a data connection and issues the 'RETR' command. If a non-zero start position is provided, the 'REST' command is sent first to resume the
transfer from the specified offset.

Parameters
[in]remoteFileThe filename of the remote file in the current directory (no path information).
[in]localFileThe full path to the local file.
[in]startPositionLoLow-order 32 bits of the 64-bit resume offset.
[in]startPositionHiHigh-order 32 bits of the 64-bit resume offset.

◆ DownloadFileEx()

HRESULT IFTPConnection::DownloadFileEx ( [in] BSTR remoteFile,
[in] VARIANT localFile,
[in] ULONGLONG startPosition,
[in] ULONGLONG endPosition,
[in] ITransferProgressEvents * progress )

Downloads a file from the current working directory on the remote server with extended options.

This method functions similarly to DownloadFile but offers greater control over the destination and transfer range.

Flexible Destination: The localFile parameter is a VARIANT that supports multiple types:

  • String (BSTR): The full path to a local file (standard download).
  • Interface (IStream): A pointer to an IStream object (stream download). The method will write directly to this stream, allowing for in-memory processing or custom storage implementations.

Partial Transfers: You can download a specific byte range of a file by setting both startPosition and endPosition. This is useful for:

  • Resuming interrupted downloads (set startPosition to the last received byte).
  • Downloading specific segments (e.g., retrieving just the header of a large file).
Parameters
[in]remoteFileThe name of the file to retrieve from the remote server.
Note
This must be a filename only; do not include path information.
Parameters
[in]localFileThe destination for the data (file path string or IStream object).
[in]startPositionThe 0-based byte offset to start downloading from.
[in]endPositionThe 0-based byte offset to stop downloading at. Pass 0 or 18446744073709551615 (UINT64_MAX) to download until the end of the file.
[in]progressAn optional pointer to an ITransferProgressEvents interface to receive real-time progress updates.
See also
DownloadFile
ITransferProgressEvents

◆ DownloadFromCommand()

HRESULT IFTPConnection::DownloadFromCommand ( [in] BSTR command,
[in] VARIANT localFile,
[in] long remoteStartPosLo,
[in] long remoteStartPosHi )

◆ FXPDownloadFile()

HRESULT IFTPConnection::FXPDownloadFile ( [in] BSTR remoteFile,
[in] ULONGLONG startPosition )

Initiates a server-to-server (FXP) file transfer from this server.

This method orchestrates the FXP (File eXchange Protocol) download process. The behavior of the method depends heavily on the state of the Passive property.

Control Flow:

  1. Sends the PASV command.
  2. Returns FTPLIB_E_PAUSED.
  3. The address returned by the server is stored in PassiveAddress.
  4. You must call Continue to proceed.
  1. Checks PassiveAddress.
  2. If PassiveAddress is empty, returns FTPLIB_E_MOREDATA (waiting for address).
  3. Sends the PORT command.
  4. Returns FTPLIB_E_PAUSED to allow synchronization with the secondary connection.
  5. You must call Continue to proceed.
Remarks
The user is responsible for setting the correct data transfer settings before calling this method:
Parameters
[in]remoteFileThe name of the file to retrieve from the remote server.
Note
This must be a filename only; do not include path information.
Parameters
[in]startPositionThe resume offset (byte position).
Return values
S_OKOperation initiated successfully (though flow may be paused).
FTPLIB_E_PAUSEDThe operation is paused waiting for synchronization or the Continue call.
FTPLIB_E_MOREDATAMissing required data (e.g., PassiveAddress in active mode).
See also
Continue
Passive
PassiveAddress

◆ FXPUploadFile()

HRESULT IFTPConnection::FXPUploadFile ( [in] BSTR remoteFile,
[in] ULONGLONG startPosition )

Initiates a server-to-server (FXP) file transfer to this server.

This method orchestrates the FXP (File eXchange Protocol) upload process. The behavior of the method depends heavily on the state of the Passive property.

Control Flow:

  1. Sends the PASV command.
  2. Returns FTPLIB_E_PAUSED.
  3. The address returned by the server is stored in PassiveAddress.
  4. You must call Continue to proceed.
  1. Checks PassiveAddress.
  2. If PassiveAddress is empty, returns FTPLIB_E_MOREDATA (waiting for address).
  3. Sends the PORT command.
  4. Returns FTPLIB_E_PAUSED to allow synchronization with the secondary connection.
  5. You must call Continue to proceed.
Remarks
The user is responsible for setting the correct data transfer settings before calling this method:
Parameters
[in]remoteFileThe name of the file to store on the remote server.
Note
This must be a filename only; do not include path information.
Parameters
[in]startPositionThe resume offset (byte position).
Return values
S_OKOperation initiated successfully (though flow may be paused).
FTPLIB_E_PAUSEDThe operation is paused waiting for synchronization or the Continue call.
FTPLIB_E_MOREDATAMissing required data (e.g., PassiveAddress in active mode).
See also
Continue
Passive
PassiveAddress

◆ GetFileHash()

HRESULT IFTPConnection::GetFileHash ( [in] HashAlgo algo,
[in] BSTR file,
[in] ULONGLONG start,
[in] ULONGLONG length,
[out, retval] BSTR * retval )

Retrieves the hash value of a file or portion specified with start and length.

Sends a server-specific hash command (e.g., XCRC, XMD5, XSHA1). If both start and length are zero, the command is sent without range parameters, requesting a hash of the entire file.

Note
Use IFTPServerState::IsHashAlgoAvailable to verify server support before calling this.
Parameters
[in]algoThe hashing algorithm to use.
[in]fileThe filename of the remote file in the current directory (no path information).
[in]startStarting offset
[in]lengthNumber of bytes to hash
[out]retvalA pointer to a BSTR that receives the calculated hash value as a hexadecimal string.

◆ GetFileSize()

HRESULT IFTPConnection::GetFileSize ( [in] BSTR file,
[out, retval] ULONGLONG * retval )

Retrieves the size of a specified file on the server.

This method sends the standard SIZE command to the server.

Important Behavior: Before sending the command, this method automatically configures the server's transfer type to match the current DataTransferType property. This is strictly necessary because the result of the SIZE command may vary depending on the mode (e.g., an ASCII text file may report a different size than its binary equivalent due to line-ending conversions).

Parameters
[in]fileThe name of the file in the current directory.
Note
This must be a filename only; do not include path information.
Parameters
[out]retvalA pointer to a 64-bit integer that receives the file size in bytes.
See also
DataTransferType

◆ GetFileSize32()

HRESULT IFTPConnection::GetFileSize32 ( [in] BSTR file,
[out, retval] long * retval )

Retrieves the size of a specified file on the server (for legacy applications).

This method functions identically to GetFileSize. This method returns a 32-bit integer. For modern applications, it is strongly recommended to use GetFileSize (which returns 64-bit values) instead.

◆ GetMLST()

HRESULT IFTPConnection::GetMLST ( [in] BSTR name,
[out, retval] IFTPItem ** retval )

◆ GetModifyTime()

HRESULT IFTPConnection::GetModifyTime ( [in] BSTR file,
[out, retval] FILETIME * retval )

Retrieves the last modified time of a specified file on the server.

Because FTP servers vary in their support for file metadata, this method employs a fallback strategy to retrieve the timestamp. It attempts the following commands in order until one succeeds:

  1. MDTM (Standard Modification Time)
  2. MFMT (Modify Fact)
  3. SITE UTIME (Legacy Unix extension)
Remarks
VBScript/JavaScript: Use the GetModifyTimeAsDate method.
Parameters
[in]fileThe name of the file in the current directory.
Note
This must be a filename only; do not include path information.
Parameters
[out]retvalA pointer to a FILETIME structure that receives the last modify time in UTC.

◆ GetModifyTimeAsDate()

HRESULT IFTPConnection::GetModifyTimeAsDate ( [in] BSTR file,
[out, retval] VARIANT * retval )

Retrieves the last modified time of a specified file on the remote server.

This method is a convenience wrapper that retrieves the file's modification time and automatically converts it into a VARIANT of type VT_DATE. See GetModifyTime.

Parameters
[in]fileThe filename of the remote file in the current directory.
Note
This must be a filename only; do not include path information.
Parameters
[out]retvalA pointer to a VARIANT structure that receives the date. The resulting variant will have the type VT_DATE.

◆ GetSpaceAvailable()

HRESULT IFTPConnection::GetSpaceAvailable ( [in] BSTR path,
[out, retval] ISFTPSpaceAvailable ** retval )

Retrieves the available disk space information for a specified path on the server.

This method queries the server for storage statistics by sending the AVBL command.

Command Support: The AVBL command is a non-standard FTP extension. If the server does not explicitly support this command (often found in high-end or specific mainframe FTP implementations), this method will return an error.

Parameters
[in]pathThe remote path to query
[out]retvalReceives the ISFTPSpaceAvailable interface pointer.

◆ InitializeTransfer()

HRESULT IFTPConnection::InitializeTransfer ( )

Explicitly applies data transfer settings to the server.

This method sends the necessary FTP commands to synchronize the server's state with the client's current configuration. It ensures the server is ready for a transfer by applying the following properties:

Note
Automatic Usage: * You generally do not need to call this method manually. High-level methods like UploadFile and DownloadFile automatically invoke this internally before starting a transfer.

◆ MakeDirectory()

HRESULT IFTPConnection::MakeDirectory ( [in] BSTR directory)

Creates a new directory on the server.

This method sends the standard MKD (Make Directory) command to the server to create a subdirectory in the current working directory.

Parameters
[in]directoryThe name of the new directory to create.
Note
This must be a directory name only; do not include path information (e.g., use "NewFolder", not "/path/to/NewFolder").
See also
RemoveDirectory
ChangeDirectory

◆ NewFile()

HRESULT IFTPConnection::NewFile ( [in] BSTR file)

Creates a new, empty (zero-byte) file on the remote server.

This method opens a data connection and immediately closes it without sending data, effectively creating an empty file using the standard STOR command.

Warning
Overwrite Risk: If a file with the specified name already exists in the current directory, it will be overwritten (truncated to zero length) without warning.
Parameters
[in]fileThe name of the file to create in the current directory.
Note
This must be a filename only; do not include path information.
See also
MakeDirectory

◆ ReadDirectory()

HRESULT IFTPConnection::ReadDirectory ( [out, retval] IFTPItems ** retval)

Retrieves the contents of the current working directory on the server.

This method initiates a data transfer to list the files and subdirectories in the current location.

Command Strategy:

  1. Attempts MLSD (Machine List Directory) first. This provides a standardized, machine-readable listing.
  2. If MLSD is not supported, falls back to LIST. This provides a traditional, human-readable listing which the library parses.
Parameters
[out]retvalA pointer to an IFTPItems collection interface that receives the directory listing.
See also
IFTPItems

◆ ReadDirectoryEx()

HRESULT IFTPConnection::ReadDirectoryEx ( [in] ITransferProgressEvents * progress,
[out, retval] IFTPItems ** retval )

◆ ReadDirectoryFromCommand()

HRESULT IFTPConnection::ReadDirectoryFromCommand ( [in] BSTR command,
[out, retval] IFTPItems ** retval )

◆ ReadDirectoryRaw()

HRESULT IFTPConnection::ReadDirectoryRaw ( [in] VARIANT localFile)

Downloads the raw directory listing from the server to a local file.

This method executes a directory listing command (LIST or MLSD) and streams the server's response directly to a file on the local filesystem.

Use Case: This is primarily useful for:

  • Debugging: Analyzing the exact format returned by a specific FTP server.
  • Custom Parsing: If the built-in parser fails, you can save the raw data and process it manually.
Parameters
[in]localFileThe full path to the local file where the raw listing will be saved.
Note
If the file already exists, it will be overwritten.
See also
ReadDirectory

◆ RemoveDirectory()

HRESULT IFTPConnection::RemoveDirectory ( [in] BSTR directory)

Removes a directory from the server.

This method sends the standard RMD (Remove Directory) command to delete the specified directory.

Warning
Constraint: Per the FTP protocol, the directory must be empty (contain no files or subdirectories) before it can be removed. If the directory contains any items, the server will reject the command with an error.
Parameters
[in]directoryThe name (or relative path) of the directory to remove.
Note
This is relative to the current working directory.
See also
MakeDirectory

◆ RenameDirectory()

HRESULT IFTPConnection::RenameDirectory ( [in] BSTR directoryFrom,
[in] BSTR directoryTo )

Renames or moves a directory on the server.

This method executes the standard two-step FTP rename sequence:

  1. Sends RNFR (Rename From) to identify the existing directory.
  2. Sends RNTO (Rename To) to specify the new name or location.

Move Capability: You can move a directory to a new location by specifying a relative or absolute path in the directoryTo parameter (e.g., renaming "Photos" to "../Archive/Photos").

Parameters
[in]directoryFromThe current name (or path) of the directory.
[in]directoryToThe new name (or path) for the directory.
See also
RenameFile

◆ RenameFile()

HRESULT IFTPConnection::RenameFile ( [in] BSTR fileFrom,
[in] BSTR fileTo )

Renames or moves a file on the server.

This method executes the standard two-step FTP rename sequence:

  1. Sends RNFR (Rename From) to identify the existing file.
  2. Sends RNTO (Rename To) to specify the new name or location.

Move Capability: You can move a file to a new location by specifying a relative or absolute path in the fileTo parameter (e.g., renaming "photo.jpg" to "../Archive/photo.jpg").

Parameters
[in]fileFromThe current name (or path) of the file.
[in]fileToThe new name (or path) for the file.
See also
RenameDirectory

◆ SetCreateTime()

HRESULT IFTPConnection::SetCreateTime ( [in] BSTR file,
[in] FILETIME time )

Sets the creation timestamp of a file on the remote server.

This method attempts to change the file's metadata using the MFCT or MFF (Modify Fact) command.

Server Support: This operation relies on the server supporting the MFCT or MFF extension (draft-somers-ftp-mfxx-04).

Remarks
Scripting Languages: If you are using VBScript, classic ASP, or PowerShell, use SetCreateTimeAsDate instead, as they cannot natively handle the FILETIME structure.
Parameters
[in]fileThe name of the remote file.
Note
This must be a filename only; do not include path information.
Parameters
[in]timeThe new creation timestamp in UTC format.
See also
SetCreateTimeAsDate
SetModifyTime

◆ SetCreateTimeAsDate()

HRESULT IFTPConnection::SetCreateTimeAsDate ( [in] BSTR file,
[in] VARIANT date )

Sets the creation timestamp of a file using an OLE Automation Date.

This method is a convenience wrapper for SetCreateTime. It accepts a date in VARIANT format (specifically VT_DATE).

Target Audience: This method is designed for scripting environments (such as VBScript, classic ASP, or PowerShell) where constructing a raw C++ FILETIME structure is difficult or impossible.

Parameters
[in]fileThe name of the remote file in the current directory.
Note
This must be a filename only; do not include path information.
Parameters
[in]dateThe new creation timestamp as a VARIANT (must be of type VT_DATE).
See also
SetCreateTime

◆ SetFileLogger()

HRESULT IFTPConnection::SetFileLogger ( [out, retval] IFileLogger ** fileLogger)

Creates a file logger sfFTPLib::FileLogger and attaches it to the Logger property.

Warning: * Calling this method a second time will detach and destroy the previous logger, replacing it with a new, unconfigured instance.

Typical Usage Workflow:

  1. Call SetFileLogger to get the interface.
  2. Set the log file path (e.g., File = c:\logs\ssh.log) on the returned object.
  3. Call Connect.
Parameters
[out]fileLoggerReceives the pointer to the newly created and attached IFileLogger interface.

◆ SetModifyTime()

HRESULT IFTPConnection::SetModifyTime ( [in] BSTR file,
[in] FILETIME time )

Sets the modification timestamp of a file on the remote server.

This method attempts to change the file's metadata using the MFMT or MFF (Modify Fact) command.

Server Support: This operation relies on the server supporting the MFMT or MFF extension (draft-somers-ftp-mfxx-04).

Remarks
Scripting Languages: If you are using VBScript, classic ASP, or PowerShell, use SetModifyTimeAsDate instead, as they cannot natively handle the FILETIME structure.
Parameters
[in]fileThe name of the remote file.
Note
This must be a filename only; do not include path information.
Parameters
[in]timeThe new modification timestamp in UTC format.
See also
SetModifyTimeAsDate
SetCreateTime

◆ SetModifyTimeAsDate()

HRESULT IFTPConnection::SetModifyTimeAsDate ( [in] BSTR file,
[in] VARIANT date )

Sets the modification timestamp of a file using an OLE Automation Date.

This method is a convenience wrapper for SetModifyTime. It accepts a date in VARIANT format (specifically VT_DATE).

Target Audience: This method is designed for scripting environments (such as VBScript, classic ASP, or PowerShell) where constructing a raw C++ FILETIME structure is difficult or impossible.

Parameters
[in]fileThe name of the remote file in the current directory.
Note
This must be a filename only; do not include path information.
Parameters
[in]dateThe new modification timestamp as a VARIANT (must be of type VT_DATE).
See also
SetModifyTime

◆ SetUnixPermissions()

HRESULT IFTPConnection::SetUnixPermissions ( [in] BSTR name,
[in] long permissions )

Sets the Unix permissions (mode) of a remote file or directory.

This method attempts to change the access permissions of the specified item using the standard Unix permission bits.

Command Strategy: It attempts the following commands to apply the permissions:

  1. MFF UNIX.mode= (Modify Fact)
  2. SITE CHMOD (Standard Unix extension)

If the server supports neither command, the operation fails.

Remarks
Octal Notation: Unix permissions are typically represented as octal numbers (e.g., 0755 for rwxr-xr-x). When passing the permissions argument in C++, ensure you use the leading 0 to indicate an octal literal, or pass the correct decimal equivalent.
Parameters
[in]nameThe name of the remote file or directory.
Note
This must be a name only; do not include path information (relative to current directory).
Parameters
[in]permissionsThe new Unix permission bits (e.g., 0644).

◆ Stat()

HRESULT IFTPConnection::Stat ( [in] BSTR name,
[out, retval] IFTPItems ** retval )

Retrieves file status or a directory listing using the control connection.

This method sends the STAT command with the specified argument.

  • Key Difference: Unlike ReadDirectory (which requires opening a secondary data connection), STAT returns the listing immediately over the existing Command/Control connection.
Warning
Parsing Reliability: The output format of the STAT command is less standardized than MLSD.

◆ UpdateWorkingDirectory()

HRESULT IFTPConnection::UpdateWorkingDirectory ( )

Synchronizes the local WorkingDirectory property with the server.

This method sends the standard PWD (Print Working Directory) command to the server and updates the library's internal state with the result.

Use Case: Call this method to verify the current location if you suspect the client and server have become out of sync (e.g., after a failed navigation command, a complex script, or a server-side timeout).

See also
WorkingDirectory
ChangeDirectory

◆ UploadFile()

HRESULT IFTPConnection::UploadFile ( [in] BSTR localFile,
[in] BSTR remoteFile,
[in] long startPositionLo,
[in] long startPositionHi )

Uploads a local file to the current working directory on the remote server.

This method opens a data connection and transfers the file content using the standard STOR (Store) command.

Resuming Transfers: If a non-zero start position is provided (via startPositionLo and startPositionHi), the method first sends the REST (Restart) command. This instructs the server to begin writing data at the specified offset, effectively resuming a broken transfer.

Parameters
[in]localFileThe full path to the local file to be uploaded.
[in]remoteFileThe name to store the file as on the remote server.
Note
This must be a filename only; do not include path information.
Parameters
[in]startPositionLoThe low-order 32 bits of the 64-bit resume offset.
[in]startPositionHiThe high-order 32 bits of the 64-bit resume offset. (Combine these to specify the byte offset to restart a broken transfer).
See also
DownloadFile

◆ UploadFileEx()

HRESULT IFTPConnection::UploadFileEx ( [in] VARIANT localFile,
[in] BSTR remoteFile,
[in] ULONGLONG startPosition,
[in] ITransferProgressEvents * progress )

Uploads a file or stream to the remote server with extended options.

This method provides an advanced interface for transferring data to the server, supporting both local filesystem sources and in-memory streams.

Flexible Source: The localFile parameter is a VARIANT that supports multiple types:

  • String (BSTR): The full path to a file on the local disk.
  • Interface (IStream): A pointer to an IStream object. The method will read data directly from the stream, allowing you to upload data generated in memory without saving it to a temporary file first.

Resuming Transfers: If startPosition is non-zero, the method sends the REST (Restart) command before the STOR command. This allows the server to append or overwrite data starting at the specified byte offset, facilitating the resumption of interrupted uploads.

Parameters
[in]localFileThe source of the data (a full file path string or an IStream object).
[in]remoteFileThe name to be used for the file on the remote server.
Note
This must be a filename only; do not include path information.
Parameters
[in]startPositionThe 64-bit byte offset at which to start the upload on the server.
[in]progressAn optional pointer to an ITransferProgressEvents interface to receive real-time callbacks regarding the transfer's status and byte count.
See also
ITransferProgressEvents
UploadFile

Property Documentation

◆ Aborted

VARIANT_BOOL IFTPConnection::Aborted
getproperty

Indicates whether the last operation was explicitly cancelled by the user.

The Context: Long-running operations like DownloadFile, or UploadFile can be interrupted using the Abort method.

The Mechanism:

  • VARIANT_TRUE: The most recent operation failed because the Abort method was called.
  • VARIANT_FALSE: The operation finished normally (success) or failed due to a genuine error (network timeout, permission denied, etc.).

Usage: This property is essential for error handling logic. It allows you to distinguish between "The network crashed" (Error) and "The user clicked Cancel" (Not an Error).

Parameters
[out]retvalReceives VARIANT_TRUE if aborted; VARIANT_FALSE otherwise.

◆ Account

BSTR IFTPConnection::Account
getsetproperty

Gets or sets the account information used for the ACCT command.

The Role: Some FTP servers (particularly mainframes, VMS, or systems with strict billing/accounting) require an additional ACCT command during the login sequence to authorize the session or allocate resources.

Automatic Handling: The component monitors the server's response to the PASS command.

  • If the server returns 332 Account for login, the component automatically sends the string stored in this property via the ACCT command.
  • If the server does not request it, this property is ignored.

Common Scenarios:

  • Mainframes: Accessing specific project partitions or billing codes.
  • Firewalls: Some application-layer gateways use ACCT to authenticate the user to the firewall itself before passing traffic to the destination FTP server.
Parameters
[in]newValueThe account string (e.g., a project ID, billing code, or secondary password).
[out]retvalReceives the current account string.

◆ Busy

VARIANT_BOOL IFTPConnection::Busy
getproperty

Indicates whether the connection is currently executing an operation.

◆ ClientId

IFTPClientId IFTPConnection::ClientId
getsetproperty

Gets or sets the client identification information sent to the server via the CSID and CLNT commands.

The Context (CSID and CLNT): The FTP protocol has seen various extensions implemented by different vendors to allow a client to identify itself.

  • CSID: The "Client System Identification" command, often used by Windows-based or commercial servers.
  • CLNT: The "Client" command, commonly supported by Unix-based servers (like ProFTPD or Pure-FTPd).

The Mechanism: This property accepts a pointer to an IFTPClientId object. The component uses the data in this object to automatically issue the appropriate identification command (CSID, CLNT, or both) based on the server's reported capabilities.

Usage: Identifying your client application allows server administrators to track usage stats and enables the server to apply specific compatibility workarounds if it detects a known client version.

Parameters
[in]newValueA pointer to an IFTPClientId interface containing the application's identity.
[out]retvalReceives the current IFTPClientId interface pointer.
Returns
S_OK on success.

◆ CodePage

long IFTPConnection::CodePage
getsetproperty

◆ CommandProtection

DataProtection IFTPConnection::CommandProtection
getsetproperty

◆ CompressionLevel

long IFTPConnection::CompressionLevel
getsetproperty

Controls the aggressiveness of the zlib compression algorithm.

This property tunes the balance between data size reduction and CPU usage.

Range: * - 1 (Fastest): Minimal compression, lowest CPU overhead. Ideal for fast networks.

  • 5 (Default): A balanced setting suitable for most internet connections.
  • 9 (Best): Maximum compression, highest CPU overhead. Ideal for very slow connections (e.g., Satellite, EDGE).
Parameters
[in]newValueAn integer between 1 and 9.
[out]retvalReceives the current compression level.

◆ ConnectionStatus

ConnectionStatus IFTPConnection::ConnectionStatus
getproperty

Retrieves the current state of the SSH connection.

This property allows you to check if the client is currently connected, connecting, or disconnected.

Parameters
[out]retvalReceives the ConnectionStatus enumeration value.

◆ DataProtection

DataProtection IFTPConnection::DataProtection
getsetproperty

◆ DataTransferMode

DataTransferMode IFTPConnection::DataTransferMode
getsetproperty

Gets or sets the transmission mode (Stream, Block, or Compressed) used for data transfer.

The Mechanism: This property controls the structure of the data sent over the data connection. It maps directly to the FTP MODE command.

Parameters
[in]newValueA value from the DataTransferMode enumeration.
[out]retvalReceives the current mode.

◆ DataTransferSpeedLimit

long IFTPConnection::DataTransferSpeedLimit
getsetproperty

Sets a maximum bandwidth limit for data transfers.

The Mechanism: This property artificially throttles the speed of file uploads and downloads by pausing the data stream at regular intervals.

Value:

  • 0 (Default): No limit. Transfers run as fast as the network and hardware allow.
  • Positive Integer: The maximum speed in Bytes per Second.
  • Example: 10240 limits the speed to 10 KB/s.
  • Example: 1048576 limits the speed to 1 MB/s.
Parameters
[in]newValueThe maximum speed in bytes/second. Set to 0 to disable throttling.
[out]retvalReceives the current speed limit setting.

◆ DataTransferType

DataTransferType IFTPConnection::DataTransferType
getsetproperty

Gets or sets the transfer mode (ASCII vs. Binary) for file operations.

The Mechanism: FTP supports two primary transfer modes that determine how bytes are handled during transit.

Parameters
[in]newValueA value from the DataTransferType enumeration.
[out]retvalReceives the current transfer type.

◆ FeatureDiscovery

FeatureDiscoveryMode IFTPConnection::FeatureDiscovery
getsetproperty

Configures when the FEAT command is sent to discover server capabilities.

The Context (Capability Discovery): Modern FTP is highly extensible. The FEAT command allows the client to ask: "What extra features do you support besides basic file transfer?"

Default Value: ftpFeatureDiscoveryModeAfterLogin (1). Compatibility Note: The default is set to "After Login" because many firewalls, NAT routers with "FTP Inspection" enabled, and security proxies view the FEAT command as an unauthorized probe if sent before authentication. Sending it too early can cause these devices to terminate the connection.

Virtual Hosting & The HOST Command:

Note
If your server requires the HOST command (RFC 7151) to navigate to a specific virtual domain, you must set this property to @ ftpFeatureDiscoveryModeBeforeAndAfterLogin. This ensures the client discovers the HOST capability immediately after connection so it can send the virtual hostname before attempting to log in.

Impact on Workflow: The results of the FEAT command are used internally to automatically enable features like MLSD or UTF8 path encoding.

Parameters
[in]newValueThe FeatureDiscoveryMode enum value.
[out]retvalReceives the current FEAT negotiation setting.

◆ FileBufferSize

long IFTPConnection::FileBufferSize
getsetproperty

Sets the size of the internal memory buffer used for local file I/O operations.

The Mechanism: When uploading or downloading files, the component moves data between the Network Socket and the Local Disk. This property controls the size of the data chunk handled in each disk interaction.

  • Uploads: The component reads FileBufferSize bytes from the local file into RAM, then sends them to the network.
  • Downloads: The component receives data from the network, accumulates it in RAM, and writes it to the local disk only when FileBufferSize bytes are ready.

Performance Tuning: Larger buffer sizes reduce the number of disk I/O interrupts (context switches), which can significantly improve performance on high-speed networks (1Gbps+) or when writing to high-latency storage (e.g., network shares or mechanical drives).

Constraints:

  • Minimum Value: 32 KB (32768 bytes). If a smaller value is provided, it is ignored or clamped to the minimum.
  • Default Value: 64 KB (65536 bytes).
Parameters
[in]newValueThe buffer size in bytes. Must be at least 32768.
[out]retvalReceives the current buffer size setting.

◆ HidePassword

VARIANT_BOOL IFTPConnection::HidePassword
getsetproperty

Controls whether the password is masked in the component's log output.

The Context: When the component connects to an FTP server, it sends the PASS command containing the user's password. If logging is enabled (via Logger or similar mechanisms), this command is recorded in the log file.

The Solution:

  • VARIANT_TRUE (Enabled): The component replaces the actual password string with asterisks (e.g., PASS ******) in all generated logs and trace events.
  • VARIANT_FALSE (Disabled): The password is written to the log in plain text.

Default Value: VARIANT_FALSE (Disabled). By default, passwords are visible in logs to aid in initial debugging.

Security Best Practice: Always keep this property enabled in production environments. Disable it only temporarily if you are debugging a specific authentication issue and need to verify exactly what characters are being sent to the server.

Parameters
[in]newValueVARIANT_TRUE to mask the password; VARIANT_FALSE to reveal it.
[out]retvalReceives the current setting.

◆ Host

BSTR IFTPConnection::Host
getsetproperty

Specifies the destination server address.

Parameters
[in]newValueThe hostname or IP address string.
[out]retvalReceives the current host setting.

◆ IdleKeepAlive

VARIANT_BOOL IFTPConnection::IdleKeepAlive
getsetproperty

Enables automatic "keep-alive" packets to prevent connection timeouts during inactivity.

The Problem: TCP connections, especially those traversing NAT routers and firewalls, are often dropped if no data flows for a certain period (e.g., 5-10 minutes). FTP servers also have "Idle Timeout" settings (often 300-900 seconds) that disconnect silent clients to save resources.

The Solution: When set to VARIANT_TRUE, the component automatically sends a lightweight command NOOP to the server at regular intervals if no other commands are being executed.

  • This traffic resets the idle timers on the server, routers, and firewalls, keeping the control channel open.

Default Value: VARIANT_FALSE (Disabled). By default, the component remains silent when idle.

Parameters
[in]newValueVARIANT_TRUE to enable keep-alive packets; VARIANT_FALSE to disable them.
[out]retvalReceives the current setting.

◆ KeepAliveInterval

long IFTPConnection::KeepAliveInterval
getsetproperty

Sets the time interval (in seconds) between automatic keep-alive packets.

The Mechanism: This property controls the frequency of the NOOP commands sent by both IdleKeepAlive and TransferKeepAlive.

  • The component starts a timer after the last command was sent. When the timer reaches KeepAliveInterval, a NOOP is triggered to maintain the connection.

Tuning Guide:

  • Goal: Set this value to be lower than the timeout setting of the strictest device in your network chain (Router, Firewall, or Server).
  • Example: If your corporate firewall drops idle connections after 5 minutes (300s), set this property to 30 or 60 seconds to stay safe.
  • Warning: Setting this too low (e.g., 1 second) will spam the server logs and waste bandwidth.

Default Value: 30 seconds.

Parameters
[in]newValueThe interval in seconds.
[out]retvalReceives the current interval setting.

◆ LastCommand

BSTR IFTPConnection::LastCommand
getproperty

Retrieves the raw text of the most recent FTP command sent to the server.

This property stores the last command string exactly as it was written to the socket.

Security Note: If the last command was PASS (sending a password), this property will return the password in plain text unless internal masking is active. Treat the output of this property as sensitive data.

Parameters
[out]retvalReceives the command string (e.g., "SIZE file.png").

◆ LastDataConnectionError

HRESULT IFTPConnection::LastDataConnectionError
getproperty

Retrieves the specific error code encountered on the Data Channel socket.

The Context (Dual Channels): FTP uses two distinct connections:

  1. Control Channel: Sends commands (e.g., MLSD, RETR) and receives status texts.
  2. Data Channel: Transfers the actual file contents or directory listings.

The Problem: A command might succeed on the Control Channel (e.g., Server says "150 Opening data connection"), but the Data Channel might fail due to a firewall block, a TLS handshake failure, or a timeout. In this scenario, the main command error might be generic, obscuring the root cause.

The Solution: LastDataConnectionError captures the specific error code from the ephemeral data socket.

Usage: Check this property if a transfer fails but LastReplyCode indicates a preliminary success (1xx) or if LastError is vague. It is invaluable for debugging Passive/Active mode mismatches and FTPS certificate issues.

Parameters
[out]retvalReceives the HRESULT code.

◆ LastError

HRESULT IFTPConnection::LastError
getproperty

Retrieves the HRESULT error code of the most recent operation.

The Context: When you call methods on the IFTPConnection interface (e.g., Connect, DownloadFile), they return an HRESULT indicating success or failure.

The Mechanism: This property stores that return value internally. It allows you to check the status of the last operation at a later time, or from a different part of your code (e.g., in a centralized error handler).

Reset Behavior: The value is overwritten by every new method call. It is not automatically reset to S_OK unless a new operation succeeds.

Parameters
[out]retvalReceives the HRESULT code (e.g., 0 for success, non-zero for failure).

◆ LastReply

BSTR IFTPConnection::LastReply
getproperty

Retrieves the raw text response received from the FTP server for the most recent command.

The Context: Every action you perform (connecting, downloading, listing files) involves sending a command to the server. The server responds with a status code and a human-readable message.

The Mechanism: This property automatically updates after every single interaction with the server. It contains the full text of the last response line (including the numeric code).

Usage:

  • Error Diagnosis: If a method returns an error code (e.g., E_FAIL), check LastReply to see the server's specific reason (e.g., "550 Disk quota exceeded" vs "550 Permission denied").
  • Custom Parsing: Some servers return useful information in the text message (e.g., usage statistics) that isn't captured by other properties.

Format: Standard FTP responses follow the format: [3-digit Code] [Text Message].

Parameters
[out]retvalReceives the raw response string (e.g., "226 Transfer complete.").

◆ LastReplyCode

long IFTPConnection::LastReplyCode
getproperty

Retrieves the numeric status code returned by the FTP server for the most recent command.

The Context: Every FTP server response begins with a 3-digit number indicating the result of the operation. This property parses that number from the raw response string.

The Mechanism: If the server responds with 226 Transfer complete., this property returns 226.

Parameters
[out]retvalReceives the 3-digit status code (e.g., 200, 550). Returns 0 if no command has been executed.

◆ LastTransferBytes

ULONGLONG IFTPConnection::LastTransferBytes
getproperty

Retrieves the total number of bytes transferred during the last SFTP transfer.

The Scope: This value represents the payload size successfully sent or received in the most recent file transfer (upload or download) or directory listing. It resets at the start of each new transfer.

Parameters
[out]retvalReceives the number of bytes transferred.

◆ LastTransferBytesHi

long IFTPConnection::LastTransferBytesHi
getproperty

Retrieves the upper 32 bits of the last transfer size.

Legacy Support: This property is provided for languages or environments (like VB6) It represents the LastTransferBytes >> 32.

Calculation: To reconstruct the full 64-bit value manually: (High * 2^32) + Low.

Parameters
[out]retvalReceives the high-order double word of the byte count.

◆ LastTransferBytesLo

long IFTPConnection::LastTransferBytesLo
getproperty

Retrieves the lower 32 bits of the last transfer size.

Legacy Support: This property is provided for languages or environments (like VB6) that do not natively support 64-bit integers. It represents the LastTransferBytes & 0xFFFFFFFF.

Parameters
[out]retvalReceives the low-order double word of the byte count.

◆ LastTransferSpeed

long IFTPConnection::LastTransferSpeed
getproperty

Retrieves the average data transfer rate of the last FTP transfer.

The Calculation: This value is derived automatically from LastTransferBytes and LastTransferTime. It represents the average speed over the entire duration of the operation.

Speed = LastTransferBytes / (LastTransferTime / 1000)

Edge Cases: If the transfer time was effectively zero (e.g., extremely small files < 1KB), this property returns 0 to avoid division-by-zero errors.

Parameters
[out]retvalReceives the transfer speed in Bytes per second.

◆ LastTransferTime

long IFTPConnection::LastTransferTime
getproperty

Retrieves the duration of the last FTP transfer in milliseconds.

The Measurement: This value represents the elapsed wall-clock time from the start of the request to the receipt of the final response (or error). It applies to file transfers (upload/download), and directory listings.

Parameters
[out]retvalReceives the elapsed time in milliseconds (e.g., 1500 for 1.5 seconds).

◆ LimitLocalPortRange

VARIANT_BOOL IFTPConnection::LimitLocalPortRange
getsetproperty

Enables the use of a specific pool of local ports for data connections.

The Problem: In Active Mode (Passive = FALSE), the client opens a local port and waits for the server to connect to it. By default, the OS assigns a random port (ephemeral port).

  • Firewall Issue: Local firewalls block incoming connections on random ports. You cannot open "all ports" without compromising security.

The Solution: Setting this property to VARIANT_TRUE instructs the component to request a port number from the global sfFTPLib::FTPPortPool singleton (specifically calling IFTPPortPool::NextPort).

Usage Workflow:

  1. Configure the global sfFTPLib::FTPPortPool with a specific range (e.g., 6000-6050).
  2. Set LimitLocalPortRange to TRUE.
  3. Configure your local firewall to allow incoming connections on ports 6000-6050.

Effect: The component will cycle through the defined ports for each data transfer, allowing you to maintain a strict firewall policy.

Parameters
[in]newValueVARIANT_TRUE to engage the Port Pool; VARIANT_FALSE to let the OS choose random ports.
[out]retvalReceives the current setting.

◆ LISTOption

long IFTPConnection::LISTOption
getsetproperty

Gets or sets the flags used for the FTP LIST command.

The Mechanism: This property defines a bitmask of LISTOption values. When a directory listing is requested, the component converts these flags into a command-line argument string (e.g., "-la") and appends it to the LIST command sent to the FTP server.

Modern Alternatives (MLST/MLSD): Most modern FTP servers support RFC 3659 extensions, specifically the MLST and MLSD commands. These commands provide a standardized, machine-parsable format that removes the need for "dash" arguments. This LISTOption property is only relevant when the component falls back to the legacy LIST command.

Default Value: 0 (None). By default, no options are sent with the LIST command.

RFC 959 Compliance: This property is disabled by default because "dash" arguments (like -l or -a) are not part of the formal RFC 959 specification.

  • Strict RFC 959 servers may return a 501 Syntax error if flags are provided.
  • Legacy Unix-based servers often require these flags to provide detailed metadata or show hidden files when MLSD is unavailable.
Parameters
[in]newValueA bitmask of LISTOption flags.
[out]retvalReceives the current bitmask of LISTOption flags.

◆ Logger

ILogger IFTPConnection::Logger
setproperty

Attaches a logging mechanism to the FTP session for debugging and auditing.

This property allows you to capture the internal activity of the component. By assigning an object that implements the ILogger interface, you can redirect log messages to a file, the console, or a custom monitoring system.

See also
sfFTPLib::FileLogger
Parameters
[in]loggerA pointer to an ILogger implementation. Set to NULL to disable logging.

◆ Login

VARIANT_BOOL IFTPConnection::Login
getsetproperty

Controls whether the component automatically performs the USER/PASS authentication sequence upon connection.

The Mechanism: When the Connect method is called, the component establishes the TCP/IP connection (and TLS handshake if using FTPS).

  • If Login is TRUE (Default): The component immediately sends the USER command (using the Username property) followed by the PASS command (using the Password property).
  • If Login is FALSE: The component establishes the network connection and waits. It does not send credentials automatically.

Default Value: VARIANT_TRUE (Enabled). Most applications want to authenticate immediately.

Parameters
[in]newValueSet to VARIANT_TRUE to auto-login; VARIANT_FALSE to connect without logging in.
[out]retvalReceives the current setting.

◆ Passive

VARIANT_BOOL IFTPConnection::Passive
getsetproperty

Controls whether the data connection is established in Passive (PASV) or Active (PORT) mode.

The Mechanism: FTP requires two channels: a Control Channel (port 21) and a Data Channel (for file transfers and directory listings). This property determines who initiates the Data Channel connection.

Default Value: VARIANT_TRUE (Enabled). By default, the component uses Passive mode. This is the standard configuration for modern internet usage, as it works seamlessly behind client-side NAT routers and firewalls.

Modes:

  • VARIANT_TRUE (Passive Mode): The Client connects to the Server.
  • Command: Sends PASV (or EPSV). The server opens a random port and tells the client to connect to it.
  • Benefit: Highly firewall-friendly for the client.
  • VARIANT_FALSE (Active Mode): The Server connects back to the Client.
  • Command: Sends PORT (or EPRT). The client opens a random port and tells the server to connect to it.
  • Drawback: Often fails if the client is behind a NAT or firewall that blocks incoming connections.
Parameters
[in]newValueSet to VARIANT_TRUE for Passive mode; VARIANT_FALSE for Active mode.
[out]retvalReceives the current mode setting.

◆ PassiveAddress

BSTR IFTPConnection::PassiveAddress
getsetproperty

Specifies or retrieves the IP address used for Server-to-Server (FXP) data connections.

The Context (FXP): In a Server-to-Server transfer, one server acts as the "Passive" partner (listening for a connection) and the other acts as the "Active" partner (initiating the connection).

  • The Client sends PASV to the Passive Server.
  • The Client takes the IP and Port returned by the Passive Server and sends them via the PORT command to the Active Server.

The Mechanism: This property acts as the bridge for the IP address between the two connections.

  1. On the Passive Connection (Get): After the PASV command is issued, this property is automatically populated with the IP address returned by the server in its reply (e.g., from 227 Entering Passive Mode).
  2. On the Active Connection (Put): The value set in this property is used to construct the PORT command sent to this server.
Parameters
[in]newValueThe IP address string to be used in the PORT command.
[out]retvalReceives the IP address obtained from the last PASV reply.

◆ PassiveMode

PassiveMode IFTPConnection::PassiveMode
getsetproperty

Controls how the client determines the target IP address for Passive Mode data connections.

The Problem (Server-Side NAT): When an FTP server is behind a NAT (e.g., AWS EC2, Azure VM, or corporate firewall), it often doesn't know its public IP address.

  • The Conflict: You connect to ftp.example.com (Public IP: 203.0.113.5).
  • The Response: The server sends a PASV reply saying: "Connect to me at `192.168.1.10`" (its internal private IP).
  • The Failure: If the client obeys, it tries to connect to 192.168.1.10 (a local address) and fails/timeouts.

The Solution: This property tells the component whether to trust the server's reply or to ignore it and force the connection to the original host IP (203.0.113.5).

Default Value: ftpPassiveModeAuto (3).

**Relationship to Passive Property:** This property only applies when Passive is set to TRUE. If Passive is FALSE (Active Mode), this setting is ignored.

Parameters
[in]newValueA value from the PassiveMode enumeration.
[out]retvalReceives the current setting.

◆ Password

BSTR IFTPConnection::Password
getsetproperty

Gets or sets the password used for authentication.

The Role: This property holds the secret credential associated with the Username.

Protocol Behavior: The value is sent via the PASS command immediately after the server accepts the USER command.

Security Note:

  • Standard FTP: The password is sent in cleartext. This is insecure over public networks.
  • FTPS (TLS): If the connection is secured (using AUTH TLS or Implicit SSL), the password is encrypted inside the TLS tunnel, providing safety against sniffing.
Parameters
[in]newValueThe password string.
[out]retvalReceives the current password.

◆ PeerName

BSTR IFTPConnection::PeerName
getproperty

Retrieves the IP address of the currently connected remote server.

The Context: When you connect to an FTP server using a domain name (e.g., ftp.example.com), the DNS system resolves this name to an IP address.

The Usage: This property allows you to see exactly which IP address the component is talking to.

  • Auditing: Useful for logging the specific server node in a load-balanced environment where ftp.example.com might resolve to 10.0.0.1, 10.0.0.2, etc.
  • Verification: confirms that the DNS resolution worked as expected.

Timing: This property returns a valid string only after a successful connection is established. If not connected, it returns an empty string.

Parameters
[out]retvalReceives the IP address string (e.g., "203.0.113.5").

◆ Port

long IFTPConnection::Port
getsetproperty

Specifies the TCP port number to connect to.

This property defines the listening port on the remote server.

Defaults:

  • Standard FTP: 21
Parameters
[in]newValueThe port number (default: 21).
[out]retvalReceives the current port setting.

◆ PortIP

BSTR IFTPConnection::PortIP
getsetproperty

Specifies the IP address sent to the server during Active Mode (PORT) negotiations.

The Role: In Active Mode, the client tells the server: "Connect to me at IP address X." This property defines "IP address X."

When to Use: This property is only used when:

  1. Passive is set to VARIANT_FALSE (Active Mode).
  2. PortMode is set to ftpPortModeManual.

Format: Expects a standard IPv4 address string (e.g., "203.0.113.10"). If left empty, the component falls back to using the local machine's IP.

Parameters
[in]newValueThe public IP address string.
[out]retvalReceives the current IP setting.

◆ PortMode

PortMode IFTPConnection::PortMode
getsetproperty

Controls how the client determines the IP address sent in the PORT command (Active Mode).

The Problem (Client-Side NAT): In Active Mode (Passive = FALSE), the client must send its IP address to the server so the server can connect back to it.

  • The Conflict: Your computer knows its local IP (e.g., 192.168.1.5).
  • The Reality: The server (on the internet) cannot reach 192.168.1.5. It needs your Public IP (the WAN address of your router).

The Solution: This property determines whether the component sends the local machine's IP or a custom override provided in the PortIP property.

Prerequisites:

  • This property is only relevant when Passive property is set to FALSE (Active Mode).
  • If set to ftpPortModeManual, you must populate the PortIP property before connecting.

Default Value: ftpPortModeDefault (1).

Parameters
[in]newValueA value from the PortMode enumeration.
[out]retvalReceives the current setting.

◆ PROTFallback

VARIANT_BOOL IFTPConnection::PROTFallback
getsetproperty

Controls whether the client falls back to an unencrypted data channel if encrypted data transfer (PROT P) fails.

The Context (PROT Command): In an FTPS session, the PROT (Protection Level) command determines if file contents and directory listings are encrypted.

  • PROT P (Private): Data is encrypted via TLS.
  • PROT C (Clear): Data is sent in plaintext.

The Mechanism: When the connection uses a secure protocol (e.g., ftpProtocolRequireTLS), the component defaults to attempting PROT P to ensure maximum security for your files.

Values:

  • VARIANT_TRUE (Default): If the server rejects the PROT P command or if the TLS negotiation for the data channel fails, the component will automatically downgrade the data channel to PROT C (Clear/Unencrypted) and continue.
  • VARIANT_FALSE: The component will strictly enforce encryption. If PROT P fails, the transfer or listing will be aborted with an error.

Security Warning: The default value (TRUE) prioritizes connectivity. However, if a fallback occurs, your file data will be visible to network sniffers, even though your password (sent on the Control Channel) remains encrypted.

Parameters
[in]newValueSet to VARIANT_TRUE to allow fallback to cleartext; VARIANT_FALSE to enforce strict encryption.
[out]retvalReceives the current fallback setting.

◆ Protocol

FTPProtocol IFTPConnection::Protocol
getsetproperty

Gets or sets the security protocol used for the connection.

The Mechanism: This property dictates the initial handshake behavior when Connect is called. It determines the default port (if not explicitly set) and whether the component attempts to negotiate an encrypted TLS session.

Default Value: The default setting is ftpProtocolPreferTLS.

Parameters
[in]newValueA value from the FTPProtocol enumeration.
[out]retvalReceives the current protocol setting.

◆ ProtocolFamily

ProtocolFamily IFTPConnection::ProtocolFamily
getproperty

Retrieves the network protocol family (IPv4 or IPv6) used for the active connection.

This property indicates whether the underlying TCP connection was established using Internet Protocol version 4 or version 6.

Parameters
[out]retvalReceives the ProtocolFamily enumeration value.

◆ ProtocolFamilyPreference

ProtocolFamily IFTPConnection::ProtocolFamilyPreference
getsetproperty

Controls the preference for IPv4 or IPv6 during hostname resolution.

This property determines which network protocol stack the client attempts to use when the Host property contains a domain name (e.g., "ftp.example.com") that resolves to multiple IP addresses.

Parameters
[in]newValueThe ProtocolFamily value to enforce.
[out]retvalReceives the current preference setting.

◆ Proxy

IProxySettings IFTPConnection::Proxy
getproperty

Accesses the proxy configuration settings for the connection.

This property returns the IProxySettings interface, which allows you to define how the SSH connection should be routed through an intermediate server.

Parameters
[out]retvalReceives the IProxySettings interface pointer.

◆ ServerState

IFTPServerState IFTPConnection::ServerState
getproperty

Retrieves the interface used to inspect the current state of the server session.

The Role: While the main IFTPConnection interface controls the desired configuration (what you want to happen), the IFTPServerState interface reports the actual status (what has happened).

Parameters
[out]retvalReceives the pointer to the IFTPServerState interface.

◆ SocketSettings

ISocketSettings IFTPConnection::SocketSettings
getproperty

Accesses the low-level TCP socket configuration.

This property returns the ISocketSettings interface, which allows you to fine-tune the underlying network socket behavior before or during a connection.

Parameters
[out]retvalReceives the ISocketSettings interface pointer.

◆ SpeedLimitSettings

ISpeedLimitSettings IFTPConnection::SpeedLimitSettings
getproperty

Accesses the bandwidth throttling configuration for this specific connection.

This property returns the ISpeedLimitSettings interface, which allows you to restrict the maximum upload and download rates for this SSH session.

Parameters
[out]retvalReceives the ISpeedLimitSettings interface pointer.

◆ SSCN

VARIANT_BOOL IFTPConnection::SSCN
getsetproperty

Enables or disables the sending of the SSCN command for secure FXP transfers.

The Problem (Secure FXP): When transferring files directly between two FTP servers (FXP) using FTPS (SSL/TLS), a security mechanism called TLS Session Resumption often causes failures.

  • Normally, an FTPS server requires the Data Channel to share the same TLS Session ID as the Control Channel to prevent "Data Connection Stealing" attacks.
  • In an FXP transfer, the two servers connect directly to each other. They cannot share the client's TLS session. Consequently, the servers reject the connection.

The Solution: Setting this property to VARIANT_TRUE instructs the component to send the SSCN ON command to the server before the transfer begins.

  • This commands the server to relax its session reuse requirements and prepare to accept a secure connection from a third-party (the other FTP server).
Parameters
[in]newValueVARIANT_TRUE to send SSCN ON; VARIANT_FALSE (Default) to disable it.
[out]retvalReceives the current setting.

◆ SSLSocketLayer

ITlsSocket IFTPConnection::SSLSocketLayer
getproperty

Retrieves the underlying TLS socket object used for secure communication.

The Architecture: The FTP component is built on top of a specialized socket interface (ITlsSocket) that handles all TCP and TLS operations.

Parameters
[out]retvalReceives the pointer to the ITlsSocket interface.

◆ Timeout

long IFTPConnection::Timeout
getsetproperty

Sets the maximum time (in seconds) to wait for a network operation to complete.

This property defines the timeout threshold for all blocking calls, such as connecting, reading data, or waiting for a server response. If an operation exceeds this duration, it is aborted and returns an error.

Default:

  • The default value is 30 (30 seconds).
Parameters
[in]newValueThe timeout duration in seconds.
[out]retvalReceives the current timeout setting.

◆ TransferKeepAlive

VARIANT_BOOL IFTPConnection::TransferKeepAlive
getsetproperty

Enables the sending of NOOP commands on the Control Channel during active file transfers.

The Problem (The "Hanging" Transfer): FTP uses two separate connections: a Control Channel (commands) and a Data Channel (file contents).

  • During a large file transfer (e.g., a 10GB video), the Data Channel is very busy, but the Control Channel sits completely silent.
  • The Conflict: Network firewalls and NAT routers monitor connection activity. If they see the Control Channel idle for too long (typically 5-10 minutes), they silently drop the connection to save memory.
  • The Result: The file transfers successfully (100%), but when the client tries to tell the server "I'm finished" on the Control Channel, the line is dead. The client hangs indefinitely or reports a timeout error despite a successful upload.

The Solution: When set to VARIANT_TRUE, the component periodically sends a NOOP command on the Control Channel while the data is still flowing on the Data Channel.

  • This traffic "tickles" the intermediate routers, reminding them that the session is still active.

Important Note: While effective, sending commands during a transfer technically violates strict FTP protocol (which expects the client to wait). However, most modern servers handle this gracefully by ignoring the NOOP or queuing the response until the transfer finishes.

Default Value: VARIANT_FALSE (Disabled).

Parameters
[in]newValueVARIANT_TRUE to enable NOOP injection; VARIANT_FALSE to disable.
[out]retvalReceives the current setting.

◆ UseMessageLoop

VARIANT_BOOL IFTPConnection::UseMessageLoop
getsetproperty

Controls whether the component processes Windows messages during blocking operations.

This property determines how the library behaves while waiting for a network response.

Settings:

  • VARIANT_FALSE (Default): The calling thread is put to sleep until the operation completes.
  • Pros: Higher performance, no re-entrancy risks.
  • Cons: The application UI will freeze and be marked as "Not Responding" by Windows during long transfers.
  • VARIANT_TRUE: The library pumps the Windows Message Queue while waiting.
  • Pros: The UI remains responsive (repaints, moves, minimizes).
  • Cons: Slower performance. Risk of Re-entrancy: Users might click a "Connect" button again while the first connection is still in progress.

When to use TRUE: Enable this if you are using the component on the Main UI Thread of a desktop application (VB6, VBA, Delphi, WinForms) and want to keep the window responsive.

When to use FALSE: Keep this disabled for Console apps, Windows Services, or background worker threads where no UI interaction exists.

Parameters
[in]newValueSet to VARIANT_TRUE to enable message pumping; VARIANT_FALSE to disable it.
[out]retvalReceives the current setting.

◆ UseMLSD

VARIANT_BOOL IFTPConnection::UseMLSD
getsetproperty

Controls whether the component uses the MLSD command if supported by the server.

The Mechanism: Modern FTP servers support the RFC 3659 extension, which introduces the MLST (for single file) and MLSD (for directories) commands. Unlike the legacy LIST command, which returns unformatted text that must be guessed/parsed, MLST and MLSD return standardized, machine-readable metadata (facts).

Default Value: VARIANT_TRUE (Enabled). The component will automatically attempt to use these modern commands if the server advertises support in its FEAT (Features) response.

Benefits of Enabling (TRUE):

  • Precision: Accurately retrieves file sizes, timestamps (in UTC), and permissions without parsing errors.
  • Efficiency: Removes the need for the LISTOption property and complex regex parsing.
  • Reliability: Standardized across different OS types (Linux, Windows, etc.).

When to Disable (FALSE): You might set this to VARIANT_FALSE if a specific server has a buggy or non-standard implementation of RFC 3659 that causes listings to fail or return incomplete data. When disabled, the component falls back to the legacy LIST command.

Parameters
[in]newValueSet to VARIANT_TRUE to prefer modern listing commands; VARIANT_FALSE to force legacy LIST.
[out]retvalReceives the current setting.
Returns
S_OK on success.

◆ Username

BSTR IFTPConnection::Username
getsetproperty

Gets or sets the username used for authentication.

The Role: This property identifies the user account on the remote FTP server. It is the first credential sent during the login sequence.

Protocol Behavior: The value provided here is sent via the standard USER command immediately after the control connection is established.

Formatting:

  • Case Sensitivity: Unix/Linux-based FTP servers are case-sensitive (e.g., "Root" != "root"). Windows (IIS) servers are typically case-insensitive.
  • Encoding: The username is transmitted using the character encoding defined in the CodePage property.
Parameters
[in]newValueThe username string.
[out]retvalReceives the current username.

◆ WorkingDirectory

BSTR IFTPConnection::WorkingDirectory
getproperty

Retrieves the current remote working directory.

This property tracks the directory path where the session is currently located on the server.

Parameters
[out]retvalPointer to a BSTR that receives the current absolute path.
The documentation for this interface was generated from the following file: