FtpSetCallback

Establishes a callback function.

SYNOPSIS

#include <ftplib.h>
int FtpCallback(FtpCallbackOptions *opt, netbuf *nControl);

FtpCallbackOptions is declared as follows.

typedef struct FtpCallbackOptions {
    FtpCallback cbFunc;		/* function to call */
    void *cbArg;		/* argument to pass to function */
    unsigned int bytesXferred;	/* callback if this number of bytes transferred */
    unsigned int idleTime;	/* callback if this many milliseconds have elapsed */
} FtpCallbackOptions;

PARAMETERS

opt: The address of a structure that contains a pointer to the callback function and the criteria for calling it.
nControl: A handle returned by FtpConnect() or FtpAccess().

DESCRIPTION

FtpSetCallback() establishes a callback functions and tells FTPlib when to call it. A data connection inherits the options assigned to the control connection it is created from. Callbacks are only called on file data connections.

The fields in FtpCallbackStruct are described below.

cbFunc: Specifies the address of a user callback routine.
cbArg: Specifies an argument to pass to the user's callback routine.
idleTime: Specifies the socket idle time in milliseconds that triggers calling the user's callback routine.
bytesXferred: Specifies the number of bytes to transfer between calls to the user's callback routine.

The user's callback routine is specified as:

typedef int (*FtpCallback)(netbuf *nControl, int xfered, void *arg);

nControl is the data connection in use. xfered specifies how many bytes of data have been transferred on the connection. arg is the value passed in the FtpCallbackOptions field cbArg.

The user can request to be called back on either of two events.

If the routine should be called when the data socket is idle for some period of time, pass the number of milliseconds of inactivity that should trigger a callback in the idleTime field.

If the routine should be called when a certain amount of data has been transferred, specify a non-zero value in bytesXferred. This value represents the minimum number of bytes to transfer between callbacks. When using this option, ftplib keeps track of the number of bytes transferred and calls the user once the specified number of bytes or more has been transferred. It then resets the count to 0 and starts again.

If the user wishes to continue the transfer, the callback routine should return true (non-zero). It can abort the transfer by return zero.

RETURN VALUE

Returns 1 for success or 0 for failure.