Qore Programming Language  1.7.0
QoreFtpClient Class Reference

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

#include <QoreFtpClient.h>

Inherited by QoreFtpClientClass.

Public Member Methods

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 BinaryNodegetAsBinary (const char *remotepath, ExceptionSink *xsink)
 gets a file from the remote server and returns it as a binary node More...
 
DLLEXPORT QoreStringNodegetAsString (const char *remotepath, ExceptionSink *xsink)
 gets a file from the remote server and returns it as a string More...
 
DLLEXPORT QoreStringNodegetAsString (ExceptionSink *xsink, const char *remotepath, const QoreEncoding *encoding=QCS_DEFAULT)
 gets a file from the remote server and returns it as a string More...
 
DLLEXPORT QoreHashNodegetControlPeerInfo (ExceptionSink *xsink, bool host_lookup) const
 returns peer information for a connected control socket More...
 
DLLEXPORT QoreHashNodegetControlSocketInfo (ExceptionSink *xsink, bool host_lookup) const
 returns information for the current control socket; the socket must be open More...
 
DLLEXPORT QoreHashNodegetDataPeerInfo (ExceptionSink *xsink, bool host_lookup) const
 returns peer information for a connected data socket More...
 
DLLEXPORT QoreHashNodegetDataSocketInfo (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 QoreStringNodegetURL () 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 QoreStringNodelist (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, size_t len, const char *remotename, ExceptionSink *xsink)
 sends a file data io the remote server More...
 
DLLEXPORT QoreStringNodepwd (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...
 
QoreHashNodesendControlMessage (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
 

Private Member Methods

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 QoreFtpClientoperator= (const QoreFtpClient &)
 this function is not implemented; it is here as a private function in order to prohibit it from being used
 

Private 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
urlthe URL string to use to set connection parameters
xsinkif 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
xsinkif 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
dirthe directory to change to
xsinkif 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
filethe filename to delete
xsinkif 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
remotepaththe path of the file on the remote server
localnamethe local name of the file
xsinkif 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
remotepaththe path of the file on the remote server
osthe output stream
xsinkif 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
remotepaththe path of the file on the remote server
xsinkif 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() [1/2]

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
remotepaththe path of the file on the remote server
xsinkif 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)

◆ getAsString() [2/2]

DLLEXPORT QoreStringNode* QoreFtpClient::getAsString ( ExceptionSink xsink,
const char *  remotepath,
const QoreEncoding encoding = QCS_DEFAULT 
)

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
xsinkif an error occurs, the Qore-language exception information will be added here
remotepaththe path of the file on the remote server
encodingthe encoding to use for the output string
Returns
file data received as a string, otherwise 0 = error (meaning that an exception has been raised)
Since
Qore 1.3

◆ 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
xsinkif an error occurs, the Qore-language exception information will be added here
host_lookupdo 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
xsinkif an error occurs, the Qore-language exception information will be added here
host_lookupdo 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
xsinkif an error occurs, the Qore-language exception information will be added here
host_lookupdo 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
xsinkif an error occurs, the Qore-language exception information will be added here
host_lookupdo 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
paththe path to list
long_listif true then a "long list" is made
xsinkif 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
remotepaththe path of the directory on the remote server
xsinkif 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
localpaththe local path of the file to send
remotenamethe name of the file on the remote server
xsinkif 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
isthe input stream
remotenamethe name of the file on the remote server
xsinkif 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,
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
datathe data to send
lenthe length of the data to send (if 0, a Qore-language exception will be raised)
remotenamethe name of the file on the remote server
xsinkif 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
xsinkif 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
fromthe original file path on the remote server
tothe new file path on the remote server
xsinkif 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
remotepaththe path of the directory on the remote server
xsinkif 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
cmdthe command to send
argthe argument for the command
xsinkif 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
familythe 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
urlthe URL string to use to set connection parameters
xsinkif an error occurs, the Qore-language exception information will be added here

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