class ftplib

# class ftplib | class providing ftp client functionality More...
Definition: | `#include <ftplib.h>`

#### Public Types

- struct netbuf
- enum ftp
- int (*FtpCallbackIdle)(int xfered, void *arg)
- void (*FtpCallbackLog)(char *str, void* arg)

#### Public Methods

- ftplib()
- char* LastResponse()
- int Connect(const char *host)
- int Login(const char *user, const char *pass)
- int Site(const char *cmd)
- int Raw(const char *cmd)
- int SysType(char* buf, int max)
- int Mkdir(const char *path)
- int Chdir(const char *path)
- int Cdup()
- int Rmdir(const char *path)
- int Pwd(char *path, int max)
- int Nlst(const char *outputfile, const char *path)
- int Dir(const char *outputfile, const char *path)
- int Size(const char *path, int *size, ftplib::ftp mode)
- int ModDate(const char *path, char *dt, int max)
- int Get(const char *outputfile, const char *path, ftplib::ftp mode)
- int Get(const char *outputfile, const char *path, ftplib::ftp mode, int offset)
- int Put(const char *inputfile, const char *path, ftplib::ftp mode)
- int Put(const char *inputfile, const char *path, ftplib::ftp mode, int offset)
- int Rename(const char *src, const char *dst)
- int Delete(const char *fnm)
- int SetDataEncryption(ftplib::ftp flag)
- int NegotiateEncryption()
- int FtpRead(void *buf, int max, netbuf *nData)
- int FtpWrite(void *buf, int len, netbuf *nData)
- int FtpAccess(const char *path, int typ, int mode, netbuf *nControl, netbuf **nData)
- int FtpClose(netbuf *nData)
- void Quit()
- void SetCallbackIdleFunction(FtpCallbackIdle pointer)
- void SetCallbackLogFunction(FtpCallbackLog pointer)
- void SetCallbackArg(void *arg)
- void SetCallbackBytes(long bytes)
- void SetCallbackIdletime(int time)
- void SetConnmode(ftplib::ftp mode)

#### Public Static Methods

- static int Fxp(ftplib* src, ftplib* dst, const char *pathSrc, const char *pathDst, ftplib::ftp mode, ftplib::ftp method)

#### Public Members

- netbuf* mp_netbuf

## Detailed Description

ftplibpp contains a c++ class providing ftp client functionality. it is a direct derivate from the great ftplib c library by Thomas Pfau. it was ported to c++, modified alot and added some features to fit todays ftp standards, like resuming up- and downloads, fxp support, ssl/tls encryption and logging functionality. however the very base of ftplibpp is still the nice code from Thomas Pfau.
Every ftp session is represented by an ftplib object, whose methods are called to communicate with the ftp server. The ftp sessions should begin with a call to myftp.Connect("myftp.org:21") (and maybe myftp.NegotiateEncryption()), be followed with myftp.Login("myuser","mypass") and ended by myftp.Quit(); For the magic in between, read the class methods documentation. Most methods have their tasks yet explained from their name.
ftplibpp uses the openssl library for encryption. Currently all programs using ftplibpp have to be linked against openssl. In future revisions it will be possible to disable the ssl functionality by the makefile.

enum ftp { pasv = 1, port = 2, defaultconnmode = 1, ascii = 'A', image = 'I', unencrypted = 0, secure = 1, defaultfxp = 0, alternativefxp = 1 } | ### ftp

several ftp properties, used as method parameters and accessable like ftplib::image.

struct netbuf | ### netbuf

struct which keeps all the necessary variables, necessary for an ftp session. ussually it is only passed through inside an ftplib object as the reference mp_netbuf. however the advanced ftplib methods (FtpAccess, FtpRead, FtpWrite, FtpClose) which can be used to interfere in data connections directly, use immediate netbuf functionality too.
struct netbuf
{
char *cput,*cget;
int handle;
int cavail,cleft;
char *buf;
int dir;
netbuf *ctrl;
int cmode;
int tlsctrl;
int tlsdata;
struct timeval idletime;
FtpCallbackIdle idlecb;
FtpCallbackLog logcb;
void *idlearg;
int xfered;
int cbbytes;
int xfered1;
char response[256];
SSL* ssl;
SSL_CTX* ctx;
BIO* sbio;
int offset;
}

int (*FtpCallbackIdle)(int xfered, void *arg) | ### FtpCallbackIdle

[typedef]
typedef int (*FtpCallbackIdle)(int xfered, void *arg);

void (*FtpCallbackLog)(char *str, void* arg) | ### FtpCallbackLog

[typedef]

typedef void (*FtpCallbackLog)(char *str, void* arg);

ftplib () | ### ftplib

[constructor]

Class constructor, an ftplib object is responsible for the ftp session.

char* LastResponse () | ### LastResponse

LastResponse() returns a pointer to the last response c-styled string sent by the server. This can be parsed by the user program to determine more information about the last request or can be displayed along with an error message.
Returns:

LastResponse() returns a pointer to the last server response string. Otherwise, NULL is returned.

int Connect ( const char* host ) | ### Connect

Connect() establishes a connection to the FTP server on the specified machine and returns a handle which can be used to initiate data transfers. The host name should be specified as or :. may be either a host name or ip address. may be either a service name or a port number.

Parameters:
host The name of the host machine to connect to and optionally an alternate port number to use (ftp.myftp.com:321).
Returns:

If the connection to the remote server if successful, Connect() returns 1. Otherwise, 0 is returned.

int Login ( const char* user, const char* pass) | ### Login

Login() attempts to login to the remote system with the supplied username and password.

Parameters:
user Specifies the username.
pass Specifies the password.
Returns:
Returns 1 if successful or 0 on error.

int Site ( const char *cmd ) | ### Site

Site() sends the specified command as an argument to a 'SITE' command.
Parameters:
cmd A string containing a 'SITE' subcommand.
Returns:
Returns 1 if successful or 0 on error.

int Raw ( const char *cmd ) | ### Raw

Raw() sends the specified command unmodified.
Parameters:
cmd A string containing a custom ftp command.
Returns:
Returns 1 if successful or 0 on error.

int SysType (char *buf, int max ) | ### SysType

SysType() issues a SYST command to the remote system and attempts to parse the system type out of the response and return it to the user's buffer.
Parameters:
buf A pointer to a buffer where the result will be returned.
max Specifies the size of the user buffer.
Returns:
Returns 1 if successful or 0 on error.

int Mkdir ( const char* path) | ### Mkdir

Mkdir() sends a make directory request to the remote system.
Parameters:
path Specifies the argument to mkdir on the remote system.
Returns:
Returns 1 if successful or 0 on error.

int Chdir ( const char* path) | ### Chdir

Sends a change working directory request to the server using the specified path.
Parameters:
path Specifies the desired working directory on the server.
Returns:
Returns 1 if successful or 0 on error.

int Cdup () | ### Cdup

Cdup() sends a CDUP command to the remote server.
Returns:
Returns 1 if successful or 0 on error.

int Rmdir ( const char* path ) | ### Rmdir

Rmdir() sends a remove directory request to the remote server.
Parameters:
path A string containing the name of a remote directory.
Returns:
Returns 1 if successful or 0 on error.

int Pwd (char* path, int max ) | ### Pwd

Pwd() attempts to determine the current default directory at the server and return it to the user's buffer.
Parameters:
path A pointer to a buffer where the result should be returned.
max Specifies the size of the user's buffer.
Returns:
Returns 1 if successful or 0 on error.

int Nlst ( const char* outputfile, const char* path ) | ### Nlst

Performs a short form directory listing of the specified path on the remote system. The results are written to the specified file.
Parameters:
output Specifies the name of a file to receive the directory listing.
path Specifies an argument to 'ls' on the remote system.
Returns:
Returns 1 if successful or 0 on error.

int Dir ( const char* outputfile, const char* path ) | ### Dir

Sends a 'LIST -aL' command to the server with the specified path. The response to this is usually a long format directory listing which will be written to the file named in outputfile. If outputfile is specified as NULL, the list will be written to stdout.
Parameters:
output Specifies the name of a file to receive the directory listing.
path Specifies an argument to 'ls' on the remote system.
Returns:
Returns 1 if successful or 0 on error.

int Size ( const char* path, int* size, ftplib::ftp mode ) | ### Size

Size() attempts to determine the size of a remote file.
Parameters:
path A pointer to a buffer where the result should be returned.
size A pointer to an int where the size will be returned.
mode Specifies the transfer mode as ftplib::image or ftplib::ascii.
Returns:
If a good response is received and the size is successfully parsed out of the result, 1 is returned. Otherwise, 0 is returned.

int ModDate ( const char* path, char* dt, int max ) | ### ModDate

ModDate() attempts to determine the last access time of a remote file and return it to the user's buffer. The date and time are returned as a string in the format 'YYYYMMDDHHMMSS'.
Parameters:
path Name of remote file to be checked.
buf A pointer to a buffer where the result should be returned.
max Specifies the size of the user's buffer.
Returns:
If a good response is received and the date and time are successfully parsed out of the result, 1 is returned. Otherwise, 0 is returned.

int Get (const char* outputfile, const char *path, ftplib::ftp mode ) | ### Get

Get() copies the contents of a remote file to a local file.

Parameters:
output Name of a local file to receive the contents of the remote file.
path Name of remote file to be retrieved.
mode Specifies the transfer mode as ftplib::image or ftplib::ascii.
Returns:
Returns 1 if successful or 0 on error.

int Get (const char* outputfile, const char *path, ftplib::ftp mode, int offset ) | ### Get

Get() copies the contents of a remote file from a given offset and appends it to a local file. Not all ftp servers might implement this feature.

Parameters:
output Name of a local file to receive the contents of the remote file.
path Name of remote file to be retrieved.
mode Specifies the transfer mode as ftplib::image or ftplib::ascii.
offset Point from where the copy begins.

Returns:
Returns 1 if successful or 0 on error.

int Put ( const char* inputfile, const char *path, ftplib::ftp mode ) | ### Put

Put() transfers a local file to the remote system.
Parameters:
input Specifies the name of a local file to be transfered to the server.
path Specifies the name to be given to the file on the remote system.
mode Specifies the transfer mode as ftplib::image or ftplib::ascii.
Returns:
Returns 1 if successful or 0 on error.

int Put ( const char* inputfile, const char *path, ftplib::ftp mode, int offset ) | ### Put

Put() copies the contents of a local file from a given offset and appends it to a remote file. Not all ftp servers might implement this feature.
Parameters:
input Specifies the name of a local file to be transfered to the server.
path Specifies the name to be given to the file on the remote system.
mode Specifies the transfer mode as ftplib::image or ftplib::ascii.
Returns:
Returns 1 if successful or 0 on error.

int Rename ( const char *src, const char *dst ) | ### Rename

FtpRename() sends a rename request to the remote server.
Parameters:
src A string containing the current name of the remote file.
dst A string containing the desired new name for the remote file.
Returns:
Returns 1 if successful or 0 on error.

int Delete ( const char *fnm ) | ### Delete

Requests that the server remove the specified file from the remote file system.

Parameters:
fnm The name of the file which is to be removed.
Returns:
Returns 1 if successful or 0 on error.

int SetDataEncryption ( ftplib::ftp flag ) | ### SetDataEncryption

On an already secured ftp session, SetDataEncryption() specifies if the data connection channel will be secured for the next data transfer.
Parameters:
flag either ftplib::unencrypted or ftplib::secure.
Returns:
Returns 1 if successful and 0 if the control connection isn't secure or on error.
Notes:
See NegotiateEncryption.

int NegotiateEncryption () | ### NegotiateEncryption

This Method is to be called after Connect and before Login to secure the ftp communication channel.
Returns:
Returns 1 if successful and 0 if the ssl negotiation failed.

Notes:

The ftplibpp library uses an ssl/tls encryption approach defined in the draft-murray-auth-ftp-ssl available at http://www.ford-hutchinson.com/~fh-1-pfh/ftps-ext.html.

void Quit () | ### Quit

Quit() issues a 'QUIT' command and closes the connection to the remote server.

void SetCallbackIdleFunction ( FtpCallbackIdle pointer ) | ### SetCallbackIdleFunction

Under certain circumstances defined in SetCallbackBytes and SetCallbackIdletime a callback function can be called during an ftp data transfer. at least one of the above methods have to be called with an argument bigger than 0 to issue a call to pointer. if the callback function returns 0, the data transfer is aborted. the callback function delivers two parameters int xfered and void* arg. xfered is the amount of bytes yet transfered during the data connection and arg contains either NULL or a custom pointer set by SetCallbackArg. If pointer is specified as NULL the idle callback is disabled.

Parameters:
pointer is a pointer to a static function of the type FtpCallbackIdle.

Notes:

Since FtpCallbackIdleFunction only accepts pointers to static functions, it might appear quite pointless in an oo c++ context. However there's an easy way to use it anyway. Using SetCallbackArg you supply the class a pointer to the object whose method you'd like to call from the ftplib object. That pointer is then delivered back with the callback function. from the static callback function you can perform a cast of void* arg to a pointer of the your desired object, and call its method.
valid code could look like this:
...
static int callback(int xfered, void* arg); // static callback function defined in myclass.h
void mymethod(); // common myclass method
...
int myclass::callback(int xfered, void* arg)
{
((*myclass)(arg)->mymethod(); // casting the pointers to the correct type and calling class method
return 1;
}
...
void myclass::mymethod()
{
DoSomething();
}
...
myftp.SetCallbackArg(this); // supply the myftp object the pointer to the current (myclass) object
myftp.SetCallbackIdleFunction(class::callback);
...

void SetCallbackLogFunction ( FtpCallbackLog pointer ) | ### SetCallbackLogFunction

SetCallbackLogFunction() enables the logging callback. everytime there's been data read from the control connection, pointer is called with a c-styled string and a custom pointer specified in SetCallbackArg. If pointer is specified as NULL logging callback is disabled.

Parameters:
pointer is a pointer to a static function of the type FtpCallbackLog.

Notes:

See SetCallbackIdleFunction.

void SetCallbackArg ( void* arg ) | ### SetCallbackArg

SetCallbackArg submits a pointer of custom type to the object, this pointer is returned with a callback function. A good idea is to store the ftplib owners (or whatever object should handle the callback) pointer in it to use it the way described in the SetCallbackIdleFunction entry.

Parameters:
arg a pointer of a custom type.

void SetCallbackBytes ( long bytes ) | ### SetCallbackBytes

SetCallbackBytes specifies the frequency of idle callbacks. The idle callback returns the amount of bytes yet transfered on this transfer.

Parameters:
bytes specifies the frequency in transfered bytes. a value of 100000 would mean every 100000 bytes an idle callback is issued.

Notes:

SetCallbackBytes issues idle callbacks, both callbacks have the same type.

void SetCallbackIdletime ( int time ) | ### SetCallbackIdletime

SetCallbackIdletime specifies how long a data socket can idle, without an idle callback beeing issued.

Parameters:
time time in msec.

Notes:

The default value of 0, means that on every idle a callback happens. if you don't want this behaviour you have to set a (higher) value.

void SetConnmode ( ftplib::ftp mode ) | ### SetCallbackArg

SetConnmode specifies which data connection method is to be used for the next data transfer.

Parameters:

mode either ftplib::pasv (passive mode, default) or ftplib::port (active mode).

int Fxp ( ftplib* src, ftplib* dst, const char *pathSrc, const char *pathDst, ftplib::ftp mode, ftplib::ftp method ) | ### Fxp

[static]

Fxp is a static function. it uses two ftp session objects and transfer a certain file between them.

Parameters:
src source ftplib object.
dst destination ftplib object.
pathSrc path to file to be copied copy ("/incoming/myfile.tar.gz").
pathDst path to file destination ("/pub/myfile_from_some_ftp.tar.gz");
mode either ftplib::ascii (ascii) or ftplib::image (binary).
method either ftplib::defaultfxp (pasv on dst, port on src) or ftplib::alternativefxp (pasv on src, port on dst).

Returns:

Returns 1 if successful, -1 if initilization failed ("PORT" & "PASV"), or 0 if the data transfer somehow failed.
Notes:
Fxp - direct Ftp to Ftp transfer - is rather an exploit than a feature and might thus be prevented by many servers. Currently Fxp does not work with encrypted data connections, so be sure to switch to unencrypted data channels before performing fxp.

int FtpRead ( void* buf, int max, netbuf *nData ) | ### FtpRead

FtpRead copies up to max bytes of data from the specified data connection and returns it to the user's buffer. If the data connection was opened in ascii mode, no more than one line of data will be returned.

Parameters:
buf Specifies the address of a buffer where received data will be written.
max Specifies the size of the user's buffer.
nData A handle returned by FtpAccess().
Returns:
Returns the number of bytes written to the user's buffer or -1 on error or end of file.

Notes:
This is one of the advanced methods. In most cases there should be no need using them. They can be handy sometimes, however. To use those you need to access the mp_netbuf object, and a peek in the sourcecode could be a good idea.

int FtpWrite ( void* buf, int len, netbuf *nData ) | ### FtpWrite

FtpWrite() sends data to a remote file. If the file were accessed in record mode, the necessary conversions are performed.

Parameters:
buf A buffer containing the data to be sent to the remote file.
len The number of bytes to be sent from 'buf'.
nData A handle returned by FtpAccess().
Returns:
Returns the number of bytes sent from the user's buffer or -1 on error.

Notes:
This is one of the advanced methods. In most cases there should be no need using them. They can be handy sometimes, however. To use those you need to access the mp_netbuf object, and a peek in the sourcecode could be a good idea.

int FtpAccess ( const char *path, int typ, int mode, netbuf *nControl, netbuf** nData ) | ### FtpAccess

FtpAccess() opens a remote file or directory and returns a handle for the calling program to use to transfer data.

Parameters:

path Specifies the name of the remote file or directory to open.
typ Specifies the type of transfer to be performed. FTPLIB_DIR performs a terse directory. FTPLIB_DIR_VERBOSE performs a verbose directory. FTPLIB_FILE_READ opens a remote file for reading. FTPLIB_FILE_WRITE creates a remote file and readies it for writing.
mode Specifies the transfer mode as FTPLIB_ASCII or FTPLIB_IMAGE.
nControl An netbuf handle .
nData Specifies the address to store a pointer to the created data handle.
Returns:
Returns 1 if successful or 0 on error.

Notes:
This is one of the advanced methods. In most cases there should be no need using them. They can be handy sometimes, however. To use those you need to access the mp_netbuf object, and a peek in the sourcecode could be a good idea.

int FtpClose ( netbuf *nData ) | ### FtpClose

Closes the data connection specified by 'nData' and frees associated resources.
Parameters:
nData A handle returned by FtpAccess().
Returns:
Returns 1 if successful or 0 on error.
Notes:
This is one of the advanced methods. In most cases there should be no need using them. They can be handy sometimes, however. To use those you need to access the mp_netbuf object, and a peek in the sourcecode could be a good idea.

netbuf* mp_netbuf | ### mp_netbuf

[member]
Contains all the data necessary for an ftp session. The structs members should be modified directly only if you know what you're doing. The advanced methods (FtpAccess, FtpRead, FtpWrite, FtpClose) use mp_netbuf member, for example. The common ftplib methods should be sufficient for most cases, however.

written by: mkulke on Tue Aug 12 03:28 using mozilla composer and some kde documentation template.