cpi.h

用于嵌入式系统的TCP/IP协议栈及若干服务

/************************************************************************
*            Copyright (c) 1993-2001 by NETsilicon Inc.
*
*  This software is copyrighted by and is the sole property of
*  NETsilicon.  All rights, title, ownership, or other interests
*  in the software remain the property of NETsilicon.  This
*  software may only be used in accordance with the corresponding
*  license agreement.  Any unauthorized use, duplication, transmission,
*  distribution, or disclosure of this software is expressly forbidden.
*
*  This Copyright notice may not be removed or modified without prior
*  written consent of NETsilicon.
*
*  NETsilicon, reserves the right to modify this software
*  without notice.
*
*  NETsilicon
*  411 Waverley Oaks Road                  USA 781.647.1234
*  Suite 227                               http://www.netsilicon.com
*  Waltham, MA 02452                       [e-mail]
*
*************************************************************************
*  $Name: Fusion 6.52 Fusion 6.51 $
*  $Date: 2001/09/20 10:38:56 $
*  $Source: M:/psisrc/ftp/incl/rcs/cpi.h $
*  $Revision: 1.9 $
*************************************************************************
*
*  File Name : cpi.h
*
*  Description:
*     CPI (Client Protocol Interpreter)
*
*     Declarations for the Client Protocol Interpreter (also called
*     user-PI in RFC959).  The Client Protocol Interpreter consists
*     of functions to initiate a control connection to the server-FTP
*     process, sends FTP commands, receives replies, and governs the
*     DTP (data transfer process) if that process is part of the file
*     transfer.
*
*     It is assumed that the reader is familiar with the RFC on the
*     FILE TRANSFER PROTOCOL (RFC 959 as of this writing).
*
*     See the "Internet Engineering Task Force" at
*              http://www.ietf.org
*     to get copies of RFCs.
*************************************************************************/

#ifndef _CPI_
#define _CPI_

#include "ftp.h"
#include "ftype.h"


/*
 * Transfer marker structure.
 * This structure is used to keep track of restart marker replies
 * from the server (110).  These can can later be used to restart
 * a transfer (see 'cpirest').
 */
typedef struct mark_s
   {
    char    * m_cmd;        /* FTP command: APPE, RETR, or STOR */
    char    * m_name;       /* name of file being transferred */
    char    * m_markstr;    /* marker */
   } mark_t;


/*-----------------------------------------------
 * cdc_init
 *
 * Description:
 *    Initialize a control and data connection
 *    structure.
 *
 *    The parameter 'cdcp' is a pointer to the
 *    structure to be initialized.
 *-----------------------------------------------*/
extern void cdc_init( cdc_t   * cdcp);


/*-----------------------------------------------
 * cdc_release
 *
 * Description:
 *    Deallocates the cdc_t object.
 *-----------------------------------------------*/
extern void	cdc_release (cdc_t * cdcp);


/*-----------------------------------------------
 * control_connection
 *
 * Description:
 *    Establish a control connection with an
 *    FTP server.
 *
 *    The parameter 'cdcp' is a pointer to a
 *    structure containing the fields 'c_ctladdress'
 *    which gives the address to be connected to,
 *    and 'c_hostname' which gives the name of the
 *    host to be connected to.  This function must
 *    be called to establish a control connection
 *    before any client protocol interpreter
 *    functions ('cpi*') are called.
 *
 * Returns:
 *    OK (0) if a control connection was
 *    sucessfully established.  Otherwise returns
 *    ERR (-1).
 *-----------------------------------------------*/
extern  int control_connection (cdc_t  *cdcp);


/*-----------------------------------------------
 * cpiabor
 *
 * Description:
 *    Send an abort (ABOR) command across the
 *    control connection.
 *
 *    The control connection is given by the 
 *    parameter 'cdcp'.
 *
 * Returns:
 *    OK (0) if the reply from the server
 *    indicates that the command was successful.
 *    Otherwise ERR (-1) is returned.
 *-----------------------------------------------*/
extern int cpiabor (cdc_t  *cdcp);


/*-----------------------------------------------
 * cpiacct
 *
 * Description:
 *    Send an account (ACCT) command across the
 *    control connection.
 *
 *    The control connection is given by the
 *    parameter 'cdcp' and the account string
 *    is given by the parameter 'account'.
 *
 *    This function is automatically called by
 *    'cpiuser' and 'cpipass' upon receiving a
 *    332 reply from the server.  The caller
 *    supplies the 'account' string which is the
 *    account informataion from the user.
 *
 * Returns:
 *    OK (0) if the reply from the server
 *    indicates that the command was successful.
 *    Otherwise ERR (-1) is returned.
 *-----------------------------------------------*/
extern int cpiacct
              (cdc_t   *cdcp,
               char    *account);


/*-----------------------------------------------
 * cpiallo
 *
 * Description:
 *    Send an allocate (ALLO) command across the
 *    control connection.
 *
 *    The control connection is given by the
 *    parameter 'cdcp'.
 *
 *    The parameter 'bytes' is the number of bytes
 *    (using the logical byte size) of storage to be
 *    reserved for the file.  The parameter 'size' is
 *    the maximum record or page size (in logical
 *    bytes) or zero if not necessary.
 *
 *    This command shall be followed by a STORe or
 *    APPEnd command.  The ALLO command should
 *    be treated as a NOOP (no operation) by those
 *    servers which do not require that the maximum
 *    size of the file be declared beforehand, and
 *    those servers interested in only the maximum
 *    record or page size should accept a dummy value
 *    in the first argument and ignore it.
 *
 * Returns:
 *    OK (0) if the reply from the server
 *    indicates that the command was successful.
 *    Otherwise ERR (-1) is returned.
 *-----------------------------------------------*/
extern  int cpiallo
               (cdc_t   *cdcp,
                int     bytes,
                int     size);


/*-----------------------------------------------
 * cpiappe
 *
 * Description:
 *    Send an append (APPE) command across the
 *    control connection.
 *
 *    The caller indicates the name of the local
 *    file that is to be sent to the server using
 *    the argument 'local_file'.  If 'local_file'
 *    is null, then the data in the 'cdc->c_bufptr'
 *    buffer will be sent to the server.  The name
 *    of the file to be appended to (at the svr
 *    site) is given by the argument 'remote_file'.
 *    Per RFC959, if the file (indicated by
 *    'remote_file') does not exist on the server
 *    site, then the server will create the file.
 *
 *    The control connection is given by the
 *    parameter 'cdcp'.
 *
 * Returns:
 *    OK (0) if the reply from the server
 *    indicates that the command was successful.
 *    Otherwise ERR (-1) is returned.
 *-----------------------------------------------*/
extern  int cpiappe
               (cdc_t   *cdcp,
                char    *local_file,
                char    *remote_file);


/*-----------------------------------------------
 * cpicdup
 *
 * Description:
 *    Send a change to parent directory (CDUP)
 *    command across the control connection
 *
 *    The control connection is given by the
 *    parameter 'cdcp'.
 *
 * Returns:
 *    OK (0) if the reply from the server
 *    indicates that the command was successful.
 *    Otherwise ERR (-1) is returned.
 *-----------------------------------------------*/
extern int cpicdup (cdc_t   *cdcp);


/*-----------------------------------------------
 * cpicwd
 *
 * Description:
 *    Send a change working directory (CWD)
 *    command across the control connection.
 *
 *    The control connection is given by the
 *    parameter 'cdcp'.  The parameter 'path'
 *    is the pathname of the directory to be
 *    changed to at the server site.
 *
 * Returns:
 *    OK (0) if the reply from the server
 *    indicates that the command was successful.
 *    Otherwise ERR (-1) is returned.
 *-----------------------------------------------*/
extern  int cpicwd
               (cdc_t   * cdcp,
                char    * path);


/*-----------------------------------------------
 * cpidele
 *
 * Description:
 *    Send a delete (DELE) command across the
 *    control connection.
 *
 *    The control connection is given by the
 *    parameter 'cdcp'.  The parameter 'path'
 *    is the pathname of the file to be deleted
 *    to at the server site.
 *
 * Returns:
 *    OK (0) if the reply from the server
 *    indicates that the command was successful.
 *    Otherwise ERR (-1) is returned.
 *-----------------------------------------------*/
extern int cpidele
              (cdc_t   * cdcp,
               char    * path);


/*-----------------------------------------------
 * cpihelp
 *
 * Description:
 *    Send a help (HELP) command across the
 *    control connection.
 *
 *    The control connection is given by the
 *    parameter 'cdcp'.  The parameter 'str'
 *    is the command on which help is desired
 *    or nil is help is needed for all commands.
 *
 * Returns:
 *    OK (0) if the reply from the server
 *    indicates that the command was successful.
 *    Otherwise ERR (-1) is returned.
 *-----------------------------------------------*/
extern  int cpihelp
               (cdc_t  *cdcp,
                char   *str);


/*-----------------------------------------------
 * cpilist
 *
 * Description:
 *    Send a list (LIST) command across the
 *    control connection.
 *
 *    The control connection is given by the
 *    parameter 'cdcp'.  The parameter 'path'
 *    specifies a directory or other group of
 *    files, or is nil to indicate the current
 *    working directory at the server site.
 *
 * Returns:
 *    OK (0) if the reply from the server
 *    indicates that the command was successful.
 *    Otherwise ERR (-1) is returned.
 *-----------------------------------------------*/
extern  int cpilist
               (cdc_t   *cdcp,
                char    *path);


/*-----------------------------------------------
 * cpimkd
 *
 * Description:
 *    Send a make directory (MKD) command across
 *    the control connection.
 *
 *    The control connection is given by the
 *    parameter 'cdcp'.  The parameter 'path'
 *    is the pathname of the directory to be
 *    created at the server site.
 *
 * Returns:
 *    OK (0) if the reply from the server
 *    indicates that the command was successful.
 *    Otherwise ERR (-1) is returned.
 *-----------------------------------------------*/
extern  int cpimkd
               (cdc_t *cdcp,
                char  *path);


/*-----------------------------------------------
 * cpimode
 *
 * Description:
 *    Send a transfer mode (MODE) command across
 *    the control connection.
 *
 *    The control connection is given by the
 *    parameter 'cdcp'.  The parameter 'mode' is
 *    the transfer mode desired.
 *
 * Returns:
 *    OK (0) if the reply from the server
 *    indicates that the command was successful.
 *    Otherwise ERR (-1) is returned.
 *-----------------------------------------------*/
extern  int cpimode
              (cdc_t       *cdcp,
               ftp_mode_t  mode);


/*-----------------------------------------------
 * cpinlst
 *
 * Description:
 *    Send a name list (NLST) command across the
 *    control connection.
 *
 *    The control connection is given by the
 *    parameter 'cdcp'.  The parameter 'path'
 *    specifies a directory or other group of
 *    files, or is nil to indicate the current
 *    working directory at the server site.
 *
 * Returns:
 *    OK (0) if the reply from the server
 *    indicates that the command was successful.
 *    Otherwise ERR (-1) is returned.
 *-----------------------------------------------*/
extern int cpinlst
              (cdc_t   *cdcp,
               char    *path);


/*-----------------------------------------------
 * cpinoop
 *
 * Description:
 *    Send a no-operation (NOOP) command across
 *    the control connection
 *
 *    The control connection is given by the
 *    parameter 'cdcp'.
 *
 * Returns:
 *    OK (0) if the reply from the server
 *    indicates that the command was successful.
 *    Otherwise ERR (-1) is returned.
 *-----------------------------------------------*/
extern int cpinoop (cdc_t   *cdcp);


/*-----------------------------------------------
 * cpipass
 *
 * Description:
 *    Send a password (PASS) command across the
 *    control connection
 *
 *    The control connection is given by the
 *    parameter 'cdcp' and the password string
 *    is given by the parameter 'password'.  This
 *    function is automatically called by 'cpiuser'
 *    and 'cpiacct' upon receiving a 331 reply
 *    from the server.  The user supplied function
 *    'get_password' will be called to obtain a
 *    password from the user.
 *
 * Returns:
 *    OK (0) if the reply from the server
 *    indicates that the command was successful.
 *    Otherwise ERR (-1) is returned.
 *-----------------------------------------------*/
extern int cpipass
              (cdc_t  *cdcp,
               char   *password);


/*-----------------------------------------------
 * cpipasv
 *
 * Description:
 *    Send a passive (PASV) command across the
 *    control connection.
 *
 *    The control connection is given by the
 *    parameter 'cdcp'.
 *
 * Returns:
 *    OK (0) if the reply from the server
 *    indicates that the command was successful.
 *    Otherwise ERR (-1) is returned.
 *-----------------------------------------------*/
extern int cpipasv (cdc_t   *cdcp);