tini400_ftpclient.h

tini的http-slientC程序

/*---------------------------------------------------------------------------
 *  Copyright (C) 2003-2004 Dallas Semiconductor Corporation, All Rights Reserved.
 * 
 *  Permission is hereby granted, free of charge, to any person obtaining a
 *  copy of this software and associated documentation files (the "Software"),
 *  to deal in the Software without restriction, including without limitation
 *  the rights to use, copy, modify, merge, publish, distribute, sublicense,
 *  and/or sell copies of the Software, and to permit persons to whom the
 *  Software is furnished to do so, subject to the following conditions:
 * 
 *  The above copyright notice and this permission notice shall be included
 *  in all copies or substantial portions of the Software.
 * 
 *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 *  OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 *  MERCHANTABILITY,  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 *  IN NO EVENT SHALL DALLAS SEMICONDUCTOR BE LIABLE FOR ANY CLAIM, DAMAGES
 *  OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
 *  ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 *  OTHER DEALINGS IN THE SOFTWARE.
 * 
 *  Except as contained in this notice, the name of Dallas Semiconductor
 *  shall not be used except as stated in the Dallas Semiconductor
 *  Branding Policy.
 *  -------------------------------------------------------------------------
 *  This file contains function definitions for ftpclient library of the 
 *  Dallas Semiconductor 400 processor.  This file is intended for use 
 *  with the Keil MicroVision (uVision) C compiler.
 *  -------------------------------------------------------------------------
 */

#ifndef __tini400_ftpclient_
#define __tini400_ftpclient_

#include "rom400_sock.h"
#include "stdio.h"
#include "ftpcodes.h"
#include <string.h>
#include <ctype.h>

/** \file  tini400_ftpclient.h
 *  \brief FTP Client functions for DS80C400
 *
 *  This library contains functions for FTP Client.
 *
 *  \warning  The functions in this library are <b>NOT</b> multi-process 
 *            safe--that is, if you call the same method from two different 
 *            processes at the same time, the parameters to the function 
 *            may be destroyed, yielding unpredictable results.
 *  
 *  For detailed information on the DS80C400 please see the
 *  <a href="http://pdfserv.maxim-ic.com/arpdf/Design/DS80C400UG.pdf">
 *  High-Speed Microcontroller User's Guide: DS80C400 Supplement</a>.
 */

/** Version number associated with this header file. Should be the same as
 * the version number returned by the <i>#ftpclient_version</i> function.
 * \sa #ftpclient_version */
#define FTPCLIENT_VERSION_NUMBER    1

/** Definition for ASCII data transfer mode
 * \sa #ftpclient_settransmissionmode */
#define FTPCLIENT_ASCII     0

/** Definition for BINARY data transfer mode
 * \sa #ftpclient_settransmissionmode */
#define FTPCLIENT_BINARY    1

/** Definition for default FTP server port number
 * \sa #ftpclient_connect */
#define FTPCLIENT_PORTNUMBER 21

/** Definition for active data connection mode
 * \sa #ftpclient_setdataconnectionmode */
#define FTPCLIENT_ACTIVE_MODE 1

/** Definition for passive data connection mode
 * \sa #ftpclient_setdataconnectionmode */
#define FTPCLIENT_PASSIVE_MODE 0

/** Definition for detailed directory listing
 * \sa #ftpclient_dir */
#define FTPCLIENT_DETAILED_DIRLISTING  1

/** Definition for short directory listing
 * \sa #ftpclient_dir */
#define FTPCLIENT_SHORT_DIRLISTING     0

/** FTP Client Status Success value, this value is returned when operation is completed
 *  successfully. */
#define FTPCLIENT_STATUS_SUCCESS       0
/** Socket error value */
#define FTPCLIENT_SOCKET_ERROR        -1
/** File not found error value */
#define FTPCLIENT_FILE_NOT_FOUND      -2
/** File operation error value */
#define FTPCLIENT_FILE_IO_ERROR       -3
/** Error value indicates that client application is already logged-in */
#define FTPCLIENT_ALREADY_LOGGEDIN    -4
/** Error value indicates that server is not connected */
#define FTPCLIENT_NOT_CONNECTED       -5

/**
 * \brief    Returns version number of ftpclient library
 *
 * \return   Version number of ftpclient library
 */
unsigned int ftpclient_version(void);

/**
 * \brief    Initializes the ftpclient library
 *
 * This function initializes ftpclient library internal datastructure and configures
 * the library with following default configuration
 * <ul><li> ASCII file transfer mode
 *     <li> Active data connection mode
 * </ul>
 *
 * \param    milli_seconds socket timeout value
 *
 */
void ftpclient_init(long milli_seconds);

/**
 * \brief    Connects with FTP server
 *
 * This function establishes connection with FTP server. Connection with FTP server must 
 * be established before calling any other functions that interact with FTP server.
 *
 * \param    sa socket address contains server ip address and FTP server portnumber
 *           <b>NOTE:</b> Passing zero value for portnumber enables ftpclient library 
 *           to use default ftp port number
 * \param    user User name 
 * \param    passwd Password
 *
 * \return   One of the following values:
 *            <ul>
 *              <li><i>#FTPCLIENT_ALREADY_LOGGEDIN</i> - if ftpclient is already connected with server
 *              <li><i>#FTPCLIENT_SOCKET_ERROR</i> - if there is any error in socket communication
 *            </ul>
 *            Otherwise, FTP server status code will be returned for successful or 
 *            failed authentication
 * 
 * <b>NOTE:</b> In case of error, the server socket will be closed before 
 * returning from function
 *
 */
int ftpclient_connect(struct sockaddr_in* sa, char *user, char *passwd);

/**
 * \brief    Sets data transfer mode in FTP server
 *
 * This function sets data transfer mode in FTP server and ftpclient library
 *
 * \param    flag should be either <i>#FTPCLIENT_ASCII</i> or <i>#FTPCLIENT_BINARY</i>
 *
 * <b>NOTE:</b> Invalid input for <i>flag</i> will be interpreted as <i>#FTPCLIENT_BINARY</i>.
 *
 * \return   returns FTP server status code
 */
int ftpclient_settransmissionmode(char flag);

/**
 * \brief    Set data connection mode in ftpclient library
 *
 * This function sets data connection mode in ftpclient library. All future
 * data connections will be made in the mode set by this function
 *
 * \param    flag should be either <i>#FTPCLIENT_ACTIVE_MODE</i> or <i>#FTPCLIENT_PASSIVE_MODE</i>
 *
 * \warning  Invalid value for "flag" yields unexpected behavior of ftpclient 
 *           data transfer functions
 *
 */
void ftpclient_setdataconnectionmode(char flag);

/**
 * \brief    Downloads file from FTP server
 *
 * This function downloads file from FTP server and store it in tini file system.
 *
 * \param    filename Name of file to get from the FTP server 
 * \param    storeas_filename Name of file to store on TINI.  If value for this 
 *           parameter is NULL, then the file will be stored under same name as it
 *           is on the FTP server.
 *
 * \return   <ul><li><i>#FTPCLIENT_NOT_CONNECTED</i> - if connection is not established 
 *               <li><i>#FTPCLIENT_FILE_IO_ERROR</i> - if error happens while storing file
 *               <li><i>#FTPCLIENT_SOCKET_ERROR</i>  - if socket communication error happens
 *           </ul>
 *           Otherwise, returns FTP server status code
 *
 */
int ftpclient_getfile(char *filename, char *storeas_filename);

/**
 * \brief    Uploads tini file to FTP server
 *
 * This function uploads tini file to FTP server.
 *
 * \param    filename Name of file on the TINI to send to the server
 * \param    storeas_filename Name to give the file put on the FTP server.  If NULL,
 *           then the name for the file on TINI will be used.
 *
 * \return   <ul><li><i>#FTPCLIENT_NOT_CONNECTED</i> - if connection is not established 
 *               <li><i>#FTPCLIENT_FILE_NOT_FOUND</i> - if the input tini file name is not there in tini file system
 *               <li><i>#FTPCLIENT_SOCKET_ERROR</i>  - if socket communication error happens
 *           </ul>
 *           Otherwise, returns FTP server status code
 *
 */
int ftpclient_putfile(char *filename, char *storeas_filename);

/**
 * \brief    Returns FTP server directory list
 *
 * This function returns FTP server directory list in short format or detailed format. 
 * This function can also be used to retrieve information about specific file. 
 *
 * \param    name Name of the file to get file attributes information.  If NULL, then
 *                information about all entries of current directory will be returned.
 * \param    dir_str Address of memory buffer where directory information will be stored
 * \param    dir_str_len Maximum amount of data to be stored in <i>dir_str</i> memory buffer
 * \param    format Specifies the format of directory listing. The value for this parameter
 *                 should be either <i>#FTPCLIENT_DETAILED_DIRLISTING</i> or <i>#FTPCLIENT_SHORT_DIRLISTING</i>
 *
 * \return   <ul><li><i>#FTPCLIENT_NOT_CONNECTED</i> - if connection is not established 
 *               <li><i>#FTPCLIENT_SOCKET_ERROR</i>  - if socket communication error happens
 *           </ul>
 *           Otherwise, returns FTP server status code
 *
 */
int ftpclient_dir(char *name, char *dir_str, int dir_str_len, char format);


/**
 * \brief    Returns current FTP server directory path
 *
 *  This function returns the current FTP server directory path name
 *
 * \param    path_str Address of memory buffer where the current FTP server path name will be stored
 * \param    path_str_len Maximum amount of data can be stored in path_str memory buffer
 *
 * \return   <ul><li><i>#FTPCLIENT_NOT_CONNECTED</i> - if connection is not established 
 *               <li><i>#FTPCLIENT_SOCKET_ERROR</i>  - if socket communication error happens
 *           </ul>
 *           Otherwise, returns FTP server status code
 *
 */
int ftpclient_pwd(char *path_str,int path_str_len);

/**
 * \brief    Changes server working directory
 *
 *  This function changes server working directory
 *
 * \param    path_str Address of memory buffer that contains new working directory path name
 *
 * \return   <ul><li><i>#FTPCLIENT_NOT_CONNECTED</i> - if connection is not established 
 *               <li><i>#FTPCLIENT_SOCKET_ERROR</i>  - if socket communication error happens
 *           </ul>
 *           Otherwise, returns FTP server status code
 *
 */
int ftpclient_cd(char *path_str);

/**
 * \brief    Sends command to FTP server
 *
 * This function sends command to FTP server through control connection and returns 
 * FTP server status code.  This function does <b>NOT</b> check whether server is connected. 
 *
 * <b>NOTE:</b> To retrieve the response string of server for control command,
 *              call the <i>#ftpclient_getlaststatus</i> function
 *
 * \param    input_cmd command to send to the FTP server
 *
 * \return   <i>#FTPCLIENT_SOCKET_ERROR</i> if socket communication error happens.
 *           Otherwise, returns FTP server status code
 */
int ftpclient_rawcmd(char *input_cmd);

/**
 * \brief  Configures for new data connection. exchange port number and ip 
 *         address information with FTP server for data connection
 *
 * This function configures for new data connection. For Active mode connection, 
 * sends IP address and port number of ftp client to which the data connection have to be established.
 * For passive mode connection, it gets server IP address and port number for data connection
 *
 * \return  <i>#FTPCLIENT_SOCKET_ERROR</i> if socket communication error happens.
 *          Otherwise, returns FTP server status code
 */
int ftpclient_dataconnection();

/**
 * \brief  Establishes new data connection and returns socket handler
 *
 *  This function establishes new data connection and returns socket handler.
 *
 * <b>IMPORTANT NOTE:</b> For Active mode connection, This function has to be called after sending control 
 * command to server to initiate the data transfer as server will establish data connection after receiving
 * control command.  For passive mode connection, this function has to be called before sending control 
 * command to server to initiate the data transfer as server expects data connection to be made before 
 * responding for control connection.
 *
 * \return  <i>#FTPCLIENT_SOCKET_ERROR</i> if socket communication error happens.
 *          Otherwise, returns FTP server status code
 */
int ftpclient_get_dataconnection_handler();

/**
 * \brief  Terminates connection with FTP server
 *
 * This function terminates connection with FTP server. the server socket will be closed even if
 * there is any socket error
 *
 * \return  <ul><li><i>#FTPCLIENT_SOCKET_ERROR</i>  - if socket communication error happens
 *              <li><i>#FTPCLIENT_NOT_CONNECTED</i> - if connection is not established 
 *          </ul>
 *          Otherwise, returns FTP server status code
 */
int ftpclient_disconnect(void);

/**
 * \brief  Returns last FTP server response string
 *
 * This function returns the FTP server's response status string for the 
 * last control command sent to the server.
 *
 * \return  Pointer to response status string
 */
char *ftpclient_getlaststatus(void);

#endif