libftp.tex

linux下ftp的库源码

\documentstyle[cxx,fancyheadings,twoside,epsf,indentfirst]{article}
% Vertical sizes
%\vsize=20cm
%\voffset=-2.3cm
%\topmargin=0cm
%\headheight=0.9cm
%\footskip=1cm
%\footheight=0.9cm
%\textheight=16cm
%\headrulewidth 0.01cm
%\footrulewidth 0.0cm
% 0 sizes
%\hsize=30cm
%\hoffset=-4.3cm
%\hoffset=-2.3cm	
%\textwidth=13cm
% Modes
% \special{landscape}
\pagestyle{empty}
\pagestyle{fancyplain}
\newcommand{\tit}[1]{#1}
\rhead[\fancyplain{}{\tit{\leftmark}}]{\fancyplain{}{\tit{\rightmark}}}
\lhead[\fancyplain{}{\tit{\rightmark}}]{\fancyplain{}{\tit{\leftmark}}}
\chead{\hfill}
\lfoot[\fancyplain{}{\tit{\thepage}}]{\fancyplain{}{\hfill}}
\rfoot[\fancyplain{}{\hfill}]{\fancyplain{}{\tit{\thepage}}}
\cfoot{\hfill}
\renewcommand{\sectionmark}[1]{\markboth{#1}{\ }}
\renewcommand{\subsectionmark}[1]{\markright{\ }}
\newcommand{\look}[1]{(Chapter~\ref{#1}, page~\pageref{#1})}
\newcommand{\toindex}[1]{\underline{\bf#1}\index{#1}}
\newcommand{\add}[1]{\symbol{64}}
\newcommand{\ps}[1]{\symbol{37}s}
\newcommand{\twcol}[4]{
\noindent\parbox[t]{#1\textwidth}{#3} \hfill \parbox[t]{#2\textwidth}{#4\hfill}\\
}
\newcommand{\tc}[2]{\twcol{0.49}{0.49}{#1}{#2}}
\newcommand{\tcc}[2]{\twcol{0.49}{0.49}{\toindex{#1}}{#2}}
\newcommand{\ttt}[2]{\bigskip

{\bf#1}

#2}
\newcommand{\ts}[1]{{\underline{\bf#1}}}
\newcommand{\dl}[2]{\parbox[t]{0.4\textwidth}{#1\hfill}\hfill
                    \parbox[t]{0.4\textwidth}{#2\hfill}}
\makeindex
\begin{document} 
\title{{\bf\it{}LIBFTP User's guide}\\Version 5.0}
\author{Oleg Orel\\\\\\[e-mail]\\[e-mail]}
\date{December 13,1995}
\newpage
\maketitle

\section*{License}

This library is designed for free, non-commercial software creation. 
It is changeable and can be improved. The author would greatly appreciate 
any advises, new components and patches of the existing programs.
Commercial usage is also possible with participation of it's author
\footnote{For use this library for commercial purpose need to buy license, for do it
need to contact with author}

\section*{Introduction}

The basic orientation of this library is making user's programs which transport
files via TCP/IP network. It contains set of functions, 
starting from primitive, such as opening FTP connection to the server, 
and finishing by high-level functions, such as functions which retrieve files
 via network, making and closing channels to the server. All functions have 
prototypes in common header file named \toindex{FtpLibrary.h}, 
which must be 
available in standard headers directory
\footnote{for example ``/usr/include''}.
Those prototypes almost fully 
describe orientation and arguments of all functions, 
but common ideology and library components should be mentioned. 

This library is a client and uses standard FTPD from the other side.

There are problems of errors processing in many operating systems including input/output errors. 
The mutual mechanism of value returning of all functions is used in this library.
(EXIT macros, defined in file FtpLibrary.h). This mechanism allows,
 after the definition of the error processing functions, write programs, 
considering the conditions to be ideal.
Data transfer functions have possibility to preset data stream 
expectation timeout.
When the set time expires, previously set function will be called.

\section*{Last major changes}

Last time to library was added several extensions for high level operations: such as 
FtpStat \look{FtpStat} which extract maximum of information about specie-fed file(s) 
and FtpHTTPGet\look{FtpHttpGet} which receive files using as gateway HTTP-server. 

\section{Variables and definitions} 

\subsection{Some definitions in libftp's header file (FtpLibrary.h)}

\ttt{\toindex{EXIT}}{Main macro for return value from library's functions with 
calling handlers if it's need}

\ttt{\toindex{MAX\_ANSWERS}}{Number of possible good answers from FTPD for one request}

\ttt{\toindex{FTP\_NFDS}}{Maximum numbers of one-time opened files in system}

\ttt{\toindex{FTPBUFSIZE}}{Size of block for transmit data via network. 
By default equivalence \toindex{BUFSIZ}}

\ttt{\toindex{LQUIT}}{Error status of local functions. If you give this status 
from libftp's function you must use perror for expand diagnostic.}

\ttt{\toindex{QUIT}}{Error status of network operation. Use perror.}

\ttt{\toindex{Ctrl}(char)}{Return control character code}

\ttt{\toindex{FtpString}}{Special type for strings, entering for readable} 

\ttt{\toindex{STATUS}}{Special type for returned value, if function return value such type, 
it is mean that you must check returned value and compare it with OK, QUIT, LQUIT 
if handlers wasn't preseted} 

\ttt{\toindex{FREE}(data)}{Fill data by zero}

\ttt{\toindex{FtpError}(libftp's call)}{Special macro for diagnostic bad conditions}

\ttt{\toindex{FtpAssert}(libftp's call)}{Special macro for automatically return from
this function if status is bad}

\ttt{\toindex{FtpStatus}(FTP *,libftp's call)}{This macro executes specified function 
and return his status, without interruption to handlers inside if last one was set}

\subsection{Libftp's file specification}

All files which must be interprets as local interprets as libftp's files. 
LIBFTP responds to three types of files such
 as local file, FTP's files and program
pipes. All files can be described as next syntax:

\ttt{$\mid$string}{interprets string as shell command, which must be 
   executed with appropriate input/output for file. It depends where
   this file is specified.}

\ttt{*STDIN*, *STDOUT*, *STDERR* or char '-'}{opened standard streams}

\ttt{anything else}{local file}




\subsection{The FTP data structure} \label{FTP}

\subsubsection{The members of FTP structure}

\tc{FILE *\toindex{sock}\footnote{You can use macro FTPCMD(ftp) for extract
this members, using this macro for making your program more compatibility 
with next versions of this library}}
{--- command channel to the server;}

\tc{FILE *\toindex{data}\footnote{You can use macro FTPDATA(ftp) for extract
this members, using this macro for making your program more compatibility 
with next versions of this library}}
{--- pointer to data structure, which describes data channel to the server;}

\tc{int \toindex{errno}}{ --- last returned value. When value is lower than 1, an error occurred;}

\tc{char \toindex{mode}}{--- type of transfer (valid values: 'A' 'I' ....);}

\tc{int \toindex{ch}}{--- help variable. Is used to convert ASCII files, 
user of library for cleaning your problems must forget about this member;}

\tc{STATUS (*\toindex{error})()}{---  pointer to an error handler. It is called 
                       when status from the server is bad;}
\tc{STATUS (*\toindex{debug})()}{--- pointer to a debug handler. Is called from  
                        functions of sending/receiving messages to/from server;}

\tc{STATUS (*\toindex{IO})()}{--- pointer to Input/Output error handler. Is called when 
channel to server is broken.}

\tc{STATUS (*\toindex{hash})()}{--- pointer to function, which must compute 
summary traffic. This function can take one argument which describe
 how many bytes 
now received of sended to/from server. If the argument is equivalence 
to zero, then counter must be reset to zero. But of course user can use 
this handler for another properties of herself program, for example for 
perriodicaly called anything else for checking other conditions, because 
the transfer procedure can take large time from user's program.}

\tc{int \toindex{seek}}{--- the first byte in file for transfer. This option
can use for re-transfer file again after connection is broken}

\tc{int \toindex{flags}}{--- the option list for transfer procedures such as:
\\
\begin{itemize}
\item[FTP\_REST] Turn on re-transfer file using method of compare size of files
in both sides. 
\item[FTP\_NOEXIT] Don't exit from standard error and IO handlers 
\item[FTP\_HANDLERS] Enable to call handlers for errors and debug events. 
                     Set by default. 
\end{itemize}}

\tc{struct timeval \toindex{timeout}}{--- Timeout for send/receive procedures}

\tc{int \toindex{port}}{--- Port for making command connection}

\tc{FtpString \toindex{title}}{--- Connection identification}

\tc{unsigned long \toindex{counter}}{--- counter of already transferred bytes}

\subsubsection{Initialization of FTP structure}

This library have two special objects: procedure FtpCreateObject and external
static structure FtpInit. The procedure FtpCreateObject called from 
FtpConnect. The structure FtpInit can be modified by hand or by using special
macros such as \toindex{FtpSetFlag}, \toindex{FtpClearFlag}, \toindex{FtpTestFlag}, \toindex{FtpSetPort}, \toindex{FtpSetTimeout}, \toindex{FtpSetErrorHandler}, \toindex{FtpSetDebugHandler}, \toindex{FtpSetIOHandler}, \\ 
\toindex{FtpSetHashHandler},\toindex{FtplibDebug}.

\subsection{The \toindex{ARCHIE}  data structure}

The \ts{ARCHIE} data structure using only with function FtpArchie for extract
result of works one. This structure have four members such as:

\tc{struct tm \toindex{createtime}}{Time of file creation.}

\tc{unsigned long \toindex{size}}{size of file.}

\tc{FtpString \toindex{host}}{Host which file is located}

\tc{FtpString \toindex{file}}{Full path in pointed host of this file}


\subsection{The \toindex{FTP\_STAT}  data structure}\label{FtpStat}

The \ts{FTP\_STAT} data structure using with function \toindex{FtpStat} and \toindex{FtpStatFree} for get file's properties in remote server. Using this functions and this structure you can get size of files, protection, owners and types for file.

\tc{FtpString \toindex{name}}{Name of file which described in current structure}

\tc{char \toindex{type}}{Type of file: '-' - regular file, 'd' - directory, 'l' - symbolic link}

\tc{int \toindex{mode}}{Protection of file.}

\tc{int \toindex{inodes}}{Number of references to this file}

\tc{FtpString \toindex{user}}{Owner's name of this file}

\tc{FtpString \toindex{group}}{Group's name of this file}

\tc{unsigned long \toindex{size}}{Size of file in bytes}

\tc{int \toindex{month}}{Month of creation file}

\tc{int \toindex{day}}{Day of creation file}

\tc{FtpString \toindex{time}}{Time of creation file in string format}

\tc{FtpString \toindex{link}}{If file is symbolic link, here is name of pointed file}

\tc{FTP\_STAT *\toindex{next}}{Pointer to next same structure, otherwise NULL }



\section{Library's routines}

\subsection{Connection/Disconnection with server}

\ttt{STATUS \toindex{FtpConnect}(FTP~**, char~*hostname
\footnote{The name of the host may be symbolic (for example \ts{dxcern.cern.ch}) or numeric (for example \ts{128.141.201.96})}
)}
{
  Makes channel to the server, at the ``hostname'' machine.
  Creates FTP data structure and returns pointer to it. If the procedure \toindex{FtplibDebug}(1)
was previously called, \ts{FtpConnect} calls automatically \ts{FtpDebug} for the \ts{debug mode} to be turned on. 
  \look{debug}.
}
\ttt{STATUS \toindex{FtpUser}(FTP~*, char~*user)}
{
 Sends the name of the user to the server. The connection must be done before it.
}

\ttt{STATUS \toindex{FtpPassword}(FTP~*, char~*password)}
{
 Sends \ts{password} to the server. The function \ts{FtpUser} must be called before it.
}

\ttt{STATUS \toindex{FtpAccount}(FTP~*, char~*account)}
{
 Sends a name of the account to the server. The name of the account is not standard
 attribute for many systems, so this function is used very seldom.
 The function \ts{FtpPassword} must be called before it.
}

\ttt{
STATUS \toindex{FtpLogin}(FTP~**, char~*hostname, char~*user, char~*password, char~*account)}
{
  Executes functions \ts{FtpConnect}, \ts{FtpUser}, \ts{FtpPassword},
  \ts{FtpAccount} (if necessary)  consistently. If the name of the account is absent, 
  replaces it with the \ts{NULL} value.
}

\ttt{STATUS \toindex{FtpBye}(FTP~*)}
{ Finishes work with the server and closes all channels. 
\footnote{You can see from the description of connect/disconnect functions, that you can create 
more than one connection to servers simultaneously.}
}

\ttt{STATUS \toindex{FtpQuickBye}(FTP~*)}
{ Fast close data and command connection to server without delays for waiting
server's confirmation and destroying the FTP object.
}

\ttt{STATUS \toindex{FtpAbort}(FTP~*)}
{ Abort last command passed to server}


\subsection{The debugging} \label{debug} 

There is a possibility to predefine few functions, 
such as:~\footnote{If the \ts{NULL} value is transferred as a parameter \ts{``function''} to the functions, described below,
the handling will be turned off.}

\ttt{\toindex{FtpSetDebugHandler}(FTP *,function)}
{  Predefines function of protocol debugging.
   After the function is predefined, it is called with every 
   sending/receiving messages from the server.
   The function, defined as a debug handler must do returns to the calling 
functions (\ts{FtpSendMessage}/\ts{FtpGetMessage}), but can also abort the program. 

}

\ttt{\toindex{FtpSetErrorHandler}(FTP *,function)}
{
   Predefines error handler. If the server's answer means, that the operation is not finished