All Classes Namespaces Functions Variables Groups Pages
Qore::FtpClient Class Reference

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

## Public Member Functions

| 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...
binary | getAsBinary (string remote_path)
| Gets a file from the FTP server and returns it as a binary. More...
string | getAsString (string remote_path)
| Gets a file from the FTP server and returns it as a string. 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...
*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...
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 | 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...
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)
| 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)
| 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)
| 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 | 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...
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, any 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` | `"qore@nohost.com"`
`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

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

## Member Function Documentation

Qore::FtpClient::clearStats | ( |  | ) |

Clears performance statistics.

Example:
  ftp.clearStats();

Since
  Qore 0.8.9

See Also
  FtpClient::getUsageInfo()

nothing Qore::FtpClient::clearWarningQueue | ( |  | ) |

Removes any warning Queue object from the Socket.

Example:
  ftp.clearWarningQueue();

See Also
  FtpClient::setWarningQueue()

Since
  Qore 0.8.9

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

Qore::FtpClient::constructor | ( |  | ) |

Creates an empty FtpClient object.

Example:
  FtpClient ftp();

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:pass@example.com: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

Qore::FtpClient::copy | ( |  | ) |

Throws an exception to prevent copying of objects this class.

Exceptions

  FTPCLIENT-COPY-ERROR | FtpClient objects cannot be copied

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

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

Qore::FtpClient::destructor | ( |  | ) |

Disconnects any remote connection and destroys the object.

Events:
  EVENT_CHANNEL_CLOSED, EVENT_DELETED

Example:
  delete ftp;

nothing Qore::FtpClient::disconnect | ( |  | ) |

Disconnects from an FTP server.

Events:
  EVENT_CHANNEL_CLOSED

Example:
  delete ftp;

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

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

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

string Qore::FtpClient::getAsString | ( | string | remote_path | ) |

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

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

*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();

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

*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();

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();

*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 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());

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();

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()

*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();

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();

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();

*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()

*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/*.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/*.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()

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

*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()

*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/*.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/*.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()

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()

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

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

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

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

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

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();

nothing Qore::FtpClient::setControlEventQueue | ( | Qore::Thread::Queue | queue | ) |

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

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

Example:
  ftp.setControlEventQueue(queue);

Exceptions

  QUEUE-ERROR | the Queue passed has a maximum size set

See Also
  event_handling for more information

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();

nothing Qore::FtpClient::setDataEventQueue | ( | Qore::Thread::Queue | queue | ) |

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

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

Example:
  ftp.setDataEventQueue(queue);

Exceptions

  QUEUE-ERROR | the Queue passed has a maximum size set

See Also
  event_handling for more information

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();

nothing Qore::FtpClient::setEventQueue | ( | Qore::Thread::Queue | queue | ) |

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

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

Example:
  ftp.setEventQueue(queue);

Exceptions

  QUEUE-ERROR | the Queue passed has a maximum size set

See Also
  event_handling for more information

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");

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

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

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();

nothing Qore::FtpClient::setModeEPSV | ( |  | ) |

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

Example:
  ftp.setModeEPSV();

nothing Qore::FtpClient::setModePASV | ( |  | ) |

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

Example:
  ftp.setModePASV();

nothing Qore::FtpClient::setModePORT | ( |  | ) |

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

Example:
  ftp.setModePORT();

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");

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

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

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:pass@example.com: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

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");

nothing Qore::FtpClient::setWarningQueue | ( | int | warning_ms,
|  | int | warning_bs,
|  | Queue | queue,
|  | any | 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

*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});