library.ltx

来自「UUDeview是一个编码解码器」· LTX 代码 · 共 1,403 行 · 第 1/5 页

pointer (the value of \texttt{opaque}), the other is one line of info
about the file (at maximum, 512 bytes). The callback is called for
each line of info.

The callback can return either zero, meaning that it can accept more
data, or non-zero, which immediately stops retrieval of more
information.

Usually, the opaque pointer holds some information about a text
window, so that the callback knows where to print the next line. In
a terminal-oriented application, the user can be queried each 25th
line and the callback can return non-zero if the user doesn't wish to
continue.

\item[\texttt{int UUSmerge (int pass)}] \hfill{} \\
Attempts a ``Smart Merge'' of parts that seem to belong to different
files but which \emph{could} belong to the same. Occasionally, you
will find a posting with parts 1 to 3 and 5 to 8 of ``picture.gif''
and part 4 of ``picure.gif'' (note the spelling). To the human, it is
obvious that these parts belong together, to a machine, it is
not. This function attempts to detect these conditions and merge the
appropriate parts together. This function must be called repeatedly
with increasing values for ``pass'': With \texttt{pass==0}, only
immediate fits are merged, increasing values allow greater
``distances'' between part numbers,

This function is a bunch of heuristics, and I don't really trust
them. In some cases, the ``smart'' merge may do more harm than
good. This function should only be called as last resort on explicit
user request. The first call should be made with \texttt{pass==0},
then with \texttt{pass==1} and at last with \texttt{pass=99}.
\end{description}

\section{Encoding Functions}

There are a couple of functions to encode data into a file. You will
usually need no more than one of them, depending on the job you want
to do. The functions also differ in the headers they generate. Some
functions do generate full MIME-compliant headers. This may sound like
the best choice, but it's not always the wisest choice. Please follow
the following guidelines.

\begin{itemize}
\item
Do not produce MIME-compliant messages if you cannot guarantee their
proper handling. For example, if you create a MIME-compliant message
on disk, and the user \emph{includes} this file in a text message, the
headers produced for the encoded data become not part of the final
message's header but are just included in the message body. The
resulting message will \emph{not} be MIME-compliant!
\item
Take it from the author that slightly-different-than-MIME messages
give the recipient much worse headaches than messages that do not try
to be MIME in the first place.
\item
Because of that, headers should \emph{only} be generated if the
application itself handles the final mailing or posting of the
message. Do not rely on user actions.
\item
Do not encode to \emph{Base64} outside of MIME messages. Because some
information like the filename is only available in the MIME-message
framework, \emph{Base64} doesn't make much sense without it.
\item
However, if you can guarantee proper MIME handling, \emph{Base64}
should be favored above the other types of encoding. Most
MIME-compliant applications do not know the other encoding types.
\end{itemize}

All of the functions have a bunch of parameters for greater
flexibility. Don't be confused by their number, usually you'll need to
fill only a few of them. There's a number of common parameters which
can be explained separately:

\begin{description}
\item[\texttt{FILE *outfile}] \hfill{} \\
The output stream, where the encoded data is written to.
\item[\texttt{FILE *infile, char *infname}] \hfill{} \\
Where the input data shall be read from. Only one of both values must
be specified, the other can be NULL.
\item[\texttt{char *outfname}] \hfill{} \\
The name by which the recipient will receive the file. It is used on
the ``begin'' line for \emph{uuencoded} and \emph{xxencoded} data, and
in the headers of MIME-formatted messages. If this parameter is NULL,
it defaults to \texttt{infname}. It must be specified if data is read
from a stream and \texttt{infname==NULL}.
\item[\texttt{int filemode}] \hfill{} \\
For \emph{uuencoded} and \emph{xxencoded} data, the file permissions
are encoded into the ``begin'' line. This mode can be specified
here. If the value is 0, it will be determined by performing a
\texttt{stat()} call on the input file. If this call should fail, a
value of 0644 is used as default.
\item[\texttt{int encoding}] \hfill{} \\
The encoding to use. One of the three constants \texttt{UU\ush{}ENCODED},
\texttt{XX\ush{}ENCODED} or \texttt{B64\-ENCODED}.
\end{description}

Now for the functions \dots{}

\begin{description}
\item[\texttt{\begin{tabular}{ll}%
int UUEncodeMulti & (FILE *outfile, FILE *infile, \\
		  & ~char *infname, int encoding, \\
		  & ~char *outfname, char *mimetype, \\
		  & ~int filemode) \\
\end{tabular}}] \hfill{} \\
Encodes data into a subpart of a MIME ``multipart'' message.
Appropriate ``Content-Type'' headers are produced, followed by
the encoded data. The application must provide the envelope and
boundary lines. If \texttt{mimetype!=NULL}, it is used as value
for the ``Content-Type'' field, otherwise, the extension from
\texttt{outfname} or \texttt{infname} (if \texttt{outfname==NULL})
is used to look up the relevant type name.

\item[\texttt{\begin{tabular}{ll}%
int UUEncodePartial & (FILE *outfile, FILE *infile, \\
		    & ~char *infname, int encoding, \\
		    & ~char *outfname, char *mimetype, \\
		    & ~int filemode, int partno, \\
		    & ~long linperfile) \\
\end{tabular}}] \hfill{} \\
Encodes data as the body of a MIME ``message/partial'' message. This
type allows message fragmentation. This function must be called
repetitively until it runs out of input data. The application must
provide a valid envelope with a ``message/partial'' content type and
proper information about the part numbers.

Each call produces \texttt{linperfile} lines of encoded output. For
\emph{uuencoded} and \emph{xxencoded} files, each output line encodes
45 bytes of input data, each \emph{Base64} line encodes 57 bytes.
If \texttt{linperfile==0}, this function is equivalent to
\texttt{UUEncodeMulti}.

Different handling is necessary when reading from an input stream
(if \texttt{infile!=NULL}) compared to reading from a file
(if \texttt{infname!=NULL}). In the first case, the function must be
called until \texttt{feof()} becomes true on the input file, or an
error occurs. In the second case, the file will be opened
internally. Instead of \texttt{UURET\ush{}OK}, a value of
\texttt{UURET\ush{}CONT} is returned for all but the last part.

\item[\texttt{\begin{tabular}{ll}%
int UUEncodeToStream & (FILE *outfile, FILE *infile, \\
		     & ~char *infname, int encoding, \\
		     & ~char *outfname, int filemode) \\
\end{tabular}}] \hfill{} \\
Encodes the input data and sends the plain output without any
headers to the output stream. Be aware that for \emph{Base64}, the
output does not include any information about the filename.

\item[\texttt{\begin{tabular}{ll}%
int UUEncodeToFile & (FILE *infile, char *infname, \\
		   & ~int encoding, char *outfname, \\
		   & ~char *diskname, long linperfile) \\
\end{tabular}}] \hfill{} \\
Encodes the input data and writes the output into one or more output
files on the local disk. No headers are generated. If
\texttt{diskname==NULL}, the names of the encoded files are generated
by concatenating the save path (see the \texttt{UUOPT\ush{}SAVEPATH} 
option) and the base name of \texttt{outfname} or \texttt{infname}
(if \texttt{outfname==NULL}).

If \texttt{diskname!=NULL} and does not contain directory information,
the target filename is the concatenation of the save path and
\texttt{diskname}. If \texttt{diskname} is an absolute path name, it
is used itself.

From the so-generated target filename, the extension is stripped. For
single-part output files, the extension set with the
\texttt{UUOPT\ush{}ENCEXT} option is used. Otherwise, the three-digit
part number is used as extension. If the destination file does already
exist, the value of the \texttt{UUOPT\ush{}OVERWRITE} is checked; if
overwriting is not allowed, encoding fails with
\texttt{UURET\ush{}EXISTS}.

\item[\texttt{\begin{tabular}{ll}%
int UUE\_PrepSingle  & (FILE *outfile, FILE *infile, \\
		    & ~char *infname, int encoding, \\
		    & ~char *outfname, int filemode, \\
		    & ~char *destination, char *from, \\
		    & ~char *subject, int isemail) \\
\end{tabular}}] \hfill{} \\
Produces a complete MIME-formatted message including all necessary
headers. The output from this function is usually fed directly into a
mail delivery agent which honors headers (like ``sendmail'' or
``inews'').

If \texttt{from!=NULL}, it is sent as the sender's email address
in the ``From'' header field. Some MDA programs are able to provide
the sender's address themselves, so this value may be NULL in certain
cases.

If \texttt{subject!=NULL}, the text is included in the ``Subject''
header field. The subject is extended with information about the file
name and part number (in this case, always ``(001/001)'').

``Destination'' must not be NULL. Depending on the ``isemail'' flag,
its contents are sent either in the ``To'' or ``Newsgroups'' header
field.

\item[\texttt{\begin{tabular}{ll}%
int UUE\_PrepPartial & (FILE *outfile, FILE *infile, \\
		     & ~char *infname, int encoding, \\
		     & ~char *outfname, int filemode, \\
		     & ~int partno, long linperfile, \\
		     & ~long filesize, \\
		     & ~char *destination, char *from, \\
		     & ~char *subject, int isemail) \\
\end{tabular}}] \hfill{} \\
Similar to \texttt{UUE\_PrepSingle}, but produces a complete
MIME-formatted ``message/partial'' message including all necessary
headers. The function must be called repetitively until it runs
out of input data. For more explanations, see the description of the
function \texttt{UUEncodePartial} above.

The only additional parameter is \texttt{filesize}. Usually, this
value can be 0, as the size of the input file can usually be
determined by performing a \texttt{stat()} call. However, this might
not be possible if \texttt{infile} refers to a pipe. In that case, the
value of \texttt{filesize} is used.

If the size of the input data cannot be determined, and
\texttt{filesize} is 0, the function refuses encoding into multiple
files and produces only a single stream of output.

If data is read from a file instead from a stream
(\texttt{infile==NULL}), the function opens the file internally and
returns \texttt{UURET\ush{}CONT} instead of \texttt{UURET\ush{}OK} on
successful completion for all but the last part.
\end{description}

\section{The Trivial Decoder}

In this section, we implement and discuss the ``Trivial Decoder'',
which illustrates the use of the decoding functions. We start with the
absolute minimum and then add more features and actually end up with a
limited, but useful tool. For a full-scale frontend, look at the
implementation of the ``UUDeview'' program. The sample code can be
found among the documentation files as \texttt{\mbox{td-v1.c}},
\texttt{\mbox{td-v2.c}} and \texttt{\mbox{td-v3.c}}.

\subsection{Version 1}

\begin{figure}
\centering
\begin{small}
\rule{\textwidth}{1pt}
\begin{verbatim}
#include <stdio.h>
#include <stdlib.h>
#include <config.h>
#include <uudeview.h>

int main (int argc, char *argv[])
{
  UUInitialize ();
  UULoadFile   (argv[1], NULL, 0);
  UUDecodeFile (UUGetFileListItem (0), NULL);
  UUCleanUp    ();
  return 0;
}
\end{verbatim}
\rule{\textwidth}{1pt}
\end{small}
\caption{The ``Trivial Decoder'', Version 1}
\label{td-v1}
\end{figure}

The minimal decoding program is displayed in Figure \ref{td-v1}. Only
four code lines are needed for the implementation. \texttt{<stdlib.h>}
defines \texttt{NULL}, \texttt{<uudeview.h>} declares the decoding
library functions, and \texttt{<config.h>}, the library's
configuration file, is needed for some configuration
details\footnote{Actually, only the definition of \texttt{UUEXPORT}
is needed. You could omit \texttt{<config.h>} and define this value
elsewhere, for example in the project definitions.}.

After initialization, the file given as first command line parameter
is scanned. No symbolic name is assigned to the file, so that we don't
need a file callback. After the scanning, the encoded file is decode