class ftplib

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

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

[typedef]

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

[typedef]

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

[constructor]

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

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.

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. 

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.

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.

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.

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.

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.

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.

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.

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

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

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.

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.

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.

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

Parameters:

time time in msec.

Notes:

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

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

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.

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.

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.