FTP Server API

The FTP server provides a single entry point:

    #include <ftpserver.h>

     __externC int cyg_ftpserver_start( cyg_ftpserver *server );

This function starts an FTP server running using parameters defined in the server argument. It should be called from a thread with a stack with at least CYGNUM_NET_FTPSERVER_STACK_SIZE bytes available. Under normal circumstances this function will not return, so the application should create a thread dedicated to the server. There are examples of this in the test programs.

The server argument contains a number of fields that the user may set to control the behaviour of the FTP server.

The normal idiom for use of the FTP server is to define the cyg_ftpserver structure statically and to then call cyg_ftpserver_start() with a pointer to that. The following is a somewhat contrived example:

#include <ftpserver.h>

//==========================================================================

static cyg_ftpserver ftp_server =
{
    .port       = 2121,                            // Listen on port 2121
    .root       = "/fatfs/ftp",                    // FTP to/from here
    .greeting   = "Welcome to Fubar FTP service.", // Welcome string
    .data_port  = 40000                            // Move data ports to 40000+
};

//==========================================================================

static void ftpd(CYG_ADDRWORD p)
{
    init_all_network_interfaces();

    cyg_ftpserver_start( &ftp_server );
}

//==========================================================================

#define STACK_SIZE CYGNUM_NET_FTPSERVER_STACK_SIZE
static char stack[STACK_SIZE] CYGBLD_ATTRIB_ALIGN_MAX;
static cyg_thread thread_data;
static cyg_handle_t thread_handle;

void start_ftpd_thread(void)
{
    cyg_thread_create(10,              // Priority
                    ftpd,              // entry
                    0,                 // entry parameter
                    "FTP test",        // Name
                    &stack[0],         // Stack
                    STACK_SIZE,        // Size
                    &thread_handle,    // Handle
                    &thread_data       // Thread data structure
                    );
  cyg_thread_resume(thread_handle);  /* Start it */
}

The defaults for the configuration parameters are such that leaving them all zero or NULL will cause the server to configure itself on the standard port serving files to/from the root of the filesystem.

Callback Interface

The default server operates to and from a directory in a filesystem, in the same way that most FTP servers operate. However, not all embedded systems have filesystem support. To allow such systems to provide an FTP service, all file access operations go through a set of callback functions in the cyg_ftpserver structure. The user can define these to redirect file I/O operations to other devices such as memory buffers or flash memory regions.

The callback interface defines a type, ftpserver_cookie that is passed to the callback functions. It is a word or pointer sized value and is typically used by the callback functions to contain a data structure pointer, or an index into a table that uniquely identifies an open file.

The callbacks for a notional example interface are defined as follows:

Extending the previous example, the cyg_ftpserver might look like this:

static cyg_ftpserver ftp_server =
{
    .port       = 2121,                            // Listen on port 2121
    .root       = "/fatfs/ftp",                    // FTP to/from here
    .greeting   = "Welcome to Fubar FTP service.", // Welcome string
    .data_port  = 40000,                           // Move data ports to 40000+

    .open       = example_open,
    .read       = example_read,
    .write      = example_write,
    .close      = example_close,
    .auth       = example_auth,
    .delete     = example_delete,

};

Configuration Options

The FTP server package contains a number of configuration options: