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 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 QoreStringNode *	getAsString (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 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, 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...

DLLEXPORT 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

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

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

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)

◆ 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

xsink	if an error occurs, the Qore-language exception information will be added here
remotepath	the path of the file on the remote server
encoding	the 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

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

DLLEXPORT 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:

/tmp/qore/include/qore/QoreFtpClient.h

Public Member Methods

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ QoreFtpClient()

Member Function Documentation

◆ connect()

◆ cwd()

◆ del()

◆ disconnect()

◆ get() [1/2]

◆ get() [2/2]

◆ getAsBinary()

◆ getAsString() [1/2]

◆ getAsString() [2/2]

◆ getControlPeerInfo()

◆ getControlSocketInfo()

◆ getDataPeerInfo()

◆ getDataSocketInfo()

◆ getNetworkFamily()

◆ getSSLCipherName()

◆ getSSLCipherVersion()

◆ getTimeout()

◆ getURL()

◆ isDataSecure()

◆ isSecure()

◆ list()

◆ mkdir()

◆ put() [1/2]

◆ put() [2/2]

◆ putData()

◆ pwd()

◆ rename()

◆ rmdir()

◆ sendControlMessage()

◆ setInsecure()

◆ setInsecureData()

◆ setNetworkFamily()

◆ setSecure()

◆ setTimeout()

◆ setURL()