All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
QoreFtpClient Class Reference

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

`#include <QoreFtpClient.h>`

## Public Member Functions

DLLEXPORT | QoreFtpClient (const QoreString *url, ExceptionSink *xsink)
| creates the object and sets connection parameters based on the url passed
DLLEXPORT | QoreFtpClient ()
| creates the object with no connection parameters
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
DLLEXPORT int | disconnect ()
| disconnects from the remote host if connected
DLLEXPORT int | cwd (const char *dir, ExceptionSink *xsink)
| changes the working directory on the remote host
DLLEXPORT QoreStringNode * | pwd (ExceptionSink *xsink)
| returns the working directory on the remote host (caller owns the reference count returned)
DLLEXPORT int | put (const char *localpath, const char *remotename, ExceptionSink *xsink)
| sends a file from the local filesystem to the remote server
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
DLLEXPORT int | putData (const void *data, qore_size_t len, const char *remotename, ExceptionSink *xsink)
| sends a file data io the remote server
DLLEXPORT QoreStringNode * | getAsString (const char *remotepath, ExceptionSink *xsink)
| gets a file from the remote server and returns it as a string
DLLEXPORT BinaryNode * | getAsBinary (const char *remotepath, ExceptionSink *xsink)
| gets a file from the remote server and returns it as a binary node
DLLEXPORT int | rename (const char *from, const char *to, ExceptionSink *xsink)
| renames/moves a file on the remote server
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)
DLLEXPORT int | del (const char *file, ExceptionSink *xsink)
| deletes the given file on the remote server
DLLEXPORT int | mkdir (const char *remotepath, ExceptionSink *xsink)
| creates a directory on the remote server
DLLEXPORT int | rmdir (const char *remotepath, ExceptionSink *xsink)
| removes a directory on the remote server
DLLEXPORT int | getPort () const
| returns the port number connection parameter
DLLEXPORT const char * | getUserName () const
| returns the user name connection parameter
DLLEXPORT const char * | getPassword () const
| returns the password connection parameter
DLLEXPORT const char * | getHostName () const
| returns the hostname connection parameter
DLLEXPORT void | setURL (const QoreString *url, ExceptionSink *xsink)
| sets the connection parameters from a URL
DLLEXPORT QoreStringNode * | getURL () const
| returns a URL string representing the current connection parameters, caller owns the reference count returned
DLLEXPORT void | setPort (int p)
| sets the port connection parameter
DLLEXPORT void | setUserName (const char *u)
| sets the user name connection parameter
DLLEXPORT void | setPassword (const char *p)
| sets the password connection parameter
DLLEXPORT void | setHostName (const char *h)
| sets the host name connection parameter
DLLEXPORT int | setSecure ()
| sets the secure connection parameter flag (to use the FTPS protocol)
DLLEXPORT int | setInsecure ()
| unsets the secure connection parameter flag (to use the FTP protocol)
DLLEXPORT int | setInsecureData ()
| sets the secure data connection parameter flag
DLLEXPORT bool | isSecure () const
| returns the secure connection parameter flag
DLLEXPORT bool | isDataSecure () const
| returns the secure data connection parameter flag
DLLEXPORT const char * | getSSLCipherName () const
| returns the name of the SSL Cipher for the currently-connected control connection, or 0 if there is none
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
DLLEXPORT long | verifyPeerCertificate () const
| returns the peer certificate verification code
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"
DLLLOCAL void | setEventQueue (Queue *cbq, ExceptionSink *xsink)
| sets the same event queue for data and control sockets
DLLLOCAL void | setDataEventQueue (Queue *cbq, ExceptionSink *xsink)
| sets the event queue for the data socket
DLLLOCAL void | setControlEventQueue (Queue *cbq, ExceptionSink *xsink)
| sets the event queue for the control socket

## 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

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

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)

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)

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)

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

disconnects from the remote host if connected

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

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

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)

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)

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

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

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

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

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

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

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)

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)

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)

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

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)

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)

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)

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)

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)

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