libftp.tex

linux下ftp的库源码

 correctly, this function will be called.
   The result code is negative, if an error is occurs.
}
\ttt{\toindex{FtpSetIOHandler}(FTP *,function)}
{
   Predefines handler of Input/Output processing. This function is called, when a connection to the  
   server is broken. For example, when the network or the remote host is down. This handler also is
   called after the  \toindex{timeout} of one character waiting expires.   
}

\ttt{\toindex{FtpDebug}(FTP *)}
{
Turns on all standard debugging functions. 

\tc{\toindex{FtpDebugError}}{--- prints a string, taken from the server, and aborts the program;}
\tc{\toindex{FtpDebugDebug}}{--- prints a string, taken from the server;}
\tc{\toindex{FtpDebugIO}}{--- prints string \ts{strerror(errno)} and aborts the program.}
}


All function for debugging have three arguments:\\
1. Pointer to FTP data structure;\\
2. Last returned value from the server. When errors occur, the value is less than 1;\\
3. Diagnostic string.(char *)

\ttt{\toindex{FtplibDebug}(yes|no)}
{	Turns on/off autostart debug mode, when connection is established.
}

\ttt{\toindex{FtpSetHashHandler}(FTP *,function)}
{
   Predefines handler of function which must compute traffic size. This 
function have only one argument which describe number of transferred bytes.
If this argument is zero counter must be reset to zero.
}


\ttt{\toindex{FtpLog}(char *name\_of\_log, char *message)}
{	Print message to user's screen in libftp's standard format,
        name\_of\_log must be your program name (if this function called 
from standard handlers then this string is title from FTP structure) and 
message with diagnostic string from anywhere.} 


\subsection{Data transfer procedures}

\ttt{STATUS  \toindex{FtpRetr}(FTP~*, char~*command, char~*inp, char~*out)}
{
	This is basically and single procedure in the library for transfer
	file from the server. One check many option with customizing its style
	of working. This options basically is members of FTP structure such
	as timeout, all handlers, mode, seek. If in continue of working this
	function happen timeout or network broked then this function 
	automatically called I/O or error handler, if one is preseted.
        If handler is not set then FtpRetr return
	status QUIT or LQUIT as signal of type of error (LQUIT is specify
	error happen with local filesystem). \\

}

\ttt{\toindex{FtpGet}(FTP~*, char~*in, char~*out)}
{
 Calls \ts{FtpRetr} with adaptation arguments to transfer file
}

\ttt{\toindex{FtpDirectory}(FTP~*, char~*pat\footnote{This is the first argument for \ts{``ls''} command}, char~*out)}
{
 Transfers files listing from the server, described by \ts{pat}, to the local file \ts{out}.
}

\ttt{\toindex{FtpDir}(FTP~*, char~*out)}
{
 Transfers files listing of the current directory from the server to the local file \ts{out}.
}

\ttt{\toindex{FtpStor}(FTP~*, char~*command, char~*inp, char*~out)}
{
  Store file to the server. Works like FtpRetr.
}

\ttt{\toindex{FtpPut}(FTP~*, char~*in, char~*out)}
{
 Calls \ts{FtpStor} adaptation arguments to transfer file 
}

\ttt{\toindex{FtpCopy}(FTP~*ftp\_from, FTP~*ftp\_to, char~*in, char~*out)}
{
 Transfer file between two server without connection to client's host
}

\ttt{\toindex{FtpLink}(FTP~*ftp1, FTP~*ftp2)}
{
 Make data chanel between both servers. 
}

\ttt{\toindex{FtpPassiveTransfer}(FTP~*ftp\_from, FTP~*ftp\_to, char~*in, char~*out)}
{
 Transfer file between two server via client's cache.
}

\subsection{Server's files read/write procedures}

This library contains special functions for remote files reading and 
writing, without copy in advance them to local files. The functions, 
which are described below, do it. After the data channel 
to a remote file is created, it becomes possible to read and write
 characters using standard Input/Output functions
or using special functions \ts{FtpRead}/\ts{FtpWrite} and/or
\ts{FtpGetc}/\ts{FtpPutc}, which reorganize stream for standard text file, 
under condition that the \ts{ASCII} mode is set. 
\footnote{Of course, such functions as \ts{seek}, \ts{ioctl}, .... 
can not be used.}

\ttt{\toindex{FtpData}(FTP~*, char~*command, char~*param, char~*mode)}
{ Makes data transfer channel, with presending command composed from \ts{command} and \ts{param}. 
The mode must be \ts{``r''} or \ts{``w''}}

\ttt{\toindex{FtpOpenRead}(FTP~*,char~*filename)}
{ Opens file named \ts{filename} for reading on server}

\ttt{\toindex{FtpOpenWrite}(FTP~*,char~*filename)}
{ Creates and opens file named \ts{filename} for writing on server}

\ttt{\toindex{FtpOpenAppend}(FTP~*,char~*filename)}
{ Creates and opens file named \ts{filename} for appending on server}

\ttt{\toindex{FtpOpenDir}(FTP~*, char~*files)}
{
  Creates channel for directory list reading, described by argument \ts{files}.
}

\ttt{STATUS \toindex{FtpRead}(FTP~*)}{
Reads character from data stream. If  \ts{ASCII} mode is set\footnote{By default} converts new line markers.
When the end of file is detected or channel is broken, returns \toindex{EOF}}

\ttt{\toindex{FtpWrite}(FTP~*, char~c)}{
Writes single character to stream, if \ts{ASCII} mode is set converts new line markers.
When channel is broken, returns \toindex{EOF}}

\ttt{int \toindex{FtpGetc}(FTP~*,FILE~*fp)}{
Reads character from data stream specified by fp. Using macros FTPDATA and FTPCMD you can specify stream need for reading. \footnote{Functions FtpGetc and FtpPutc ignores data stream mode, works as binary always}
}

\ttt{STATUS \toindex{FtpPutc}(FTP~*,FILE~*fp, char c)}{
Writes character to data stream specified by fp. Using macros FTPDATA and 
FTPCMD you can specify stream need for reading. \footnote{Functions 
FtpGetc and FtpPutc ignores data stream mode, works as binary always}
}


\ttt{\toindex{FtpClose}(FTP~*)}
{Closes opened channel to server}

\subsection{Other commands for server}

\ttt{\toindex{FtpCommand}(FTP~*, char~*command, char~*param, int~ok1, ok2, ok3, ..., okN, EOF)}
{ Sends a command, composed from \ts{command} and \ts{param} using \ts{sprintf} function. 
Reads an answer from the server. 
When return code from the server is not included to \ts{ok-list}(\ts{ok1},\ts{ok2}...) the sign of code 
will be  inverted.}


\ttt{\toindex{FtpType}(FTP~*,char~mode)}
{Sets transfer mode, such as \ts{'A'},\ts{'I'},\ts{'S'},etc...}

\ttt{\toindex{FtpBinary}(FTP~*)}
{Sets binary mode}

\ttt{\toindex{FtpAscii}(FTP~*)}
{Sets \ts{ASCII} mode}


\ttt{\toindex{FtpMkdir}(FTP~*,char *dirname)}
{Makes  directory on server}

\ttt{\toindex{FtpChdir}(FTP~*,char *dirname)}
{Changes working directory on server}

\ttt{\toindex{FtpChmod}(FTP~*,char *file, int mode)}
{Changes protection of file at remote server, argument mode is protection like inside regular stat's structure.}

\ttt{\toindex{FtpRm}(FTP~*,char *filename)}
{Removes file on server}

\ttt{char~*\toindex{FtpPwd}(FTP~*)}
{Returns the name of working directory on server}

\ttt{int \toindex{FtpSize}(FTP~*,char *filename)}
{Returned size (in bytes) of description's file.}

\ttt{STATUS \toindex{FtpStat}(FTP~*,char~*paten,FTP\_STAT **stat\_list)} 
{Get information about files specified by ``paten''. This function is parser
of text output of command ls or dir on UNIX's, VMS's and MSDOS's operating systems.
The basic problem of realization last one is very different syntaxes of output of
different realization of UNIX's, ftp's daemons and programs such as ``ls'' for making
output list. So.... This function give your garanty of right work only if you use
Berkeley's ftpd or wuftpd on UNIX, PC TCP/IP on MSDOS and Multinet on AXP and VAX VMS's
systems, otherwise function returns empty list}

\ttt{STATUS \toindex{FtpStatFree}(FTP\_STAT *)}
{Free memory from data structures}

\ttt{char *\toindex{FtpSyst}(FTP~*)}{FtpStat return name of operating system on remote server}


\ttt{\toindex{FtpMove}(FTP~*,char *oldfilename, char *newfilename)}
{Renames file from \ts{oldfilename} to \ts{newfilename}}

\ttt{\toindex{FtpPort}(FTP~*, int~a, int~b, int~c, int~d, int~e, int~f)
\footnote{Recommended in non-trivial situations}
}
{ A command for the server for making a new data channel. \ts{a.b.c.d} is an IP address of a client(i.e. your IP address), 
\ts{e*256+f} is a port number}


\ttt{struct hostent *\toindex{FtpGetHost}(char *hostname)
\footnote{Extension of standard function ``gethostbyname''}
}
{Returned pointer to structure \ts{hostent} creating using string 
\ts{hostname}, which contains name of the computer or its IP 
address~\footnote{For example''dxunk8.oea.ihep.su'' or ``192.102.229.71''} 
}  


\subsection{Functions for sending/receiving control messages to/from server}

\ttt{\toindex{FtpSendMessage}(FTP~*, char~*message)}
{Sends a message to the server}

\ttt{int \toindex{FtpGetMessage}(FTP~*)}
{Receives a message from the server.}

\ttt{\toindex{FtpMessage}(int Number)}
{Gets a message by code.}

\ttt{\toindex{FtpNumber}(char *Message)}
{Extract message's number from string.}

\subsection{High-level functions}

\ttt{FILE *\toindex{FtpFullOpen}(char *filename,char *mode)}
{  
Parses string \ts{filename}, which must contain a string in format or \\
\ts{host/user/password:filename} or \ts{filename},
what corresponds to remote or local file. The second argument is the type of opening, divided into two characters: 
first --- the mode of opening \ts{``r''}, \ts{``w''} or \ts{``a''}, second is the transfer type , if contains character \ts{``b''},
 then the mode is binary.
}

\ttt{STATUS \toindex{FtpFullClose}(FILE *)}
{  
Close file opened by FtpFullOpen.
}

\ttt{STATUS \toindex{FtpFullSyntax}(FtpString source,FtpString host,FtpString user,FtpString password,FtpString file)}
{Make out string ``source'' for next four parameters.}

\ttt{FILE *\toindex{Ftpfopen}(char *file, char *mode)}
{
	Open file specified in libftp's file specification. Works like 
	\ts{fopen}. \look{FTP}
}

\ttt{STATUS \toindex{Ftpfclose}(FILE *fp)}
{
	Close file which opened using Ftpfopen. Works like fclose.
}

\ttt{STATUS \toindex{FtpArchie}
\footnote{FtpArchie for making list and specification of searched files runs 
``archie'' which must be accessible for execution in one of directories listed in PATH environment variable}
(char *what, ARCHIE *result, int number)}{
Find \ts{number} entrys in Archie's database enrolls described by \ts{what}
argument. \ts{result} must be pointer to array of Archie's structures number
of which must be equivalence or higher than \ts{number}. This call return
number of entrys which found in database. If FtpArchie return value lower 
than zero then pointed target not found or archie isn't works}

\ttt{STATUS \toindex{FtpHttpGet}(char *server, int port, char *spec, char *out)}
\label{FtpHttpGet}
{
 This function transfers file from remote computer thru HTTP-server, which must
be described by two firsts arguments server and port. Object which must be took
(probably ftp's file) must be described as HTTP objects. This function always returns
one of several answers such as:

\begin{itemize}
\item[OK] Object was transfered correctly.
\item[QUIT] Socket's communication problem, need to repeat request again.
\item[LQUIT] Problems with opening local file, 
             probably no disk space or permitions problems, need to check regular errno
		variable.
\item[ENOENT] Specified object doesn't exists.
\end{itemize}
}


\section{Simple example of using LIBFTP}

Next example demonstrate very simple using library calls only Ftpfopen 
and Ftpfclose functions which discriminate libftp's file specification:

\input example

For tests works this program you can try run one as:

\bigskip

\% example username/password@hostname:filename myfile.out

\% example myfile.input username/password@hostname:filename.out


\newpage
\input libftp.ind
\newpage
\tableofcontents
\end{document}