naftpclnt: FTP Client Sample Application using the FTP client API
8 December 2004


Overview
--------
This application demonstrates the FTP client API.  It is provided as a guide
to enable the customer to quickly write their own FTP client application.



Supported Platforms and Processors
----------------------------------
This application is a network application requiring an Ethernet interface,
thus can be run on any Digi International processor or platform.


Features and APIs being demonstrated
------------------------------------
    FTP Client
    - FCConnect()
    - FCDeleteFile()
    - FCDisconnect()
    - FCGetCurrentDir()
    - FCGetData()
    - FCListDir()
    - FCMakeDir()
    - FCPutData()
    - FCRemoveDir()
    - FCRetrieveFile()
    - FCSetCurrentDir()
    - FCStoreFile()


Required external equipment and setup
-------------------------------------
This application requires an FTP Server.


BSP Requirements
----------------
For 9360 platforms, since this application relies on ethernet, the GPIO map
must be configured to route BSP_GPIO_MUX_ETHERNET_PHY_INTERFACE externally 
to use the RMII or MII interface.  Note this setting is activated by default.

No special requirements are necessary to run this application.

    Note you must first compile a BSP listed from the supported platforms
    before you can successfully compile, link and execute this sample
    application.


Customizeable Application Parameters
------------------------------------
The FTP server, the user name, the password, the path name, the file name and
the directory name are hard coded in the naftpclnt.h.  Change them for your
specific FTP server settings.  They are as follows;

    MY_FTP_SERVER
    MY_USER_NAME
    MY_PASSWORD
    MY_PATHNAME
    MY_FILENAME
    MY_DIRNAME

The FTP server define must be entered as an IP address.


Running the Application
-----------------------
The file appconf.h contains the customizable application parameters necessary
for running the application.

The application needs to know if the parameters are to be stored in NVRAM.
The APP_USE_NVRAM parameter defines this behavior.  If it is defined as 0, all
parameters set in this file will be used but will not be written to NVRAM.  If
it is defined as 1, the values in this file will be used as defaults and will
be written to NVRAM.  

The following parameters define the serial port settings for the debug port.  

	#define BSP_BAUD_RATE 9600 in bsp_sys.h
	#define BSP_DIALOG_PORT "/com/0" in bsp_sys.h

In this example the first com port is set to 9600, no parity, 8 data bits and
1 stop bit.  Once the application starts, a dialog will be sent to the
serial port which will allow the parameters to be changed if APP_USE_NVRAM
is defined as 1.  The dialog prompt will wait the number of seconds defined in 
the BSP_STARTUP_DELAY parameter in bsp_sys.h.  If a key is entered within this time,
the settings can be changed.  The password for changing these settings is defined by the
APP_ROOT_PASSWORD parameter in appconf.h.

The following parameters in appconf.h define the IP acquisition mode
and IP address
settings. The APP_IP_ADDRESS, APP_IP_SUBNET_MASK and APP_IP_GATEWAY are only
needed if APP_USE_STATIC_IP is defined as TRUE.

	APP_IP_ADDRESS
	APP_IP_SUBNET_MASK
	APP_IP_GATEWAY
	APP_USE_STATIC_IP
	APP_ENABLE_AUTO_IP

The application starts in the function applicationStart() in the file root.c.
This function starts a thread to run the FTP Client sample application.  A
thread is not necessary but is useful as an example.

Once the FTP Client application starts you should see the following printed
on the debug port.

	<<Starting FTP Client Application

This signifies that the thread NAFtpclnt() has started.

The parameters refereced in the	"Customizeable Application Parameters" section
are used throughout this application.


Detailed Application Description
--------------------------------
The thread NAFtpclnt() first attempts to connect and login to the FTP Server
using the parameters MY_FTP_SERVER, MY_USER_NAME and MY_PASSWORD.  It
does so by calling the function FCConnect().  If the connection attempt fails,
you will see the following printed to the debug port.

	Could not connect to FTP server

This function does not distinguish between a connection and an authentication
failure.

If the FTP client successfully connects and logs into the FTP server, the
function FtpSession() is called with the handle returned from FCConnect().
FtpSession() is an example of FTP session.  It attempts to show the standard
functions of an FTP client.

FTPSession() first calls FCSetCurrentDir() to set the current directory
specified by the parameter MY_PATHNAME.  FCSetCurrentDir() returns either 0
for success or -1 for failure.  The result is printed to the debug port.

FCRemoveDir() is called to remove the directory specified by the parameter
MY_DIRNAME.  FCRemoveDir() returns either 0 for success or -1 for failure.
The result is printed to the debug port. 

FCDeleteFile() is called to delete the file specified by the parameter
MY_FILENAME.  FCDeleteFile() returns either 0 for success or -1 for failure.
The result is printed to the debug port.

FCGetCurrentDir() is called to get the current directory.  The directory is a
NUL terminated string returned in an array of size DIR_NAME_LEN.
FCGetCurrentDir() returns either 0 for success or -1 for failure.  Failure or
the current directory name is printed to the debug port.

The local function ListDirectory() is called to get a directory listing of the
current directory.  ListDirectory() calls the function FCListDir() with an
array of size DIR_LIST_LEN + 1 to hold all, or part of the directory listing.
The extra byte is to NUL terminate the array so it can be printed to the debug
port.  FCListDir() returns the number of bytes of the directory listing
received from the FTP server or -1 for failure.  FCListDir() also fills in the
flag field to indicate if FCListDir() needs to be called again to receive more
data.  Failure or the directory listing is printed to the debug port. 

FCMakeDir() is called to remove the directory specified by the parameter
MY_DIRNAME.  FCMakeDir() returns either 0 for success or -1 for failure.
The result is printed to the debug port.

FCStoreFile() is called to specify the filename and file type to be used for
writing a file using FCPutData().  The filename is specified by the parameter
MY_FILENAME and the file type is FTP_TYPE_ASC (ASCII).  To set the type to
binary, use FTP_TYPE_BIN.   If the result from FCStoreFile() is success,
PutFileData() is called continuously until all of the data has been sent.  The
last_buffer flag must be set to TRUE to tell FCPutData() that this is the last
buffer.  PutFileData() calls FCPutData().   The size of the file is printed to
the debug port.

FCRetrieveFile() is called to specify the filename and file type to be used
for reading a file using FCGetData().  The filename is specified by the
parameter MY_FILENAME and the file type is FTP_TYPE_ASC (ASCII).  To set the
type to binary, use FTP_TYPE_BIN.   If the result from FCGetFile() is success,
GetFileData() is called continuously until all of the data has been received.
This occurs when NAFTPC_EOF is returned from FCGetFile().  GetFileData() calls
FCGetData().   The size of the file is printed to the debug port.

The local function ListDirectory() is called again to get a directory listing
of the current directory.  This time the listing should contain the file we
just created.

For each FTP client operation the network errors can be printed to the debug
port from the function FC_record_error() if PRINTF_ERRORS is defined as a 1 in
ftpclnt.c.  Unfortunately the responses from the FTP client API do not
distinguish between the different error conditions, just success and failure. 

Once "FtpSession" completes, "NAFtpclnt" will attempt to disconnect from the
FTP server by calling "FCDisconnect".  You will see the following;

	"<<End Of Session"

NAFtpclnt() will then exit.

One GNU make file is provided.  Build the target 'image' to
generate an image that can be debugged with gdb, and the file 
image.bin which can be written to flash if the bootloader is used.
Build the target 'rom.bin' to create the file rom.bin which 
can be written to ROM if the bootloader is not used.


Tree Strucuture
---------------
    +naftpclnt
    |   appconf.h             [sets application configuration settings]
    |   readme                [This readme file]
    |   root.c                [Application source file: contains 
    |   naftpclnt.c			  [FTP Client sample application]
    |   naftpclnt.h			  [header file for FTP Client sample application]
    |
    +---+32b
    |       Makefile		  [Make file for the GNU toolset]

