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 More...

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

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

DLLLOCAL void	setControlEventQueue (Queue cbq, ExceptionSink xsink)
	sets the event queue for the control socket

DLLLOCAL void	setDataEventQueue (Queue cbq, ExceptionSink xsink)
	sets the event queue for the data socket

DLLLOCAL void	setEventQueue (Queue cbq, ExceptionSink xsink)
	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	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...

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

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

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation