4.7. FtpClient Class

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

The FtpClient class allows Qore programs to communicate with FTP servers. 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.

Table 4.238. 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, the FtpClient::connect() method must be called to connect and login to the FTP server.

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.

When a data connection is required, by default the following modes are tried in series: EPSV (Extended Passive Mode), PASV (Passive Mode), and 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 Event Handling for more information.

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

Table 4.239. 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.


Table 4.240. FtpClient Method Overview

Method

Except?

Description

FtpClient::constructor()

Y

Creates object and optionally initializes URL

FtpClient::destructor()

N

Destroys the object.

FtpClient::copy()

Y

Throws an exception to prevent copying of objects this class.

FtpClient::connect()

Y

Connects and logs in to FTP server

FtpClient::disconnect()

N

Disconnects from the FTP server.

FtpClient::setSecure()

Y

Make an FTPS connection to the server on the next connect.

FtpClient::setInsecure()

Y

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

FtpClient::setInsecureData()

Y

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

FtpClient::isSecure()

N

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

FtpClient::isDataSecure()

N

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

FtpClient::getSSLCipherName()

N

Returns the name of the cipher for an encrypted connection.

FtpClient::getSSLCipherVersion()

N

Returns the version string of the cipher for encrypted connections.

FtpClient::verifyPeerCertificate()

N

Returns a string code giving the result of verifying the remote certificate.

FtpClient::setModeAuto()

N

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

FtpClient::setModeEPSV()

N

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

FtpClient::setModePASV()

N

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

FtpClient::setModePORT()

N

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

FtpClient::list()

Y

Gets a list of files from the FTP server in the server's long format.

FtpClient::nlst()

Y

Gets a list of file names from the FTP server.

FtpClient::pwd()

Y

Returns the server-side current working directory.

FtpClient::cwd()

Y

Changes the current working directory on the server.

FtpClient::get()

Y

Gets a file from the FTP server and stores it on the local filesystem.

FtpClient::getAsBinary()

Y

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

FtpClient::getAsString()

Y

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

FtpClient::put()

Y

Transfers a file to the FTP server.

FtpClient::del()

Y

Deletes a file from the FTP server

FtpClient::setUserName()

N

Sets the user name to use

FtpClient::setPassword()

N

Sets the password to use

FtpClient::setHostName()

N

Sets the hostname to connect to

FtpClient::setPort()

N

Sets the port to connect to

FtpClient::setURL()

Y

Sets the URL

FtpClient::getUserName()

N

Gets the current user name

FtpClient::getPassword()

N

Gets the current password

FtpClient::getHostName()

N

Gets the current hostname

FtpClient::getPort()

N

Gets the current port

FtpClient::getURL()

N

Gets the current FTP URL

FtpClient::setEventQueue()

N

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

FtpClient::setDataEventQueue()

N

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

FtpClient::setControlEventQueue()

N

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


4.7.1. FtpClient::constructor()

Synopsis

Creates the FtpClient object. It accepts one optional 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 is "ftps", the client will attempt to establish a secure connection to the server according to RFC-4217 when the first connection is established.

A call to FtpClient::connect() must be made explicitly before any actions requiring a connection to the server are made; connections are not made implicitly by this class.

Usage
new FtpClient([string_value])
Example
$ftp = new FtpClient("ftp://user:pass@hostname");

Table 4.241. Arguments for FtpClient::constructor()

Argument

Type

Description

string_value

String

The entire command line to process.


Table 4.242. Return Values for FtpClient::constructor()

Return Type

Description

Object

The FtpClient object created


Table 4.243. Exceptions Thrown by FtpClient::constructor()

err

desc

UNSUPPORTED-PROTOCOL

Only "ftp" or "ftps" are allowed as the protocol in the URL.

FTP-URL-ERROR

No hostname given in the URL.


4.7.2. FtpClient::destructor()

Synopsis

Destroys the object.

Usage
delete lvalue
Example
delete $ftp;
Events
EVENT_CHANNEL_CLOSED, EVENT_DELETED

4.7.3. FtpClient::copy()

Synopsis

Throws an exception; objects of this class cannot be copied.

Table 4.244. Arguments for FtpClient::copy()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.245. Return Values for FtpClient::copy()

Return Type

Description

n/a

This method returns no value because it throws an exception.


Table 4.246. Exceptions Thrown by FtpClient::copy()

err

desc

FTPCLIENT-COPY-ERROR

Objects of this class cannot be copied.


4.7.4. FtpClient::connect()

Synopsis

Connects to the FTP server and attempts a login.

Usage
FtpClient::connect(optional:string_value)
Example
$ftp.connect(); # connects to the URL set in the constructor
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

Table 4.247. Arguments for FtpClient::connect()

Argument

Type

Description

string_value

String

The URL of the FTP connection.


Table 4.248. Return Values for FtpClient::connect()

Return Type

Description

Integer

Returns 0 for success, -1 for error.


Table 4.249. Exceptions Thrown by FtpClient::connect()

err

desc

FTP-RESPONSE-ERROR

Invalid response received from FTP server.

FTP-CONNECT-ERROR

Cannot establish connection on data port, no hostname set, FTP server reported an error, etc.

FTP-LOGIN-ERROR

Login denied by FTP server.


4.7.5. FtpClient::disconnect()

Synopsis

Disconnects from an FTP server.

Usage
FtpClient::disconnect()
Example
$ftp.disconnect();
Events
EVENT_CHANNEL_CLOSED

Table 4.250. Arguments for FtpClient::disconnect()

Argument

Type

Description

n/a

n/a

No arguments are accepted by this method


Table 4.251. Return Values for FtpClient::disconnect()

Return Type

Description

Integer

Always returns 0 for success, on errors an exception is thrown.


4.7.6. FtpClient::setSecure()

Synopsis

Make an FTPS connection to the server on the next connect.

Usage
FtpClient::setSecure()
Example
$ftp.setSecure();

Table 4.252. Arguments for FtpClient::setSecure()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.253. Return Values for FtpClient::setSecure()

Return Type

Description

n/a

This method returns no value


Table 4.254. Exceptions thrown by FtpClient::setSecure()

err

desc

SET-SECURE-ERROR

cannot be called while a control connection has already been established.


4.7.7. FtpClient::setInsecure()

Synopsis

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

Usage
FtpClient::setInsecure()
Example
$ftp.setInsecure();

Table 4.255. Arguments for FtpClient::setInsecure()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.256. Return Values for FtpClient::setInsecure()

Return Type

Description

n/a

This method returns no value


Table 4.257. Exceptions thrown by FtpClient::setInsecure()

err

desc

SET-INSECURE-ERROR

cannot be called while a control connection has already been established.


4.7.8. FtpClient::setInsecureData()

Synopsis

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

Usage
FtpClient::setInsecureData()
Example
$ftp.setInsecureData();

Table 4.258. Arguments for FtpClient::setInsecureData()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.259. Return Values for FtpClient::setInsecureData()

Return Type

Description

n/a

This method returns no value


Table 4.260. Exceptions thrown by FtpClient::setInsecureData()

err

desc

SET-INSECUREDATA-ERROR

cannot be called while a control connection has already been established.


4.7.9. FtpClient::isSecure()

Synopsis

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

Usage
FtpClient::isSecure()
Example
$bool = $ftp.isSecure();

Table 4.261. Arguments for FtpClient::isSecure()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.262. Return Values for FtpClient::isSecure()

Return Type

Description

Boolean

True if the control connection is encrypted.


4.7.10. FtpClient::isDataSecure()

Synopsis

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

Usage
FtpClient::isDataSecure()
Example
$bool = $ftp.isDataSecure();

Table 4.263. Arguments for FtpClient::isDataSecure()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.264. Return Values for FtpClient::isDataSecure()

Return Type

Description

Boolean

True if data connections are encrypted.


4.7.11. FtpClient::getSSLCipherName()

Synopsis

Returns the name of the cipher for an encrypted connection.

Usage
FtpClient::getSSLCipherName()
Example
$str = $ftp.getSSLCipherName();

Table 4.265. Arguments for FtpClient::getSSLCipherName()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.266. Return Values for FtpClient::getSSLCipherName()

Return Type

Description

String

The name of the cipher for an encrypted connection.


4.7.12. FtpClient::getSSLCipherVersion()

Synopsis

Returns the version string of the cipher for encrypted connections.

Usage
FtpClient::getSSLCipherVersion()
Example
$str = $ftp.getSSLCipherVersion();

Table 4.267. Arguments for FtpClient::getSSLCipherVersion()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.268. Return Values for FtpClient::getSSLCipherVersion()

Return Type

Description

String

The version string of the cipher for encrypted connections.


4.7.13. FtpClient::verifyPeerCertificate()

Synopsis

Returns a string code giving the result of verifying the remote certificate for secure (FTPS) connections. Return value are the keys described in the X509_VerificationReasons hash constant. This hash can also be used to generate a textual description of the verification result.

Usage
FtpClient::verifyPeerCertificate()
Example
$str = $ftp.verifyPeerCertificate();

Table 4.269. Arguments for FtpClient::verifyPeerCertificate()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.270. Return Values for FtpClient::verifyPeerCertificate()

Return Type

Description

String

A string code giving the result of verifying the peer's certificate. No value is returned if no secure connection has been established.


4.7.14. FtpClient::setModeAuto()

Synopsis

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

Usage
FtpClient::setModeAuto()
Example
$ftp.setModeAuto();

Table 4.271. Arguments for FtpClient::setModeAuto()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.272. Return Values for FtpClient::setModeAuto()

Return Type

Description

n/a

This method returns no value


4.7.15. FtpClient::setModeEPSV()

Synopsis

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

Usage
FtpClient::setModeEPSV()
Example
$ftp.setModeEPSV();

Table 4.273. Arguments for FtpClient::setModeEPSV()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.274. Return Values for FtpClient::setModeEPSV()

Return Type

Description

n/a

This method returns no value


4.7.16. FtpClient::setModePASV()

Synopsis

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

Usage
FtpClient::setModePASV()
Example
$ftp.setModePASV();

Table 4.275. Arguments for FtpClient::setModePASV()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.276. Return Values for FtpClient::setModePASV()

Return Type

Description

n/a

This method returns no value


4.7.17. FtpClient::setModePORT()

Synopsis

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

Usage
FtpClient::setModePORT()
Example
$ftp.setModePORT();

Table 4.277. Arguments for FtpClient::setModePORT()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.278. Return Values for FtpClient::setModePORT()

Return Type

Description

n/a

This method returns no value


4.7.18. FtpClient::list()

Synopsis

Gets a list of files from the FTP server in the server's long format in the current working directory.

Usage
FtpClient::list()
Example
$list = $ftp.list();
Events
EVENT_FTP_SEND_MESSAGE, EVENT_FTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_PACKET_SENT

Table 4.279. Arguments for FtpClient::list()

Argument

Type

Description

n/a

n/a

This method does not take any arguments.


Table 4.280. Return Values for FtpClient::list()

Return Type

Description

String

The string returned by the server without any translations or processing.


Table 4.281. Exceptions Thrown by FtpClient::list()

err

desc

FTP-RECEIVE-ERROR

Incomplete message received on control port.

FTP-NOT-CONNECTED

Not connected to FTP server (call FtpClient::connect() first).

FTP-LIST-ERROR

FTP server returned an error in response to the LIST command.


4.7.19. FtpClient::nlst()

Synopsis

Gets a list of file names in the current working directory from the FTP server.

Usage
FtpClient::nlst()
Example
$str = $ftp.nlst();
Events
EVENT_FTP_SEND_MESSAGE, EVENT_FTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_PACKET_SENT

Table 4.282. Arguments for FtpClient::nlst()

Argument

Type

Description

n/a

n/a

This method does not take any arguments.


Table 4.283. Return Values for FtpClient::nlst()

Return Type

Description

String

The string returned by the server without any translations or processing.


Table 4.284. Exceptions Thrown by FtpClient::nlst()

err

desc

FTP-RECEIVE-ERROR

Incomplete message received on control port.

FTP-NOT-CONNECTED

Not connected to FTP server (call FtpClient::connect() first).

FTP-LIST-ERROR

FTP server returned an error in response to the NSLT command.


4.7.20. FtpClient::pwd()

Synopsis

Returns the server-side current working directory.

Usage
FtpClient::pwd()
Example
$str = $ftp.pwd();
Events
EVENT_FTP_SEND_MESSAGE, EVENT_FTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_PACKET_SENT

Table 4.285. Arguments for FtpClient::pwd()

Argument

Type

Description

n/a

n/a

This method does not take any arguments.


Table 4.286. Return Values for FtpClient::pwd()

Return Type

Description

String

The server-side current working directory.


Table 4.287. Exceptions Thrown by FtpClient::pwd()

err

desc

FTP-RECEIVE-ERROR

Incomplete message received on control port.

FTP-NOT-CONNECTED

Not connected to FTP server (call FtpClient::connect() first).

FTP-PWD-ERROR

FTP server returned an error to the PWD command.


4.7.21. FtpClient::cwd()

Synopsis

Changes the current working directory on the server.

Usage
FtpClient::cwd(path)
Example
$ftp.cwd("/pub/gnu");
Events
EVENT_FTP_SEND_MESSAGE, EVENT_FTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_PACKET_SENT

Table 4.288. Arguments for FtpClient::cwd()

Argument

Type

Description

path

String

The directory to change to.


Table 4.289. Return Values for FtpClient::cwd()

Return Type

Description

Integer

Always returns 0, on errors exceptions are raised.


Table 4.290. Exceptions Thrown by FtpClient::cwd()

err

desc

FTP-RECEIVE-ERROR

Incomplete message received on control port.

FTP-NOT-CONNECTED

Not connected to FTP server (call FtpClient::connect() first).

FTP-CWD-ERROR

FTP server returned an error to the CWD command.

FTPCLIENT-CWD-PARAMETER-ERROR

Missing argument to the method.


4.7.22. FtpClient::get()

Synopsis

Gets a file from the FTP server and stores it on the local system.

Usage
FtpClient::get(server_path, [local_path])
Example
$ftp.get("file.txt", "/tmp/file-1.txt");
Events
EVENT_FTP_SEND_MESSAGE, EVENT_FTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_PACKET_SENT

Table 4.291. Arguments for FtpClient::get()

Argument

Type

Description

server_path

String

The path on the server to the file to get.

[local_path]

String

If given, where to save the local file.


Table 4.292. Return Values for FtpClient::get()

Return Type

Description

Integer

Always returns 0, on errors exceptions are raised.


Table 4.293. Exceptions Thrown by FtpClient::get()

err

desc

FTP-RECEIVE-ERROR

Incomplete message received on control port.

FTP-NOT-CONNECTED

Not connected to FTP server (call FtpClient::connect() first).

FTP-FILE-OPEN-ERROR

Could not create the local file.

FTP-GET-ERROR

There was an error retrieving the file.

FTPCLIENT-GET-PARAMETER-ERROR

Missing argument to the method.


4.7.23. FtpClient::getAsBinary()

Synopsis

Gets a file from the FTP server and returns the file's contents as a binary value. For a similar function returning the file's contents as a string, see FtpClient::getAsString(); for a function that will get a remote file and save it on the local filesystem, see FtpClient::get().

Usage
FtpClient::getAsBinary(server_path)
Example
my $b = $ftp.getAsBinary("file.bin");
Events
EVENT_FTP_SEND_MESSAGE, EVENT_FTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_PACKET_SENT

Table 4.294. Arguments for FtpClient::getAsBinary()

Argument

Type

Description

server_path

String

The path on the server to the file to get.


Table 4.295. Return Values for FtpClient::getAsBinary()

Return Type

Description

Binary

The file retrieved; if any errors occur an exception is raised.


Table 4.296. Exceptions Thrown by FtpClient::getAsBinary()

err

desc

FTP-RECEIVE-ERROR

Incomplete message received on control port.

FTP-NOT-CONNECTED

Not connected to FTP server (call FtpClient::connect() first).

FTP-FILE-OPEN-ERROR

Could not create the local file.

FTP-GET-ERROR

There was an error retrieving the file.

FTPCLIENT-GET-PARAMETER-ERROR

Missing argument to the method.


4.7.24. FtpClient::getAsString()

Synopsis

Gets a file from the FTP server and returns the file's contents as a string. For a similar function returning the file's contents as a binary, see FtpClient::getAsBinary(); for a function that will get a remote file and save it on the local filesystem, see FtpClient::get().

Usage
FtpClient::getAsString(server_path)
Example
my $str = $ftp.getAsString("file.txt");
Events
EVENT_FTP_SEND_MESSAGE, EVENT_FTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_PACKET_SENT

Table 4.297. Arguments for FtpClient::getAsString()

Argument

Type

Description

server_path

String

The path on the server to the file to get.


Table 4.298. Return Values for FtpClient::getAsString()

Return Type

Description

String

The file retrieved; if any errors occur an exception is raised.


Table 4.299. Exceptions Thrown by FtpClient::getAsString()

err

desc

FTP-RECEIVE-ERROR

Incomplete message received on control port.

FTP-NOT-CONNECTED

Not connected to FTP server (call FtpClient::connect() first).

FTP-FILE-OPEN-ERROR

Could not create the local file.

FTP-GET-ERROR

There was an error retrieving the file.

FTPCLIENT-GET-PARAMETER-ERROR

Missing argument to the method.


4.7.25. FtpClient::put()

Synopsis

Transfers a file to the FTP server.

Usage
FtpClient::put(local_path, [server_path])
Example
$ftp.put("/tmp/file-1.txt", "file.txt");
Events
EVENT_FTP_SEND_MESSAGE, EVENT_FTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_PACKET_SENT

Table 4.300. Arguments for FtpClient::put()

Argument

Type

Description

local_path

String

The path on the local system of the file to send.

[server_path]

String

If given, where to save the file on the server.


Table 4.301. Return Values for FtpClient::put()

Return Type

Description

Integer

Always returns 0, on errors exceptions are raised.


Table 4.302. Exceptions Thrown by FtpClient::put()

err

desc

FTP-RECEIVE-ERROR

Incomplete message received on control port.

FTP-NOT-CONNECTED

Not connected to FTP server (call FtpClient::connect() first).

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.

FTPCLIENT-PUT-PARAMETER-ERROR

Missing argument to the method.


4.7.26. FtpClient::del()

Synopsis

Deletes a file on the FTP server.

Usage
FtpClient::del(server_path)
Example
$ftp.del("file-2.txt");
Events
EVENT_FTP_SEND_MESSAGE, EVENT_FTP_MESSAGE_RECEIVED, EVENT_PACKET_READ, EVENT_PACKET_SENT

Table 4.303. Arguments for FtpClient::del()

Argument

Type

Description

server_path

String

The path on the server to the file to delete.


Table 4.304. Return Values for FtpClient::del()

Return Type

Description

Integer

Always returns 0, on errors exceptions are raised.


Table 4.305. Exceptions Thrown by FtpClient::del()

err

desc

FTP-RECEIVE-ERROR

Incomplete message received on control port.

FTP-NOT-CONNECTED

Not connected to FTP server (call FtpClient::connect() first).

FTP-DELETE-ERROR

FTP server returned an error to the DELE command.

FTPCLIENT-DEL-PARAMETER-ERROR

Missing argument to the method.


4.7.27. FtpClient::setUserName()

Synopsis

Sets the username for logging in to the FTP server.

Usage
FtpClient::setUserName(string)
Example
$ftp.setUserName("ftp");

Table 4.306. Arguments for FtpClient::setUserName()

Argument

Type

Description

string

String

The username to use when logging in to the FTP server.


Table 4.307. Return Values for FtpClient::setUserName()

Return Type

Description

n/a

This method does not return any value.


Table 4.308. Exceptions Thrown by FtpClient::setUserName()

err

desc

FTPCLIENT-SETUSERNAME-PARAMETER-ERROR

Missing argument to the method.


4.7.28. FtpClient::setPassword()

Synopsis

Sets the login password for the FTP server to connect to.

Usage
FtpClient::setPassword(string)
Example
$ftp.setPassword("ftp");

Table 4.309. Arguments for FtpClient::setPassword()

Argument

Type

Description

string

String

The password to use when logging in to the FTP server.


Table 4.310. Return Values for FtpClient::setPassword()

Return Type

Description

n/a

This method does not return any value.


Table 4.311. Exceptions Thrown by FtpClient::setPassword()

err

desc

FTPCLIENT-SETPASSWORD-PARAMETER-ERROR

Missing argument to the method.


4.7.29. FtpClient::setHostName()

Synopsis

Sets the hostname value for the FTP server to connect to.

Usage
FtpClient::setHostName(string)
Example
$ftp.setHostName("hostname");

Table 4.312. Arguments for FtpClient::setHostName()

Argument

Type

Description

string

String

The hostname to use when connecting to the FTP server.


Table 4.313. Return Values for FtpClient::setHostName()

Return Type

Description

n/a

This method does not return any value.


Table 4.314. Exceptions Thrown by FtpClient::setHostName()

err

desc

FTPCLIENT-SETHOSTNAME-PARAMETER-ERROR

Missing argument to the method.


4.7.30. FtpClient::setPort()

Synopsis

Sets the control port value (default is 21).

Usage
FtpClient::setPort(integer)
Example
$ftp.setPort(21);

Table 4.315. Arguments for FtpClient::setPort()

Argument

Type

Description

integer

Integer

The port to use when connecting to the FTP server.


Table 4.316. Return Values for FtpClient::setPort()

Return Type

Description

n/a

This method does not return any value.


Table 4.317. Exceptions Thrown by FtpClient::setPort()

err

desc

FTPCLIENT-SETPORT-PARAMETER-ERROR

Missing argument to the method.


4.7.31. FtpClient::setURL()

Synopsis

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

Usage
FtpClient::setURL(string)
Example
$ftp.setURL("ftps://user:pass@host");

Table 4.318. Arguments for FtpClient::setURL()

Argument

Type

Description

string

String

The URL to use to set connection and login parameters for the FTP server.


Table 4.319. Return Values for FtpClient::setURL()

Return Type

Description

n/a

This method does not return any value.


Table 4.320. Exceptions Thrown by FtpClient::setURL()

err

desc

UNSUPPORTED-PROTOCOL

Only "ftp" is allowed as the protocol in the URL.

FTP-URL-ERROR

No hostname given in the URL.

FTPCLIENT-SETURL-PARAMETER-ERROR

Missing argument to the method.


4.7.32. FtpClient::getUserName()

Synopsis

Retrieves the current username.

Usage
FtpClient::getUserName()
Example
$user = $ftp.getUserName();

Table 4.321. Arguments for FtpClient::getUserName()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.322. Return Values for FtpClient::getUserName()

Return Type

Description

String

The current username value.


4.7.33. FtpClient::getPassword()

Synopsis

Retrieves the current login password value for this object.

Usage
FtpClient::getPassword()
Example
$pass = $ftp.getPassword();

Table 4.323. Arguments for FtpClient::getPassword()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.324. Return Values for FtpClient::getPassword()

Return Type

Description

String

The current password value.


4.7.34. FtpClient::getHostName()

Synopsis

Retrieves the current hostname value for this object.

Usage
FtpClient::getHostName()
Example
$host = $ftp.getHostName();

Table 4.325. Arguments for FtpClient::getHostName()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.326. Return Values for FtpClient::getHostName()

Return Type

Description

String

The current hostname value.


4.7.35. FtpClient::getPort()

Synopsis

Retrieves the current connection port value for this object.

Usage
FtpClient::getPort()
Example
$port = $ftp.getPort();

Table 4.327. Arguments for FtpClient::getPort()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.328. Return Values for FtpClient::getPort()

Return Type

Description

Integer

The current connection port value.


4.7.36. FtpClient::getURL()

Synopsis

Retrieves the current connection URL string for this object.

Usage
FtpClient::getURL()
Example
$url = $ftp.getURL();

Table 4.329. Arguments for FtpClient::getURL()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.330. Return Values for FtpClient::getURL()

Return Type

Description

String

The current URL value.


4.7.37. FtpClient::setEventQueue()

Synopsis

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

To remove the event queue and stop monitoring socket events, pass NOTHING to the method. See Event Handling for more information.

To control monitoring of network events on just the data connection or just the control connection, use FtpClient::setDataEventQueue or FtpClient::setControlEventQueue respectively

Usage
FtpClient::setEventQueue([queue])
Example
$ftp.setEventQueue($queue);

Table 4.331. Arguments for FtpClient::setEventQueue()

Argument

Type

Description

[queue]

Queue

To set the event queue, pass a Queue object; to clear the event queue, pass no argument to the function.


Table 4.332. Return Values for FtpClient::setEventQueue()

Return Type

Description

n/a

This method does not return any value.


4.7.38. FtpClient::setDataEventQueue()

Synopsis

Sets a Queue object to receive socket and FtpClient events on the data connection when retrieving data from an FTP server.

To remove the event queue and stop monitoring network events, pass NOTHING to the method. See Event Handling for more information.

To control monitoring of network events on just the control connection or on both connections with the same queue, use FtpClient::setControlEventQueue or FtpClient::setEventQueue respectively.

Usage
FtpClient::setDataEventQueue([queue])
Example
$ftp.setDataEventQueue($queue);

Table 4.333. Arguments for FtpClient::setDataEventQueue()

Argument

Type

Description

[queue]

Queue

To set the event queue, pass a Queue object; to clear the event queue, pass no argument to the function.


Table 4.334. Return Values for FtpClient::setDataEventQueue()

Return Type

Description

n/a

This method does not return any value.


4.7.39. FtpClient::setControlEventQueue()

Synopsis

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

To remove the event queue and stop monitoring network events, pass NOTHING to the method. See Event Handling for more information.

To control monitoring of network events on just the data connection or for both data and control connections simultaneously, use FtpClient::setDataEventQueue or FtpClient::setEventQueue respectively

Usage
FtpClient::setControlEventQueue([queue])
Example
$ftp.setControlEventQueue($queue);

Table 4.335. Arguments for FtpClient::setControlEventQueue()

Argument

Type

Description

[queue]

Queue

To set the event queue, pass a Queue object; to clear the event queue, pass no argument to the function.


Table 4.336. Return Values for FtpClient::setControlEventQueue()

Return Type

Description

n/a

This method does not return any value.