ftplib_options

Set connection options.

SYNOPSIS

#include <ftplib.h>
int ftplib_options(int opt, long val, netbuf *nbp);

PARAMETERS

opt: Specifies the option to change. Valid options are FTPLIB_CONNMODE, FTPLIB_IDLECALLBACK, FTPLIB_IDLETIME, FTPLIB_IDLECALLBACKARG, FTPLIB_XFERCALLBACK, FTPLIB_XFERCALLBACKARG, and FTPLIB_CALLBACKBYTES.
val: Specifies the new value for the option. The value may need to by cast to a long.
nbp: A handle returned by ftplib_connect() or ftplib_access().

DESCRIPTION

ftplib_options() changes the options for a connection handle. A data connection inherits the options assigned to the control connection it is created from. Callbacks are only _called_ on file data connections, but they can be assigned for control connection to be inherited be data connections.

The following options and values are recognized.

Option Value
FTPLIB_CONNMODE Specifies the connection mode. Either FTPLIB_PASSIVE or FTPLIB_PORT.
FTPLIB_IDLECALLBACK Specifies the address of a user idle callback routine.
FTPLIB_IDLETIME Specifies the socket idle time in milliseconds that triggers calling the user's idle callback routine.
FTPLIB_IDLECALLBACKARG Specifies an argument to pass to the user's idle callback routine.
FTPLIB_XFERCALLBACK Specifies the address of the user's transfer callback routine.
FTPLIB_XFERCALLBACKARG Specifies an argument to pass to the user's trnasfer callback routine.
FTPLIB_CALLBACKBYTES Specifies the number of bytes to transfer between calls to the user's trnasfer callback routine.

Option	Value
FTPLIB_CONNMODE	Specifies the connection mode. Either FTPLIB_PASSIVE or FTPLIB_PORT.
FTPLIB_IDLECALLBACK	Specifies the address of a user idle callback routine.
FTPLIB_IDLETIME	Specifies the socket idle time in milliseconds that triggers calling the user's idle callback routine.
FTPLIB_IDLECALLBACKARG	Specifies an argument to pass to the user's idle callback routine.
FTPLIB_XFERCALLBACK	Specifies the address of the user's transfer callback routine.
FTPLIB_XFERCALLBACKARG	Specifies an argument to pass to the user's trnasfer callback routine.
FTPLIB_CALLBACKBYTES	Specifies the number of bytes to transfer between calls to the user's trnasfer callback routine.

The connection mode tells ftplib if it should use PASV or PORT to establish data connections. The default is specified as a build option or internally as passive mode connections.

The user's idle callback routine is specified as:

typedef int (*ftp_idle_callback)(netbuf *nbp, void *arg);

nbp is the data connection in use. arg is the value specified with option FTPLIB_IDLECALLBACKARG.

If the user wishes to be called when the data socket is idle for some period of time, use FTPLIB_IDLETIME and pass the time in milliseconds.

typedef void (*ftp_xfer_callback)(netbuf *nbp, int xfered, void *arg);

nbp is the data connection in use. xfered specifies how many bytes of data have been transferred on the connection. arg is the value specified with option FTPLIB_XFERCALLBACKARG.

If the user wishes to be called when a certain amount of data has been transferred, use FTPLIB_CALLBACKBYTES and pass 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. (XXX)

RETURN VALUE

Returns 1 if a valid option was specified and the value is legal. Otherwise, returns 0.

$Id: ftplib_options.html,v 1.1 2002/12/02 03:12:52 te Exp $