QoreFtpClient Class Reference

provides thread-safe access to FTP servers through Qore data structures More...

`#include <QoreFtpClient.h>`

## Public Member Functions

DLLEXPORT | QoreFtpClient ()
| creates the object with no connection parameters
DLLEXPORT | QoreFtpClient (const QoreString *url, ExceptionSink *xsink)
| creates the object and sets connection parameters based on the url passed More...
DLLEXPORT | ~QoreFtpClient ()
| disconnects from the host if necessary and frees all memory associated with the object
DLLEXPORT int | connect (ExceptionSink *xsink)
| connects to the remote host and logs in More...
DLLEXPORT int | cwd (const char *dir, ExceptionSink *xsink)
| changes the working directory on the remote host More...
DLLEXPORT int | del (const char *file, ExceptionSink *xsink)
| deletes the given file on the remote server More...
DLLEXPORT int | disconnect ()
| disconnects from the remote host if connected More...
DLLEXPORT int | get (const char *remotepath, const char *localname, ExceptionSink *xsink)
| gets a file from the remote server and saves it on the local filesystem More...
DLLEXPORT int | get (const char *remotepath, OutputStream *os, ExceptionSink *xsink)
| gets a file from the remote server and writes it to an OutputStream More...
DLLEXPORT BinaryNode * | getAsBinary (const char *remotepath, ExceptionSink *xsink)
| gets a file from the remote server and returns it as a binary node More...
DLLEXPORT QoreStringNode * | getAsString (const char *remotepath, ExceptionSink *xsink)
| gets a file from the remote server and returns it as a string More...
DLLEXPORT QoreHashNode * | getControlPeerInfo (ExceptionSink *xsink, bool host_lookup) const
| returns peer information for a connected control socket More...
DLLEXPORT QoreHashNode * | getControlSocketInfo (ExceptionSink *xsink, bool host_lookup) const
| returns information for the current control socket; the socket must be open More...
DLLEXPORT QoreHashNode * | getDataPeerInfo (ExceptionSink *xsink, bool host_lookup) const
| returns peer information for a connected data socket More...
DLLEXPORT QoreHashNode * | getDataSocketInfo (ExceptionSink *xsink, bool host_lookup) const
| returns information for the current control socket; the socket must be open More...
DLLEXPORT const char * | getHostName () const
| returns the hostname connection parameter
DLLEXPORT const char * | getMode () const
| returns a string for the connection mode: "port", "pasv", "epsv", or "auto" if not connected and auto mode is set
DLLEXPORT int | getNetworkFamily () const
| returns the network family to use with new connections More...
DLLEXPORT const char * | getPassword () const
| returns the password connection parameter
DLLEXPORT int | getPort () const
| returns the port number connection parameter
DLLEXPORT const char * | getSSLCipherName () const
| returns the name of the SSL Cipher for the currently-connected control connection, or 0 if there is none More...
DLLEXPORT const char * | getSSLCipherVersion () const
| returns the version string of the SSL Cipher for the currently-connected control connection, or 0 if there is none More...
DLLLOCAL int | getTimeout () const
| returns the socket I/O timeout value as an integer in milliseconds More...
DLLEXPORT QoreStringNode * | getURL () const
| returns a URL string representing the current connection parameters, caller owns the reference count returned More...
DLLEXPORT const char * | getUserName () const
| returns the user name connection parameter
DLLEXPORT bool | isDataSecure () const
| returns the secure data connection parameter flag More...
DLLEXPORT bool | isSecure () const
| returns the secure connection parameter flag More...
DLLEXPORT QoreStringNode * | list (const char *path, bool long_list, ExceptionSink *xsink)
| returns a string listing the directory contents on the remote host (caller owns the reference count returned) More...
DLLEXPORT int | mkdir (const char *remotepath, ExceptionSink *xsink)
| creates a directory on the remote server More...
DLLEXPORT int | put (const char *localpath, const char *remotename, ExceptionSink *xsink)
| sends a file from the local filesystem to the remote server More...
DLLEXPORT int | put (InputStream *is, const char *remotename, ExceptionSink *xsink)
| sends the content of an InputStream to the remote server More...
DLLEXPORT int | putData (const void *data, qore_size_t len, const char *remotename, ExceptionSink *xsink)
| sends a file data io the remote server More...
DLLEXPORT QoreStringNode * | pwd (ExceptionSink *xsink)
| returns the working directory on the remote host (caller owns the reference count returned) More...
DLLEXPORT int | rename (const char *from, const char *to, ExceptionSink *xsink)
| renames/moves a file on the remote server More...
DLLEXPORT int | rmdir (const char *remotepath, ExceptionSink *xsink)
| removes a directory on the remote server More...
QoreHashNode * | sendControlMessage (const char *cmd, const char *arg, ExceptionSink *xsink)
| Sends a message on the control port and returns a FtpResponseInfo hash or nullptr (if an exception is thrown) More...
DLLLOCAL void | setControlEventQueue (ExceptionSink *xsink, Queue *q, QoreValue arg, bool with_data)
| sets the event queue for the control socket
DLLLOCAL void | setDataEventQueue (ExceptionSink *xsink, Queue *q, QoreValue arg, bool with_data)
| sets the event queue for the data socket
DLLLOCAL void | setEventQueue (ExceptionSink *xsink, Queue *q, QoreValue arg, bool with_data)
| sets the same event queue for data and control sockets
DLLEXPORT void | setHostName (const char *h)
| sets the host name connection parameter
DLLEXPORT int | setInsecure ()
| unsets the secure connection parameter flag (to use the FTP protocol) More...
DLLEXPORT int | setInsecureData ()
| sets the secure data connection parameter flag More...
DLLEXPORT void | setModeAuto ()
| sets the connection mode for the next connection to "auto"
DLLEXPORT void | setModeEPSV ()
| sets the connection mode for the next connection to "EPSV" (extended passive mode)
DLLEXPORT void | setModePASV ()
| sets the connection mode for the next connection to "PASV" (passive mode)
DLLEXPORT void | setModePORT ()
| sets the connection mode for the next connection to "PORT"
DLLEXPORT void | setNetworkFamily (int family)
| sets the network family to use with new connections More...
DLLEXPORT void | setPassword (const char *p)
| sets the password connection parameter
DLLEXPORT void | setPort (int p)
| sets the port connection parameter
DLLEXPORT int | setSecure ()
| sets the secure connection parameter flag (to use the FTPS protocol) More...
DLLLOCAL void | setTimeout (int timeout_ms)
| sets the socket I/O timeout value in milliseconds More...
DLLEXPORT void | setURL (const QoreString *url, ExceptionSink *xsink)
| sets the connection parameters from a URL More...
DLLEXPORT void | setUserName (const char *u)
| sets the user name connection parameter
DLLEXPORT long | verifyPeerCertificate () const
| returns the peer certificate verification code

## Protected Member Functions

DLLLOCAL | QoreFtpClient (const QoreFtpClient &)
| this function is not implemented; it is here as a private function in order to prohibit it from being used
DLLLOCAL QoreFtpClient & | operator= (const QoreFtpClient &)
| this function is not implemented; it is here as a private function in order to prohibit it from being used

## Protected Attributes

struct qore_ftp_private * | priv
| private implementation of the object

## Detailed Description

provides thread-safe access to FTP servers through Qore data structures

is "auto" mode, tries the following data modes in order:

- EPSV mode (RFC 2428)
- PASV mode (RFC 959)
- then PORT

references:

- RFC 959: FTP
- RFC 2428: EPSV mode only (no IPv6 support yet)
- RFC 4217 (supercedes RFC 2228):
- AUTH TLS: secure authentication
- PBSZ 0 and PROT P: secure data connections

Note
  RFC 1639: LPSV mode not implemented yet

tested with:

- tnftpd 20040810 (Darwin/OS X 10.3.8) EPSV, PASV, PORT
- vsFTPd 2.0.1 (Fedora Core 3) EPSV
- proFTPd 1.3.0 (Darwin/OS X 10.4.7) EPSV, PORT, AUTH TLS, PBSZ 0, PROT P

## Constructor & Destructor Documentation

## QoreFtpClient()

DLLEXPORT QoreFtpClient::QoreFtpClient | ( | const QoreString * | url,
|  | ExceptionSink * | xsink
| ) |  |

creates the object and sets connection parameters based on the url passed

a Qore-language exception will be raised if the URL is invalid (protocol is not "ftp" or "ftps") or the hostname is missing.

Parameters

  url | the URL string to use to set connection parameters
  xsink | if an error occurs, the Qore-language exception information will be added here

## Member Function Documentation

## connect()

DLLEXPORT int QoreFtpClient::connect | ( | ExceptionSink * | xsink | ) |

connects to the remote host and logs in

if there are any connection or authentication errors, Qore-language exceptions are raised

Parameters

  xsink | if an error occurs, the Qore-language exception information will be added here

Returns
  0 for OK, non-zero for error (meaning that an exception has been raised)

## cwd()

DLLEXPORT int QoreFtpClient::cwd | ( | const char * | dir,
|  | ExceptionSink * | xsink
| ) |  |

changes the working directory on the remote host

if there are any errors (if no connection has been previously established, it's an error), Qore-language exceptions are raised.

Parameters

  dir | the directory to change to
  xsink | if an error occurs, the Qore-language exception information will be added here

Returns
  0 for OK, non-zero for error (meaning that an exception has been raised)

## del()

DLLEXPORT int QoreFtpClient::del | ( | const char * | file,
|  | ExceptionSink * | xsink
| ) |  |

deletes the given file on the remote server

the connection must be already established before this function is called or an error will be raised.

Parameters

  file | the filename to delete
  xsink | if an error occurs, the Qore-language exception information will be added here

Returns
  0 for OK, non-zero for error (meaning that an exception has been raised)

## disconnect()

DLLEXPORT int QoreFtpClient::disconnect | ( |  | ) |

disconnects from the remote host if connected

Returns
  0 for OK, non-zero for error (currently always returns 0)

## get() [1/2]

DLLEXPORT int QoreFtpClient::get | ( | const char * | remotepath,
|  | const char * | localname,
|  | ExceptionSink * | xsink
| ) |  |

gets a file from the remote server and saves it on the local filesystem

the connection must be already established before this function is called or an error will be raised.

Parameters

  remotepath | the path of the file on the remote server
  localname | the local name of the file
  xsink | if an error occurs, the Qore-language exception information will be added here

Returns
  0 for OK, non-zero for error (meaning that an exception has been raised)

See also
  QoreFtpClient::getAsString()
  QoreFtpCleint::getAsBinary()

## get() [2/2]

DLLEXPORT int QoreFtpClient::get | ( | const char * | remotepath,
|  | OutputStream * | os,
|  | ExceptionSink * | xsink
| ) |  |

gets a file from the remote server and writes it to an OutputStream

the connection must be already established before this function is called or an error will be raised.

Parameters

  remotepath | the path of the file on the remote server
  os | the output stream
  xsink | if an error occurs, the Qore-language exception information will be added here

Returns
  0 for OK, non-zero for error (meaning that an exception has been raised)

See also
  QoreFtpClient::getAsString()
  QoreFtpCleint::getAsBinary()

## getAsBinary()

DLLEXPORT BinaryNode* QoreFtpClient::getAsBinary | ( | const char * | remotepath,
|  | ExceptionSink * | xsink
| ) |  |

gets a file from the remote server and returns it as a binary node

the connection must be already established before this function is called or an error will be raised.

Parameters

  remotepath | the path of the file on the remote server
  xsink | if an error occurs, the Qore-language exception information will be added here

Returns
  file data received as a binary node, otherwise 0 = error (meaning that an exception has been raised)

## getAsString()

DLLEXPORT QoreStringNode* QoreFtpClient::getAsString | ( | const char * | remotepath,
|  | ExceptionSink * | xsink
| ) |  |

gets a file from the remote server and returns it as a string

the connection must be already established before this function is called or an error will be raised.

Parameters

  remotepath | the path of the file on the remote server
  xsink | if an error occurs, the Qore-language exception information will be added here

Returns
  file data received as a string, otherwise 0 = error (meaning that an exception has been raised)

## getControlPeerInfo()

DLLEXPORT QoreHashNode* QoreFtpClient::getControlPeerInfo | ( | ExceptionSink * | xsink,
|  | bool | host_lookup
| ) |  | const

returns peer information for a connected control socket

if the socket is not connected, a Qore-language exception is thrown

Parameters

  xsink | if an error occurs, the Qore-language exception information will be added here
  host_lookup | do a host lookup (if this is false the `"hostname"` and `"hostname_desc"` are not present in the response hash)

Returns
  a hash with the following keys:
  - `hostname:` the hostname of the remote end (if known or appropriate for the socket type, only performed if host_lookup is true)
  - `hostname_desc:` a descriptive string for the remote hostname (including the socket type - ie "ipv6[host]", only performed if host_lookup is true)
  - `address:` the address of the remote end - for UNIX sockets this is the file path
  - `address_desc:` a descriptive string for the remote address
  - `port:` the port number if known
  - `family:` the address family (ie AF_INET, AF_INET6, AF_UNIX, ...)
  - `familystr:` a string description of the address family ("ipv4", "ipv6", etc)

Since
  Qore 0.9.0

## getControlSocketInfo()

DLLEXPORT QoreHashNode* QoreFtpClient::getControlSocketInfo | ( | ExceptionSink * | xsink,
|  | bool | host_lookup
| ) |  | const

returns information for the current control socket; the socket must be open

if the socket is not open, a Qore-language exception is thrown

Parameters

  xsink | if an error occurs, the Qore-language exception information will be added here
  host_lookup | do a host lookup (if this is false the `"hostname"` and `"hostname_desc"` are not present in the response hash)

Returns
  a hash with the following keys:
  - `hostname:` the hostname for the local interface (if known or appropriate for the socket type)
  - `hostname_desc:` a descriptive string for the local hostname (including the socket type - ie "ipv6[host]")
  - `address:` the address of the local interface - for UNIX sockets this is the file path
  - `address_desc:` a descriptive string for the local interface
  - `port:` the port number if known
  - `family:` the address family (ie AF_INET, AF_INET6, AF_UNIX, ...)
  - `familystr:` a string description of the address family ("ipv4", "ipv6", etc)

Since
  Qore 0.9.0

## getDataPeerInfo()

DLLEXPORT QoreHashNode* QoreFtpClient::getDataPeerInfo | ( | ExceptionSink * | xsink,
|  | bool | host_lookup
| ) |  | const

returns peer information for a connected data socket

if the socket is not connected, a Qore-language exception is thrown

Parameters

  xsink | if an error occurs, the Qore-language exception information will be added here
  host_lookup | do a host lookup (if this is false the `"hostname"` and `"hostname_desc"` are not present in the response hash)

Returns
  a hash with the following keys:
  - `hostname:` the hostname of the remote end (if known or appropriate for the socket type, only performed if host_lookup is true)
  - `hostname_desc:` a descriptive string for the remote hostname (including the socket type - ie "ipv6[host]", only performed if host_lookup is true)
  - `address:` the address of the remote end - for UNIX sockets this is the file path
  - `address_desc:` a descriptive string for the remote address
  - `port:` the port number if known
  - `family:` the address family (ie AF_INET, AF_INET6, AF_UNIX, ...)
  - `familystr:` a string description of the address family ("ipv4", "ipv6", etc)

Since
  Qore 0.9.0

## getDataSocketInfo()

DLLEXPORT QoreHashNode* QoreFtpClient::getDataSocketInfo | ( | ExceptionSink * | xsink,
|  | bool | host_lookup
| ) |  | const

returns information for the current control socket; the socket must be open

if the socket is not open, a Qore-language exception is thrown

Parameters

  xsink | if an error occurs, the Qore-language exception information will be added here
  host_lookup | do a host lookup (if this is false the `"hostname"` and `"hostname_desc"` are not present in the response hash)

Returns
  a hash with the following keys:
  - `hostname:` the hostname for the local interface (if known or appropriate for the socket type)
  - `hostname_desc:` a descriptive string for the local hostname (including the socket type - ie "ipv6[host]")
  - `address:` the address of the local interface - for UNIX sockets this is the file path
  - `address_desc:` a descriptive string for the local interface
  - `port:` the port number if known
  - `family:` the address family (ie AF_INET, AF_INET6, AF_UNIX, ...)
  - `familystr:` a string description of the address family ("ipv4", "ipv6", etc)

Since
  Qore 0.9.0

## getNetworkFamily()

DLLEXPORT int QoreFtpClient::getNetworkFamily | ( |  | ) | const

returns the network family to use with new connections

Returns
  the network family to use with new connections (default: AF_UNSPEC)

Since
  Qore 0.9.0

## getSSLCipherName()

DLLEXPORT const char* QoreFtpClient::getSSLCipherName | ( |  | ) | const

returns the name of the SSL Cipher for the currently-connected control connection, or 0 if there is none

Returns
  the name of the SSL Cipher for the currently-connected control connection, or 0 if there is none

## getSSLCipherVersion()

DLLEXPORT const char* QoreFtpClient::getSSLCipherVersion | ( |  | ) | const

returns the version string of the SSL Cipher for the currently-connected control connection, or 0 if there is none

Returns
  the version string of the SSL Cipher for the currently-connected control connection, or 0 if there is none

## getTimeout()

DLLLOCAL int QoreFtpClient::getTimeout | ( |  | ) | const

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

Since
  Qore 0.8.12.3

## getURL()

DLLEXPORT QoreStringNode* QoreFtpClient::getURL | ( |  | ) | const

returns a URL string representing the current connection parameters, caller owns the reference count returned

this function always returns a value

Returns
  a URL string representing the current connection parameters, caller owns the reference count returned

## isDataSecure()

DLLEXPORT bool QoreFtpClient::isDataSecure | ( |  | ) | const

returns the secure data connection parameter flag

true indicates that the current data connection (if any) is encrypted, or that the next data connection can only be established with a secure connection

Returns
  the secure dataconnection parameter flag

## isSecure()

DLLEXPORT bool QoreFtpClient::isSecure | ( |  | ) | const

returns the secure connection parameter flag

true indicates that current control connection (if any) is encrypted, or that the next control connection can only be established with a secure connection

Returns
  the secure connection parameter flag

## list()

DLLEXPORT QoreStringNode* QoreFtpClient::list | ( | const char * | path,
|  | bool | long_list,
|  | ExceptionSink * | xsink
| ) |  |

returns a string listing the directory contents on the remote host (caller owns the reference count returned)

the connection must be already established before this function is called or an error will be raised.

Parameters

  path | the path to list
  long_list | if true then a "long list" is made
  xsink | if an error occurs, the Qore-language exception information will be added here

Returns
  a string giving the directory listing on the remote host (caller owns the reference count returned), 0 if an error occured

## mkdir()

DLLEXPORT int QoreFtpClient::mkdir | ( | const char * | remotepath,
|  | ExceptionSink * | xsink
| ) |  |

creates a directory on the remote server

the connection must be already established before this function is called or an error will be raised.

Parameters

  remotepath | the path of the directory on the remote server
  xsink | if an error occurs, the Qore-language exception information will be added here

Returns
  0 for OK, non-zero for error (meaning that an exception has been raised)

## put() [1/2]

DLLEXPORT int QoreFtpClient::put | ( | const char * | localpath,
|  | const char * | remotename,
|  | ExceptionSink * | xsink
| ) |  |

sends a file from the local filesystem to the remote server

the connection must be already established before this function is called or an error will be raised.

Parameters

  localpath | the local path of the file to send
  remotename | the name of the file on the remote server
  xsink | if an error occurs, the Qore-language exception information will be added here

Returns
  0 for OK, non-zero for error (meaning that an exception has been raised)

## put() [2/2]

DLLEXPORT int QoreFtpClient::put | ( | InputStream * | is,
|  | const char * | remotename,
|  | ExceptionSink * | xsink
| ) |  |

sends the content of an InputStream to the remote server

the connection must be already established before this function is called or an error will be raised.

Parameters

  is | the input stream
  remotename | the name of the file on the remote server
  xsink | if an error occurs, the Qore-language exception information will be added here

Returns
  0 for OK, non-zero for error (meaning that an exception has been raised)

## putData()

DLLEXPORT int QoreFtpClient::putData | ( | const void * | data,
|  | qore_size_t | len,
|  | const char * | remotename,
|  | ExceptionSink * | xsink
| ) |  |

sends a file data io the remote server

the connection must be already established before this function is called or an error will be raised.

Parameters

  data | the data to send
  len | the length of the data to send (if 0, a Qore-language exception will be raised)
  remotename | the name of the file on the remote server
  xsink | if an error occurs, the Qore-language exception information will be added here

Returns
  0 for OK, non-zero for error (meaning that an exception has been raised)

## pwd()

DLLEXPORT QoreStringNode* QoreFtpClient::pwd | ( | ExceptionSink * | xsink | ) |

returns the working directory on the remote host (caller owns the reference count returned)

the connection must be already established before this function is called or an error will be raised.

Parameters

  xsink | if an error occurs, the Qore-language exception information will be added here

Returns
  a string giving the working directory on the remote host (caller owns the reference count returned), 0 if an error occured

## rename()

DLLEXPORT int QoreFtpClient::rename | ( | const char * | from,
|  | const char * | to,
|  | ExceptionSink * | xsink
| ) |  |

renames/moves a file on the remote server

the connection must be already established before this function is called or an error will be raised.

Parameters

  from | the original file path on the remote server
  to | the new file path on the remote server
  xsink | if an error occurs, the Qore-language exception information will be added here

Returns
  0 for OK, non-zero for error (meaning that an exception has been raised)

## rmdir()

DLLEXPORT int QoreFtpClient::rmdir | ( | const char * | remotepath,
|  | ExceptionSink * | xsink
| ) |  |

removes a directory on the remote server

the connection must be already established before this function is called or an error will be raised.

Parameters

  remotepath | the path of the directory on the remote server
  xsink | if an error occurs, the Qore-language exception information will be added here

Returns
  0 for OK, non-zero for error (meaning that an exception has been raised)

## sendControlMessage()

QoreHashNode* QoreFtpClient::sendControlMessage | ( | const char * | cmd,
|  | const char * | arg,
|  | ExceptionSink * | xsink
| ) |  |

Sends a message on the control port and returns a FtpResponseInfo hash or nullptr (if an exception is thrown)

Parameters

  cmd | the command to send
  arg | the argument for the command
  xsink | if an error occurs, the Qore-language exception information will be added here

Since
  Qore 0.9.4

## setInsecure()

DLLEXPORT int QoreFtpClient::setInsecure | ( |  | ) |

unsets the secure connection parameter flag (to use the FTP protocol)

Returns
  0 for OK, -1 for error, not set (if a connection is currently established, then this flag cannot be changed)

## setInsecureData()

DLLEXPORT int QoreFtpClient::setInsecureData | ( |  | ) |

sets the secure data connection parameter flag

after calling QoreFtpClient::setSecure(), this function can be set to indicate that data connection should not be encrypted (while logins will be encrypted)

Returns
  0 for OK, -1 for error, not set (if a connection is currently established, then this flag cannot be changed)

## setNetworkFamily()

DLLEXPORT void QoreFtpClient::setNetworkFamily | ( | int | family | ) |

sets the network family to use with new connections

Parameters

  family | the network family to use with new connections

Note
  must be a valid value (AF_INET, AF_INET6, AF_UNSPEC); values are not validated by this API

Since
  Qore 0.9.0

## setSecure()

DLLEXPORT int QoreFtpClient::setSecure | ( |  | ) |

sets the secure connection parameter flag (to use the FTPS protocol)

Returns
  0 for OK, -1 for error, not set (if a connection is currently established, then this flag cannot be changed)

## setTimeout()

DLLLOCAL void QoreFtpClient::setTimeout | ( | int | timeout_ms | ) |

sets the socket I/O timeout value in milliseconds

Since
  Qore 0.8.12.3

## setURL()

DLLEXPORT void QoreFtpClient::setURL | ( | const QoreString * | url,
|  | ExceptionSink * | xsink
| ) |  |

sets the connection parameters from a URL

a Qore-language exception will be raised if the URL is invalid (protocol is not "ftp" or "ftps") or the hostname is missing.

Parameters

  url | the URL string to use to set connection parameters
  xsink | if an error occurs, the Qore-language exception information will be added here

The documentation for this class was generated from the following file:

- include/qore/QoreFtpClient.h