The FtpClient class allows Qore code to communicate with FTP servers with the FTP and FTPS protocols. More...

#include <QC_FtpClient.dox.h>

Public Member Methods
	clearStats ()
	Clears performance statistics. More...

nothing	clearWarningQueue ()
	Removes any warning Queue object from the Socket. More...

nothing	connect ()
	Connects to the FTP server and attempts a login; if any errors occur, an exception is thrown. More...

	constructor ()
	Creates an empty FtpClient object. More...

	constructor (string url)
	Creates an FtpClient object and initializes it with a URL. More...

	copy ()
	Throws an exception to prevent copying of objects this class. More...

nothing	cwd (string path)
	Changes the current working directory on the server. More...

nothing	del (string remote_path)
	Deletes a file from the FTP server; if any errors occur, an exception is thrown. More...

	destructor ()
	Disconnects any remote connection and destroys the object. More...

nothing	disconnect ()
	Disconnects from an FTP server. More...

nothing	get (string remote_path, *string local_path)
	Gets a file from the FTP server and stores it on the local filesystem; if any errors occur, an exception is thrown. More...

nothing	get (string remote_path, Qore::OutputStream os)
	Gets a file from the FTP server and writes it to an OutputStream; if any errors occur, an exception is thrown. More...

binary	getAsBinary (string remote_path)
	Gets a file from the FTP server and returns it as a binary. More...

string	getAsString (string remote_path, *string encoding)
	Gets a file from the FTP server and returns it as a string. More...

hash< auto >	getControlPeerInfo (bool host_lookup=True)
	Returns information about the remote end of the control socket as a hash. More...

hash< auto >	getControlSocketInfo (bool host_lookup=True)
	Returns information about the local control socket as a hash. More...

hash< auto >	getDataPeerInfo (bool host_lookup=True)
	Returns information about the remote data socket as a hash. More...

hash< auto >	getDataSocketInfo (bool host_lookup=True)
	Returns information about the local data socket as a hash. More...

*string	getHostName ()
	Returns the current hostname value or NOTHING if none is set. More...

string	getMode ()
	returns a string for the connection mode: `"port"`, `"pasv"`, `"epsv"`, or `"auto"` if not connected and auto mode is set More...

int	getNetworkFamily ()
	Returns the network address family to use for new connections. More...

*string	getPassword ()
	Returns the current password value or NOTHING if none is set. More...

int	getPort ()
	Retrieves the current connection port value for this object. More...

*string	getSSLCipherName ()
	Returns the name of the cipher for an encrypted connection or NOTHING if an encrypted connection is not established. More...

*string	getSSLCipherVersion ()
	Returns the version of the cipher for an encrypted connection or NOTHING if an encrypted connection is not established. More...

int	getTimeout ()
	returns the socket I/O timeout value as an integer in milliseconds More...

string	getURL ()
	Retrieves the current connection URL string for this object. More...

hash	getUsageInfo ()
	Returns performance statistics for the socket. More...

*string	getUserName ()
	Returns the current username value or NOTHING if none is set. More...

bool	isDataSecure ()
	Returns True if the data connections are secure TLS/SSL connections, False if not. More...

bool	isSecure ()
	Returns True if the control connection is a secure TLS/SSL connection, False if not. More...

*string	list ()
	Returns a list of files from the FTP server in the server's long format in the current working directory or NOTHING if the path cannot be found. More...

*string	list (string path)
	Returns a list of files from the FTP server in the server's long format for the given path or NOTHING if the path cannot be found. More...

nothing	mkdir (string remote_path)
	Creates a directory on the FTP server; if any errors occur, an exception is thrown. More...

*string	nlst ()
	Returns a list of file names from the FTP server in the current working directory or NOTHING if the path cannot be found. More...

*string	nlst (string path)
	Returns a list of file names from the FTP server for the given path or NOTHING if the path cannot be found. More...

nothing	put (string local_path, *string remote_path)
	Transfers a local file to the FTP server; if any errors occur, an exception is thrown. More...

nothing	put (Qore::InputStream is, string remote_path)
	Transfers the content of an InputStream to the FTP server; if any errors occur, an exception is thrown. More...

nothing	putData (string data, string remote_path)
	Transfers string data to the FTP server and saves it as a file on the remote machine; if any errors occur, an exception is thrown. More...

nothing	putData (binary data, string remote_path)
	Transfers binary data to the FTP server and saves it as a file on the remote machine; if any errors occur, an exception is thrown. More...

string	pwd ()
	Returns the server-side current working directory. More...

nothing	rename (string from, string to)
	Renames/moves a file or directory; if any errors occur, an exception is thrown. More...

nothing	rmdir (string remote_path)
	Removes a directory on the remote FTP server; if any errors occur, an exception is thrown. More...

hash< FtpResponseInfo >	sendControlMessage (string cmd, string arg)
	Sends a message on the control connection with a reply on the control connection only. More...

nothing	setControlEventQueue ()
	Clears any Queue object that may be set on the FtpClient object so that I/O events are no longer captured on the object on the control connection. More...

nothing	setControlEventQueue (Qore::Thread::Queue queue, auto arg, *bool with_data)
	Sets a Queue object to receive FtpClient and Socket events on the control connection. More...

nothing	setDataEventQueue ()
	Clears any Queue object that may be set on the FtpClient object so that I/O events are no longer captured on the object on the data connection. More...

nothing	setDataEventQueue (Qore::Thread::Queue queue, auto arg, *bool with_data)
	Sets a Queue object to receive FtpClient and Socket events on the data connection. More...

nothing	setEventQueue ()
	Clears any Queue object that may be set on the FtpClient object so that I/O events are no longer captured on the object on either the data or control connections. More...

nothing	setEventQueue (Qore::Thread::Queue queue, auto arg, *bool with_data)
	Sets a Queue object to receive FtpClient and Socket events on both the data and control connections. More...

nothing	setHostName (string host)
	Sets the hostname or address to use to connect to for the next connection. More...

nothing	setInsecure ()
	Make a non-encrypted connection to the server on the next connect. More...

nothing	setInsecureData ()
	Make a non-encrypted data connection to the server on the next connect even if the control connection is secure. More...

nothing	setModeAuto ()
	Sets the object to automatically try to negotiate the data connections in `EPSV`, `PASV`, and `PORT` modes, in that order. More...

nothing	setModeEPSV ()
	Sets the object to only try to make data connections using `EPSV` (RFC-2428 extended passive) mode. More...

nothing	setModePASV ()
	Sets the object to only try to make data connections using `PASV` (RFC-959 passive) mode. More...

nothing	setModePORT ()
	Sets the object to only try to make data connections using `PORT` mode. More...

nothing	setNetworkFamily (int family)
	Sets the network address family to use for new connections; use this method to restrict connections to IPv4 or IPv6 connections. More...

nothing	setPassword (string pass)
	Sets the password to use for the next connection. More...

nothing	setPort (int port)
	Sets the control port value to use for the next connection (the FTP protocol default is 21) More...

nothing	setSecure (bool secure=True)
	Make an FTPS connection to the server on the next connect if the argument is True. More...

	setTimeout (timeout timeout_ms)
	sets the socket I/O timeout value in milliseconds More...

nothing	setURL (string url)
	Sets the connection and login parameters based on the URL passed as an argument. More...

nothing	setUserName (string user)
	Sets the user name to use for the next connection. More...

nothing	setWarningQueue (int warning_ms, int warning_bs, Queue queue, auto arg, timeout min_ms=1s)
	Sets a Queue object to receive socket warnings. More...

*string	verifyPeerCertificate ()
	Returns a string code giving the result of verifying the remote certificate or NOTHING if an encrypted connection is not established. More...

Detailed Description

The FtpClient class allows Qore code to communicate with FTP servers with the FTP and FTPS protocols.

Restrictions:: Qore::PO_NO_NETWORK

The constructor takes an optional URL with the following format:
[(ftp|ftps)://][username[:password]@]hostname[:port]

If the URL is not set with the constructor, then the connection parameters must be set with the FtpClient::set*() methods. At the very minimum the hostname must be set. If any path name is given in the URL, it is ignored. See the following table for default URL parameters.

FtpClient::constructor() Default URL Parameters

Field	Default Value
`protocol`	`"ftp"` (unencrypted)
`username`	`"anonymous"`
`password`	`"[email protected]"`
`port`	`21`

Once the URL (at least the hostname) has been set, any method requiring a connection will make an implicit call to FtpClient::connect() to attempt to connect and login to the FTP server before executing the method.

Objects of this class are capable of making encrypted FTPS connections according to RFC-4217. TLS/SSL encrypted control and data connection will be attempted if the protocol is set to "ftps" or the FtpClient::setSecure() method is called before connecting.

Note that "sftp", or FTP over ssh, is not supported with this class; FTPS is an extension of the FTP protocol to allow for secure connections; while "sftp" is FTP over an encrypted ssh connection. For sftp and ssh support, use the ssh2 module.

When a data connection is required, by default the following modes are tried in series:

EPSV (Extended Passive Mode)
PASV (Passive Mode)
PORT (Port mode)

If the FTP server does not support one of these methods, or network conditions do not allow a data connection of any of these types to be established, then an exception is thrown.

To manually control which modes are tried, see the FtpClient::setModeEPSV(), FtpClient::setModePASV(), and FtpClient::setModePORT() methods.

This class supports posting network events to a Queue, either events on the control or data channels or both can be monitored. See I/O Event Handling for more information.

The events raised by this object are listed in the following table:

FtpClient Events

Name	Value	Description
EVENT_FTP_SEND_MESSAGE	`9`	Raised immediately before an FTP control message is sent
EVENT_FTP_MESSAGE_RECEIVED	`10`	Raised when an FTP reply is received on the control channel

FtpClient Timeouts

FtpClient objects have a default socket I/O timeout value of 60 seconds. The following methods can be used to set or retrieve the socket I/O timeout value:

Note: This class is not available with the PO_NO_NETWORK parse option.

Member Function Documentation

◆ clearStats()

Qore::FtpClient::clearStats ( )

Clears performance statistics.

Example:: ftp.clearStats();

Since: Qore 0.8.9

See also: FtpClient::getUsageInfo()

◆ clearWarningQueue()

nothing Qore::FtpClient::clearWarningQueue ( )

Removes any warning Queue object from the Socket.

Example:: ftp.clearWarningQueue();

See also: FtpClient::setWarningQueue()

Since: Qore 0.8.9

◆ connect()

nothing Qore::FtpClient::connect ( )

Connects to the FTP server and attempts a login; if any errors occur, an exception is thrown.

This method does not need to be called explicitly; connections are established implicitly by all methdods that communicate with FTP servers.

Connection parameters are set in the constructor or in the FtpClient::set*() methods

Events:: EVENT_CONNECTING, EVENT_CONNECTED, EVENT_HOSTNAME_LOOKUP, EVENT_HOSTNAME_RESOLVED, EVENT_START_SSL, EVENT_SSL_ESTABLISHED, EVENT_FTP_SEND_MESSAGE, EVENT_FTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_PACKET_SENT

Example:: ftp.connect();

Exceptions

FTP-RESPONSE-ERROR	Invalid response received from FTP server
SOCKET-CONNECT-ERROR	Cannot establish socket connection to FTP server
FTP-CONNECT-ERROR	no hostname set, FTP server reported an error, etc
FTP-LOGIN-ERROR	Login denied by FTP server

◆ constructor() [1/2]

Qore::FtpClient::constructor ( )

Creates an empty FtpClient object.

Example:: FtpClient ftp();

◆ constructor() [2/2]

Qore::FtpClient::constructor ( string url )

Creates an FtpClient object and initializes it with a URL.

It accepts one argument that will set the URL for the FTP connection; the path is ignored in the URL, however the username, password, hostname and port are respected; additionally if the protocol (or scheme) is "ftps", the client will attempt to establish a secure connection to the server according to RFC-4217 when the first connection is established.

Parameters

url	The URL of the server to connect to; must have at least a hostname

Example:: FtpClient ftp("ftp://user:[email protected]:2021");

Exceptions

UNSUPPORTED-PROTOCOL	Only `"ftp"` or `"ftps"` are allowed as the protocol in the URL
FTP-URL-ERROR	No hostname given in the URL

◆ copy()

Qore::FtpClient::copy ( )

Throws an exception to prevent copying of objects this class.

Exceptions

FTPCLIENT-COPY-ERROR FtpClient objects cannot be copied

◆ cwd()

nothing Qore::FtpClient::cwd ( string path )

Changes the current working directory on the server.

Events:: EVENT_FTP_SEND_MESSAGE, EVENT_FTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_PACKET_SENT

Example:: ftp.cwd("/foo/bar");

Exceptions

FTP-RECEIVE-ERROR	Incomplete message received on control port
FTP-CWD-ERROR	FTP server returned an error to the CWD command

Note: see FtpClient::connect() for additional exceptions that could be thrown when connections are implicitly established

◆ del()

nothing Qore::FtpClient::del ( string remote_path )

Deletes a file from the FTP server; if any errors occur, an exception is thrown.

Parameters

remote_path The path on the server to the file to delete

Events:: EVENT_FTP_SEND_MESSAGE, EVENT_FTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_PACKET_SENT

Example:: ftp.del("file-2.txt");

Exceptions

FTP-RECEIVE-ERROR	Incomplete message received on control port
FTP-DELETE-ERROR	FTP server returned an error to the `DELE` command

Note: see FtpClient::connect() for additional exceptions that could be thrown when connections are implicitly established

◆ destructor()

Qore::FtpClient::destructor ( )

Disconnects any remote connection and destroys the object.

Events:: EVENT_CHANNEL_CLOSED, EVENT_DELETED

Example:: delete ftp;

◆ disconnect()

nothing Qore::FtpClient::disconnect ( )

Disconnects from an FTP server.

Events:: EVENT_CHANNEL_CLOSED

Example:: ftp.disconnect();

◆ get() [1/2]

nothing Qore::FtpClient::get	(	string	remote_path,
		*string	local_path
	)

Gets a file from the FTP server and stores it on the local filesystem; if any errors occur, an exception is thrown.

Restrictions:: Qore::PO_NO_FILESYSTEM

Parameters

remote_path	The path on the server to the file to get
local_path	The optional local path for saving the file; if this parameter is not given in the call, then the server path is used for the local path as well

Events:: EVENT_FTP_SEND_MESSAGE, EVENT_FTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_PACKET_SENT

Example:: ftp.get("file.txt", "/tmp/file-1.txt");

Exceptions

FTP-RECEIVE-ERROR	Incomplete message received on control port
FTP-FILE-OPEN-ERROR	Could not create the local file
FTP-GET-ERROR	There was an error retrieving the file

Note

see FtpClient::connect() for additional exceptions that could be thrown when connections are implicitly established
any existing file with the same name is truncated before writing

See also: FtpClient::getAsString(), FtpClient::getAsData()

◆ get() [2/2]

nothing Qore::FtpClient::get	(	string	remote_path,
		Qore::OutputStream	os
	)

Gets a file from the FTP server and writes it to an OutputStream; if any errors occur, an exception is thrown.

Parameters

remote_path	The path on the server to the file to get
os	The output stream to write the file to

Events:: EVENT_FTP_SEND_MESSAGE, EVENT_FTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_PACKET_SENT

Example:: ftp.get("file.txt", new FileOutputStream("/tmp/file-1.txt"));

Exceptions

FTP-RECEIVE-ERROR	Incomplete message received on control port
FTP-FILE-OPEN-ERROR	Could not create the local file
FTP-GET-ERROR	There was an error retrieving the file

Note: see FtpClient::connect() for additional exceptions that could be thrown when connections are implicitly established

See also: FtpClient::getAsString(), FtpClient::getAsData()

Since: Qore 0.8.13

◆ getAsBinary()

binary Qore::FtpClient::getAsBinary ( string remote_path )

Gets a file from the FTP server and returns it as a binary.

Parameters

remote_path The path on the server to the file to get

Returns: The file data retrieved; if any errors occur an exception is raised

Events:: EVENT_FTP_SEND_MESSAGE, EVENT_FTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_PACKET_SENT

Example:: binary b = ftp.getAsBinary("file.pdf");

Exceptions

FTP-RECEIVE-ERROR	Incomplete message received on control port
FTP-FILE-OPEN-ERROR	Could not create the local file
FTP-GET-ERROR	There was an error retrieving the file

Note: see FtpClient::connect() for additional exceptions that could be thrown when connections are implicitly established

See also: FtpClient::getAsString() for a similar function returning the file's contents as a string; see FtpClient::get() for a function that will get a remote file and save it on the local filesystem

◆ getAsString()

string Qore::FtpClient::getAsString	(	string	remote_path,
		*string	encoding
	)

Gets a file from the FTP server and returns it as a string.

Parameters

remote_path	The path on the server to the file to get
encoding	the output encoding for the string; if not given, then the default encoding is used (`UTF-8`)

Returns: The file retrieved as a string; if any errors occur an exception is raised

Events:: EVENT_FTP_SEND_MESSAGE, EVENT_FTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_PACKET_SENT

Example:: string str = ftp.getAsString("file.txt");

Exceptions

FTP-RECEIVE-ERROR	Incomplete message received on control port
FTP-FILE-OPEN-ERROR	Could not create the local file
FTP-GET-ERROR	There was an error retrieving the file

Note: see FtpClient::connect() for additional exceptions that could be thrown when connections are implicitly established

See also: FtpClient::getAsBinary() for a similar function returning the file's contents as a binary; see FtpClient::get() for a function that will get a remote file and save it on the local filesystem

Since: Qore 1.3 added the encoding parameter

◆ getControlPeerInfo()

hash< auto > Qore::FtpClient::getControlPeerInfo ( bool host_lookup = True )

Returns information about the remote end of the control socket as a hash.

If the control socket is not open, an exception is thrown

Example:: hash<auto> h = ftp.getControlPeerInfo();

Parameters

host_lookup do a lookup of the hostname; if this is False then "hostname" and "hostname_desc" are not present in the response hash

Returns: a hash of information about the remote end for connected sockets

Exceptions

SOCKET-NOT-OPEN	The socket is not open
SOCKET-GETPEERINFO-ERROR	error in getpeername()

Since: Qore 0.9.0

◆ getControlSocketInfo()

hash< auto > Qore::FtpClient::getControlSocketInfo ( bool host_lookup = True )

Returns information about the local control socket as a hash.

If the control socket is not open, an exception is thrown

Example:: hash<auto> h = ftp.getControlSocketInfo();

Parameters

host_lookup do a lookup of the hostname; if this is False then "hostname" and "hostname_desc" are not present in the response hash

Returns: a hash of information about the remote end for connected sockets

Exceptions

SOCKET-NOT-OPEN	The socket is not open
SOCKET-GETSOCKETINFO-ERROR	error in getsockname()

Since: Qore 0.9.0

◆ getDataPeerInfo()

hash< auto > Qore::FtpClient::getDataPeerInfo ( bool host_lookup = True )

Returns information about the remote data socket as a hash.

If the data socket is not open, an exception is thrown

Example:: hash<auto> h = ftp.getDataPeerInfo();

Parameters

host_lookup do a lookup of the hostname; if this is False then "hostname" and "hostname_desc" are not present in the response hash

Returns: a hash of information about the remote end for connected sockets

Exceptions

SOCKET-NOT-OPEN	The socket is not open
SOCKET-GETPEERINFO-ERROR	error in getpeername()

Since: Qore 0.9.0

◆ getDataSocketInfo()

hash< auto > Qore::FtpClient::getDataSocketInfo ( bool host_lookup = True )

Returns information about the local data socket as a hash.

If the data socket is not open, an exception is thrown

Example:: hash<auto> h = ftp.getControlSocketInfo();

Parameters

host_lookup do a lookup of the hostname; if this is False then "hostname" and "hostname_desc" are not present in the response hash

Returns: a hash of information about the remote end for connected sockets

Exceptions

SOCKET-NOT-OPEN	The socket is not open
SOCKET-GETSOCKETINFO-ERROR	error in getsockname()

Since: Qore 0.9.0

◆ getHostName()

*string Qore::FtpClient::getHostName ( )

Returns the current hostname value or NOTHING if none is set.

Returns: the current hostname value that will be used for the next connection or NOTHING if none is set

Example:: *string host = ftp.getHostName();

◆ getMode()

string Qore::FtpClient::getMode ( )

returns a string for the connection mode: "port", "pasv", "epsv", or "auto" if not connected and auto mode is set

Code Flags:: CONSTANT

Example:: string mode = ftp.getMode();

Since: Qore 0.8.12

◆ getNetworkFamily()

int Qore::FtpClient::getNetworkFamily ( )

Returns the network address family to use for new connections.

Returns: the network address family to use for new connections; see Network Address Family Constants for valid values; Qore::AF_UNSPEC means to automatically choose the family (the default)

Code Flags:: CONSTANT

Example:: int family = ftp.getNetworkFamily();

Since: Qore 0.9.0

◆ getPassword()

*string Qore::FtpClient::getPassword ( )

Returns the current password value or NOTHING if none is set.

Returns: the current password value that will be used for the next connection or NOTHING if none is set

Example:: *string pass = ftp.getPassword();

◆ getPort()

int Qore::FtpClient::getPort ( )

Retrieves the current connection port value for this object.

Returns: the current port value that will be used for the next connection

Example:: int port = ftp.getPort();

◆ getSSLCipherName()

*string Qore::FtpClient::getSSLCipherName ( )

Returns the name of the cipher for an encrypted connection or NOTHING if an encrypted connection is not established.

Returns: the name of the cipher for an encrypted connection or NOTHING if an encrypted connection is not established

Code Flags:: CONSTANT

Example:: if (ftp.isSecure())

printf("secure connection: %s %s\n", ftp.getSSLCipherName(), ftp.getSSLCipherVersion());

◆ getSSLCipherVersion()

*string Qore::FtpClient::getSSLCipherVersion ( )

Returns the version of the cipher for an encrypted connection or NOTHING if an encrypted connection is not established.

Returns: the version of the cipher for an encrypted connection or NOTHING if an encrypted connection is not established

Code Flags:: CONSTANT

Example:: if (ftp.isSecure())

printf("secure connection: %s %s\n", ftp.getSSLCipherName(), ftp.getSSLCipherVersion());

◆ getTimeout()

int Qore::FtpClient::getTimeout ( )

returns the socket I/O timeout value as an integer in milliseconds

Code Flags:: CONSTANT

Returns: the socket timeout value in milliseconds

Since: Qore 0.8.12.3

◆ getURL()

string Qore::FtpClient::getURL ( )

Retrieves the current connection URL string for this object.

Returns: the current connection URL string for this object

Example:: string url = ftp.getURL();

◆ getUsageInfo()

hash Qore::FtpClient::getUsageInfo ( )

Returns performance statistics for the socket.

Code Flags:: CONSTANT

Example:: hash h = ftp.getUsageInfo();

Returns

a hash with the following keys:

"bytes_sent": an integer giving the total amount of bytes sent
"bytes_recv": an integer giving the total amount of bytes received
"us_sent": an integer giving the total number of microseconds spent sending data
"us_recv": an integer giving the total number of microseconds spent receiving data
"arg": (only if warning values have been set with FtpClient::setWarningQueue()) the optional argument for warning hashes
"timeout": (only if warning values have been set with FtpClient::setWarningQueue()) the warning timeout in microseconds
"min_throughput": (only if warning values have been set with FtpClient::setWarningQueue()) the minimum warning throughput in bytes/sec

Since: Qore 0.8.9

See also: FtpClient::clearStats()

◆ getUserName()

*string Qore::FtpClient::getUserName ( )

Returns the current username value or NOTHING if none is set.

Returns: the current username value that will be used for the next connection or NOTHING if none is set

Example:: *string user = ftp.getUserName();

◆ isDataSecure()

bool Qore::FtpClient::isDataSecure ( )

Returns True if the data connections are secure TLS/SSL connections, False if not.

Returns: True if the data connections are secure TLS/SSL connections, False if not

Code Flags:: CONSTANT

Example:: bool b = ftp.isDataSecure();

◆ isSecure()

bool Qore::FtpClient::isSecure ( )

Returns True if the control connection is a secure TLS/SSL connection, False if not.

Returns: True if the control connection is a secure TLS/SSL connection, False if not

Code Flags:: CONSTANT

Example:: bool b = ftp.isSecure();

◆ list() [1/2]

*string Qore::FtpClient::list ( )

Returns a list of files from the FTP server in the server's long format in the current working directory or NOTHING if the path cannot be found.

Events:: EVENT_FTP_SEND_MESSAGE, EVENT_FTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_PACKET_SENT

Returns: a list of files from the FTP server in the server's long format in the current working directory or NOTHING if the path cannot be found

Example:: *string str = ftp.list();

Exceptions

FTP-RECEIVE-ERROR	Incomplete message received on control port
FTP-LIST-ERROR	FTP server returned an error in response to the LIST command

Note: see FtpClient::connect() for additional exceptions that could be thrown when connections are implicitly established

See also: FtpClient::nlst()

◆ list() [2/2]

*string Qore::FtpClient::list ( string path )

Returns a list of files from the FTP server in the server's long format for the given path or NOTHING if the path cannot be found.

Parameters

path	The path or filename (or filename filter) to list (ex: `"/tmp/file*.txt"`)

Returns: a list of files from the FTP server in the server's long format for the given path or NOTHING if the path cannot be found

Events:: EVENT_FTP_SEND_MESSAGE, EVENT_FTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_PACKET_SENT

Example:: *string str = ftp.list("/tmp/file*.txt");

Exceptions

FTP-RECEIVE-ERROR	Incomplete message received on control port
FTP-LIST-ERROR	FTP server returned an error in response to the LIST command

Note: see FtpClient::connect() for additional exceptions that could be thrown when connections are implicitly established

See also: FtpClient::nlst()

◆ mkdir()

nothing Qore::FtpClient::mkdir ( string remote_path )

Creates a directory on the FTP server; if any errors occur, an exception is thrown.

Parameters

remote_path The path on the server to the directory to create

Events:: EVENT_FTP_SEND_MESSAGE, EVENT_FTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_PACKET_SENT

Example:: ftp.mkdir("tmp");

Exceptions

FTP-RECEIVE-ERROR	Incomplete message received on control port
FTP-MKDIR-ERROR	FTP server returned an error to the `MKD` command

Note: see FtpClient::connect() for additional exceptions that could be thrown when connections are implicitly established

◆ nlst() [1/2]

*string Qore::FtpClient::nlst ( )

Returns a list of file names from the FTP server in the current working directory or NOTHING if the path cannot be found.

Returns: a list of file names from the FTP server in the current working directory or NOTHING if the path cannot be found

Events:: EVENT_FTP_SEND_MESSAGE, EVENT_FTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_PACKET_SENT

Example:: *string str = ftp.nlst();

Exceptions

FTP-RECEIVE-ERROR	Incomplete message received on control port
FTP-LIST-ERROR	FTP server returned an error in response to the NLST command

Note: see FtpClient::connect() for additional exceptions that could be thrown when connections are implicitly established

See also: FtpClient::list()

◆ nlst() [2/2]

*string Qore::FtpClient::nlst ( string path )

Returns a list of file names from the FTP server for the given path or NOTHING if the path cannot be found.

Parameters

path	The path or filename (or filename filter) to list (ex: `"/tmp/file*.txt"`)

Returns: a list of file names from the FTP server for the given path or NOTHING if the path cannot be found

Events:: EVENT_FTP_SEND_MESSAGE, EVENT_FTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_PACKET_SENT

Example:: *string str = ftp.nlst("/tmp/file*.txt");

Exceptions

FTP-RECEIVE-ERROR	Incomplete message received on control port
FTP-LIST-ERROR	FTP server returned an error in response to the LIST command

Note: see FtpClient::connect() for additional exceptions that could be thrown when connections are implicitly established

See also: FtpClient::list()

◆ put() [1/2]

nothing Qore::FtpClient::put	(	Qore::InputStream	is,
		string	remote_path
	)

Transfers the content of an InputStream to the FTP server; if any errors occur, an exception is thrown.

Parameters

is	The input stream to send to the FTP server
remote_path	The name of the file on the server

Events:: EVENT_FTP_SEND_MESSAGE, EVENT_FTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_PACKET_SENT

Example:: ftp.put(new FileInputStream("/tmp/file-1.txt"), "file.txt");

Exceptions

FTP-RECEIVE-ERROR	Incomplete message received on control port
FTP-FILE-OPEN-ERROR	Could not open local file for reading
FTP-FILE-PUT-ERROR	Could not determine file size of local file (stat() failed)
FTP-PUT-ERROR	An error occurred while sending the file

Note: see FtpClient::connect() for additional exceptions that could be thrown when connections are implicitly established

See also: FtpClient::putData()

◆ put() [2/2]

nothing Qore::FtpClient::put	(	string	local_path,
		*string	remote_path
	)

Transfers a local file to the FTP server; if any errors occur, an exception is thrown.

Restrictions:: Qore::PO_NO_FILESYSTEM

Parameters

local_path	The path on the local system of the file to send
remote_path	If given, where to save the file on the server (otherwise the local path is used)

Events:: EVENT_FTP_SEND_MESSAGE, EVENT_FTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_PACKET_SENT

Example:: ftp.put("/tmp/file-1.txt", "file.txt");

Exceptions

FTP-RECEIVE-ERROR	Incomplete message received on control port
FTP-FILE-OPEN-ERROR	Could not open local file for reading
FTP-FILE-PUT-ERROR	Could not determine file size of local file (stat() failed)
FTP-PUT-ERROR	An error occurred while sending the file

Note: see FtpClient::connect() for additional exceptions that could be thrown when connections are implicitly established

See also: FtpClient::putData()

◆ putData() [1/2]

nothing Qore::FtpClient::putData	(	binary	data,
		string	remote_path
	)

Transfers binary data to the FTP server and saves it as a file on the remote machine; if any errors occur, an exception is thrown.

Parameters

data	The file data to save on the remote server
remote_path	The path on the remote server for the file to save the data under

Events:: EVENT_FTP_SEND_MESSAGE, EVENT_FTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_PACKET_SENT

Example:: ftp.putData(bin, "file.pdf");

Exceptions

FTP-RECEIVE-ERROR	Incomplete message received on control port
FTP-PUT-ERROR	An error occurred while sending the file

Note: see FtpClient::connect() for additional exceptions that could be thrown when connections are implicitly established

◆ putData() [2/2]

nothing Qore::FtpClient::putData	(	string	data,
		string	remote_path
	)

Transfers string data to the FTP server and saves it as a file on the remote machine; if any errors occur, an exception is thrown.

Parameters

data	The file data to save on the remote server
remote_path	The path on the remote server for the file to save the data under

Events:: EVENT_FTP_SEND_MESSAGE, EVENT_FTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_PACKET_SENT

Example:: ftp.putData(str, "file.txt");

Exceptions

FTP-RECEIVE-ERROR	Incomplete message received on control port
FTP-PUT-ERROR	An error occurred while sending the file

Note: see FtpClient::connect() for additional exceptions that could be thrown when connections are implicitly established

◆ pwd()

string Qore::FtpClient::pwd ( )

Returns the server-side current working directory.

Returns: the server-side current working directory

Events:: EVENT_FTP_SEND_MESSAGE, EVENT_FTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_PACKET_SENT

Example:: string str = ftp.pwd();

Exceptions

FTP-RECEIVE-ERROR	Incomplete message received on control port
FTP-PWD-ERROR	FTP server returned an error to the PWD command

Note: see FtpClient::connect() for additional exceptions that could be thrown when connections are implicitly established

◆ rename()

nothing Qore::FtpClient::rename	(	string	from,
		string	to
	)

Renames/moves a file or directory; if any errors occur, an exception is thrown.

Parameters

from	The original file path on the server to rename/move
to	The new path on the server

Events:: EVENT_FTP_SEND_MESSAGE, EVENT_FTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_PACKET_SENT

Example:: ftp.rename("file.txt", "file.txt.orig");

Exceptions

FTP-RECEIVE-ERROR	Incomplete message received on control port
FTP-RENAME-ERROR	FTP server returned an error to the `RNFR` or `RNTO` commands

Note: see FtpClient::connect() for additional exceptions that could be thrown when connections are implicitly established

◆ rmdir()

nothing Qore::FtpClient::rmdir ( string remote_path )

Removes a directory on the remote FTP server; if any errors occur, an exception is thrown.

Parameters

remote_path The path on the server to the directory to delete

Events:: EVENT_FTP_SEND_MESSAGE, EVENT_FTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_PACKET_SENT

Example:: ftp.rmdir("tmp");

Exceptions

FTP-RECEIVE-ERROR	Incomplete message received on control port
FTP-RMDIR-ERROR	FTP server returned an error to the `RMD` command

Note: see FtpClient::connect() for additional exceptions that could be thrown when connections are implicitly established

◆ sendControlMessage()

hash< FtpResponseInfo > Qore::FtpClient::sendControlMessage	(	string	cmd,
		string	arg
	)

Sends a message on the control connection with a reply on the control connection only.

Parameters

cmd	the FTP command to send
arg	the argument for the command

Returns: the response from the FTP server

Note: This method is for commands only on the control connection; no data connection is possible with this method

Since: Qore 0.9.4

◆ setControlEventQueue() [1/2]

nothing Qore::FtpClient::setControlEventQueue ( )

Clears any Queue object that may be set on the FtpClient object so that I/O events are no longer captured on the object on the control connection.

Example:: ftp.setControlEventQueue();

◆ setControlEventQueue() [2/2]

nothing Qore::FtpClient::setControlEventQueue	(	Qore::Thread::Queue	queue,
		auto	arg,
		*bool	with_data
	)

Sets a Queue object to receive FtpClient and Socket events on the control connection.

Example:: ftp.setControlEventQueue(queue);

Parameters

queue	a Queue object to receive FtpClient and Socket events on the control connection; note that the Queue passed cannot have any maximum size set or a QUEUE-ERROR will be thrown
arg	an argument that will be included in each event hash in the arg key
with_data	if True, then the actual raw data transferred / received is also included in the events

Exceptions

QUEUE-ERROR the Queue passed has a maximum size set

See also: event_handling for more information

Since: Qore 0.9.4 added the arg and with_data options

◆ setDataEventQueue() [1/2]

nothing Qore::FtpClient::setDataEventQueue ( )

Clears any Queue object that may be set on the FtpClient object so that I/O events are no longer captured on the object on the data connection.

Example:: ftp.setDataEventQueue();

◆ setDataEventQueue() [2/2]

nothing Qore::FtpClient::setDataEventQueue	(	Qore::Thread::Queue	queue,
		auto	arg,
		*bool	with_data
	)

Sets a Queue object to receive FtpClient and Socket events on the data connection.

Example:: ftp.setDataEventQueue(queue);

Parameters

queue	a Queue object to receive FtpClient and Socket events on the data connection; note that the Queue passed cannot have any maximum size set or a QUEUE-ERROR will be thrown
arg	an argument that will be included in each event hash in the arg key
with_data	if True, then the actual raw data transferred / received is also included in the events

Exceptions

QUEUE-ERROR the Queue passed has a maximum size set

See also: event_handling for more information

Since: Qore 0.9.4 added the arg and with_data options

◆ setEventQueue() [1/2]

nothing Qore::FtpClient::setEventQueue ( )

Clears any Queue object that may be set on the FtpClient object so that I/O events are no longer captured on the object on either the data or control connections.

Example:: ftp.setEventQueue();

◆ setEventQueue() [2/2]

nothing Qore::FtpClient::setEventQueue	(	Qore::Thread::Queue	queue,
		auto	arg,
		*bool	with_data
	)

Sets a Queue object to receive FtpClient and Socket events on both the data and control connections.

Example:: ftp.setEventQueue(queue);

Parameters

queue	a Queue object to receive FtpClient and Socket events on both the data and control connections; note that the Queue passed cannot have any maximum size set or a QUEUE-ERROR will be thrown
arg	an argument that will be included in each event hash in the arg key
with_data	if True, then the actual raw data transferred / received is also included in the events

Exceptions

QUEUE-ERROR the Queue passed has a maximum size set

See also: event_handling for more information

Since: Qore 0.9.4 added the arg and with_data options

◆ setHostName()

nothing Qore::FtpClient::setHostName ( string host )

Sets the hostname or address to use to connect to for the next connection.

Parameters

host	the hostname or address to use to connect to for the next connection

Example:: ftp.setHostName("example.com");

◆ setInsecure()

nothing Qore::FtpClient::setInsecure ( )

Make a non-encrypted connection to the server on the next connect.

Example:: ftp.setInsecure();

Exceptions

SET-INSECURE-ERROR this method cannot be called while the control connection is established

◆ setInsecureData()

nothing Qore::FtpClient::setInsecureData ( )

Make a non-encrypted data connection to the server on the next connect even if the control connection is secure.

Example:: ftp.setSecure();

ftp.setInsecureData();

Exceptions

SET-INSECUREDATA-ERROR this method cannot be called while the control connection is established

◆ setModeAuto()

nothing Qore::FtpClient::setModeAuto ( )

Sets the object to automatically try to negotiate the data connections in EPSV, PASV, and PORT modes, in that order.

Example:: ftp.setModeAuto();

◆ setModeEPSV()

nothing Qore::FtpClient::setModeEPSV ( )

Sets the object to only try to make data connections using EPSV (RFC-2428 extended passive) mode.

Example:: ftp.setModeEPSV();

◆ setModePASV()

nothing Qore::FtpClient::setModePASV ( )

Sets the object to only try to make data connections using PASV (RFC-959 passive) mode.

Example:: ftp.setModePASV();

◆ setModePORT()

nothing Qore::FtpClient::setModePORT ( )

Sets the object to only try to make data connections using PORT mode.

Example:: ftp.setModePORT();

◆ setNetworkFamily()

nothing Qore::FtpClient::setNetworkFamily ( int family )

Sets the network address family to use for new connections; use this method to restrict connections to IPv4 or IPv6 connections.

Parameters

family the network address family to use for new connections; see Network Address Family Constants for valid values; use Qore::AF_UNSPEC to automatically choose the family (the default)

Example:: ftp.setNetworkFamily(AF_INET);

Exceptions

FTPCLIENT-SETNETWORKFAMILY-ERROR invalid or unknown network family

Since: Qore 0.9.0

◆ setPassword()

nothing Qore::FtpClient::setPassword ( string pass )

Sets the password to use for the next connection.

Parameters

pass	the password to use for the next connection

Example:: ftp.setPassword("ftp");

◆ setPort()

nothing Qore::FtpClient::setPort ( int port )

Sets the control port value to use for the next connection (the FTP protocol default is 21)

Parameters

port	the control port value to use for the next connection (the FTP protocol default is 21); must be > 0 or an FTPCLIENT-SETPORT-PARAMETER-ERROR exception is raised

Example:: ftp.setPort(2021);

Exceptions

FTPCLIENT-SETPORT-PARAMETER-ERROR port <= 0 number passed as argument

◆ setSecure()

nothing Qore::FtpClient::setSecure ( bool secure = True )

Make an FTPS connection to the server on the next connect if the argument is True.

Parameters

secure Make an FTPS connection to the server on the next connect if the argument is True; make a cleartext connection if the argument is False

Example:: ftp.setSecure(True);

Exceptions

SET-SECURE-ERROR this method cannot be called while the control connection is established

◆ setTimeout()

Qore::FtpClient::setTimeout ( timeout timeout_ms )

sets the socket I/O timeout value in milliseconds

Parameters

timeout_ms the timeout value in milliseconds

Since: Qore 0.8.12.3

◆ setURL()

nothing Qore::FtpClient::setURL ( string url )

Sets the connection and login parameters based on the URL passed as an argument.

Only "ftp" and "ftps" protocols (schemes) are accepted; any other protocol (scheme) will cause an exception to be thrown.

Parameters

url	The URL to use for the next connection; the URL must contain at least a hostname

Example:: ftp.setURL("ftps://user:[email protected]:2021");

Exceptions

UNSUPPORTED-PROTOCOL	Only `"ftp"` and "ftps" are allowed as the protocol (scheme) in the URL
FTP-URL-ERROR	No hostname given in the URL

◆ setUserName()

nothing Qore::FtpClient::setUserName ( string user )

Sets the user name to use for the next connection.

Parameters

user	the user name to use for the next connection

Example:: ftp.setUserName("ftp");

◆ setWarningQueue()

nothing Qore::FtpClient::setWarningQueue	(	int	warning_ms,
		int	warning_bs,
		Queue	queue,
		auto	arg,
		timeout	min_ms = `1s`
	)

Sets a Queue object to receive socket warnings.

Example:: ftp.setWarningQueue(5000, 5000, queue, "socket-1");

Parameters

warning_ms	the threshold in milliseconds for individual socket actions (send, receive, connect), if exceeded, a socket warning is placed on the warning queue with the following keys: `"type"`: a string with the constant value `"SOCKET-OPERATION-WARNING"` `"operation"`: a string giving the operation that caused the warning (ex: `"connect"`) `"us"`: an integer giving the number of microseconds for the operation `"timeout"`: an integer giving the warning threshold in microseconds `"arg"`: if any `"arg"` argument is passed to the FtpClient::setWarningQueue() method, it will be included in the warning hash here
warning_bs	value in bytes per second; if any call has performance below this threshold, a socket warning is placed on the warning queue with the following keys: `"type"`: a string with the constant value `"SOCKET-THROUGHPUT-WARNING"` `"dir"`: either `"send"` or `"recv"` depending on the direction of the data flow `"bytes"`: the amount of bytes sent `"us"`: an integer giving the number of microseconds for the operation `"bytes_sec"`: a float giving the transfer speed in bytes per second `"threshold"`: an integer giving the warning threshold in bytes per second `"arg"`: if any `"arg"` argument is passed to the FtpClient::setWarningQueue() method, it will be included in the warning hash here
queue	the Queue object to receive warning events
arg	an optional argument to be placed in the `"arg"` key in each warning hash (could be used to identify the socket for example)
min_ms	the minimum transfer time with a resolution of milliseconds for a transfer to be eligible for triggering a warning; transfers that take less than this period of time are not eligible for raising a warning

Exceptions

QUEUE-ERROR	the Queue passed has a maximum size set
SOCKET-SETWARNINGQUEUE-ERROR	at least one of warning_ms and warning_bs must be > 0

See also: FtpClient::clearWarningQueue()

Since

Qore 0.8.9
Qore 0.8.12 the minimum threshold for a warning is a transfer of at least 1024 bytes, smaller transfers will not result in a warning

◆ verifyPeerCertificate()

*string Qore::FtpClient::verifyPeerCertificate ( )

Returns a string code giving the result of verifying the remote certificate or NOTHING if an encrypted connection is not established.

Returns: A string code giving the result of verifying the peer's certificate or NOTHING if a secure connection has not been established. The possible values are found in the keys of the X509_VerificationReasons hash constant. This hash can also be used to generate a textual description of the verification result.

Code Flags:: CONSTANT

Example:: if (ftp.isSecure() && (*string str = ftp.verifyPeerCertificate())) {

printf("certificate: %s: %s\n", str, X509_VerificationReasons{str});

Public Member Methods

Detailed Description

FtpClient Timeouts

Member Function Documentation

◆ clearStats()

◆ clearWarningQueue()

◆ connect()

◆ constructor() [1/2]

◆ constructor() [2/2]

◆ copy()

◆ cwd()

◆ del()

◆ destructor()

◆ disconnect()

◆ get() [1/2]

◆ get() [2/2]

◆ getAsBinary()

◆ getAsString()

◆ getControlPeerInfo()

◆ getControlSocketInfo()

◆ getDataPeerInfo()

◆ getDataSocketInfo()

◆ getHostName()

◆ getMode()

◆ getNetworkFamily()

◆ getPassword()

◆ getPort()

◆ getSSLCipherName()

◆ getSSLCipherVersion()

◆ getTimeout()

◆ getURL()

◆ getUsageInfo()

◆ getUserName()

◆ isDataSecure()

◆ isSecure()

◆ list() [1/2]

◆ list() [2/2]

◆ mkdir()

◆ nlst() [1/2]

◆ nlst() [2/2]

◆ put() [1/2]

◆ put() [2/2]

◆ putData() [1/2]

◆ putData() [2/2]

◆ pwd()

◆ rename()

◆ rmdir()

◆ sendControlMessage()

◆ setControlEventQueue() [1/2]

◆ setControlEventQueue() [2/2]

◆ setDataEventQueue() [1/2]

◆ setDataEventQueue() [2/2]

◆ setEventQueue() [1/2]

◆ setEventQueue() [2/2]

◆ setHostName()

◆ setInsecure()

◆ setInsecureData()

◆ setModeAuto()

◆ setModeEPSV()

◆ setModePASV()

◆ setModePORT()

◆ setNetworkFamily()

◆ setPassword()

◆ setPort()

◆ setSecure()

◆ setTimeout()

◆ setURL()

◆ setUserName()

◆ setWarningQueue()

◆ verifyPeerCertificate()