Qore Programming Language Reference Manual  1.7.0
Qore::FtpClient Class Reference

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

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< FtpResponseInfosendControlMessage (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-ERRORInvalid response received from FTP server
SOCKET-CONNECT-ERRORCannot establish socket connection to FTP server
FTP-CONNECT-ERRORno hostname set, FTP server reported an error, etc
FTP-LOGIN-ERRORLogin 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
urlThe URL of the server to connect to; must have at least a hostname
Example:
FtpClient ftp("ftp://user:[email protected]:2021");
Exceptions
UNSUPPORTED-PROTOCOLOnly "ftp" or "ftps" are allowed as the protocol in the URL
FTP-URL-ERRORNo hostname given in the URL

◆ copy()

Qore::FtpClient::copy ( )

Throws an exception to prevent copying of objects this class.

Exceptions
FTPCLIENT-COPY-ERRORFtpClient 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-ERRORIncomplete message received on control port
FTP-CWD-ERRORFTP 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_pathThe 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-ERRORIncomplete message received on control port
FTP-DELETE-ERRORFTP 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:
delete ftp;

◆ 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_pathThe path on the server to the file to get
local_pathThe 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-ERRORIncomplete message received on control port
FTP-FILE-OPEN-ERRORCould not create the local file
FTP-GET-ERRORThere 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_pathThe path on the server to the file to get
osThe 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-ERRORIncomplete message received on control port
FTP-FILE-OPEN-ERRORCould not create the local file
FTP-GET-ERRORThere 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_pathThe 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-ERRORIncomplete message received on control port
FTP-FILE-OPEN-ERRORCould not create the local file
FTP-GET-ERRORThere 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_pathThe path on the server to the file to get
encodingthe 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-ERRORIncomplete message received on control port
FTP-FILE-OPEN-ERRORCould not create the local file
FTP-GET-ERRORThere 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_lookupdo 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-OPENThe socket is not open
SOCKET-GETPEERINFO-ERRORerror 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_lookupdo 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-OPENThe socket is not open
SOCKET-GETSOCKETINFO-ERRORerror 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_lookupdo 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-OPENThe socket is not open
SOCKET-GETPEERINFO-ERRORerror 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_lookupdo 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-OPENThe socket is not open
SOCKET-GETSOCKETINFO-ERRORerror 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());
string printf(string fmt,...)
Outputs the string passed to standard output, using the first argument as a format string; does not e...

◆ 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-ERRORIncomplete message received on control port
FTP-LIST-ERRORFTP 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
pathThe 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-ERRORIncomplete message received on control port
FTP-LIST-ERRORFTP 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_pathThe 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-ERRORIncomplete message received on control port
FTP-MKDIR-ERRORFTP 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-ERRORIncomplete message received on control port
FTP-LIST-ERRORFTP 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
pathThe 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-ERRORIncomplete message received on control port
FTP-LIST-ERRORFTP 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
isThe input stream to send to the FTP server
remote_pathThe 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-ERRORIncomplete message received on control port
FTP-FILE-OPEN-ERRORCould not open local file for reading
FTP-FILE-PUT-ERRORCould not determine file size of local file (stat() failed)
FTP-PUT-ERRORAn 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_pathThe path on the local system of the file to send
remote_pathIf 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-ERRORIncomplete message received on control port
FTP-FILE-OPEN-ERRORCould not open local file for reading
FTP-FILE-PUT-ERRORCould not determine file size of local file (stat() failed)
FTP-PUT-ERRORAn 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
dataThe file data to save on the remote server
remote_pathThe 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-ERRORIncomplete message received on control port
FTP-PUT-ERRORAn 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
dataThe file data to save on the remote server
remote_pathThe 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-ERRORIncomplete message received on control port
FTP-PUT-ERRORAn 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-ERRORIncomplete message received on control port
FTP-PWD-ERRORFTP 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
fromThe original file path on the server to rename/move
toThe 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-ERRORIncomplete message received on control port
FTP-RENAME-ERRORFTP 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_pathThe 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-ERRORIncomplete message received on control port
FTP-RMDIR-ERRORFTP 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
cmdthe FTP command to send
argthe 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
queuea 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
argan argument that will be included in each event hash in the arg key
with_dataif True, then the actual raw data transferred / received is also included in the events
Exceptions
QUEUE-ERRORthe 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
queuea 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
argan argument that will be included in each event hash in the arg key
with_dataif True, then the actual raw data transferred / received is also included in the events
Exceptions
QUEUE-ERRORthe 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
queuea 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
argan argument that will be included in each event hash in the arg key
with_dataif True, then the actual raw data transferred / received is also included in the events
Exceptions
QUEUE-ERRORthe 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
hostthe 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-ERRORthis 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-ERRORthis 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
familythe 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-ERRORinvalid 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
passthe 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
portthe 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-ERRORport <= 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
secureMake 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-ERRORthis 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_msthe 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
urlThe 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-PROTOCOLOnly "ftp" and "ftps" are allowed as the protocol (scheme) in the URL
FTP-URL-ERRORNo hostname given in the URL

◆ setUserName()

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

Sets the user name to use for the next connection.

Parameters
userthe 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_msthe 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_bsvalue 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
queuethe Queue object to receive warning events
argan optional argument to be placed in the "arg" key in each warning hash (could be used to identify the socket for example)
min_msthe 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-ERRORthe Queue passed has a maximum size set
SOCKET-SETWARNINGQUEUE-ERRORat 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});