library.ltx

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

\NeedsTeXFormat{LaTeX2e}
\documentclass{article}
\usepackage{psfig}
\usepackage{times}
\usepackage{a4wide}
\author{Frank Pilhofer}
\title{The UUDeview Decoding Library}

\providecommand{\ush}{\discretionary{-}{}{\_}}
\providecommand{\uuversion}{0.5}
\providecommand{\uupatch}{20}

%
% $Id: library.ltx,v 1.28 2004/03/01 23:06:20 fp Exp $
%

\begin{document}
\maketitle
\begin{abstract}
The UUDeview library is a highly portable set of functions that
provide facilities for decoding \emph{uuencoded}, \emph{xxencoded},
\emph{Base64} and \emph{BinHex}-Encoded files as well as for
encoding binary files into all of these representations except
BinHex. This document describes how the features of encoding
and decoding can be integrated into your own applications.

The information is intended for developers only, and is not required
reading material for end users. It is assumed that the reader is
familiar with the general issue of encoding and decoding and has some
experience with the ``C'' programming language.

This document describes version \uuversion{}, patchlevel \uupatch{}
of the library.
\end{abstract}

\section{Introduction}

\subsection{Background}

The Internet provides us with a fast and reliable means of user-to-user
message delivery, using private email or newsgroups. Both systems have
originally been designed to transport plain-text messages. Over the
years, some methods appeared allowing transport of arbitrary binary
data by ``encoding'' the data into plain-text messages. But after
these years, there are still certain problems handling the encoded
data, and many recipients have difficulties decoding the messages back
into their original form.

It should be the job of the mail delivery agent to handle sending and
rend receiving binary data transparently. However, the support of most
applications is limited, and several incompatibilities among different
software exists.

There are three common formats for encoding binary data, called
\emph{uuencoding}, \emph{Base64} and \emph{BinHex}. Issues are further
complicated by slight variations of the formats, the packaging, and
some broken implementations.

Further problems arise with multi-part postings, where the encoding
of a huge file has been split up into several individual messages to
ensure proper transfer over gateways with limited message sizes. Very
few software is able to properly sort and decode the parts. Even
nowadays, many users are at a loss to decode these kinds of messages.

This is where the UUDeview Decoding Library steps in.

\subsection{The Library}

The UUDeview library makes an attempt at decoding nearly all
kinds of encoded files. It is supposed to decode multi-part files as
well as many files simultaneously. Part numbers are evaluated, thus
making it possible to re-arrange parts that aren't in their correct
order.

No assumptions are made on the format of the input file. Usually the
input will be an email folder or newsgroup messages. If this is the
case, the information found in header lines is evaluated; but plain
encoded files with no surrounding information are also accepted. The
input may also consist of concatenated parts and files.

Decoding files is done in two passes. During the first pass, all input
files are scanned. Information is gathered about each chunk of encoded
data. Besides the obvious data about type, position and size of the
chunk, some environmental information from the envelope of a mail
message is also gathered if available.

If the scanner finds a properly MIME-formatted message, a proper MIME
parser steps into action. Because MIME messages include precise
information about the message's contents, there is seldom doubt about
its parts.

For other, non-MIME messages, the ``Subject'' header line is closely
examined. Two informations are extracted: the part number (usually
given in parentheses) and a unique identifier, which is used to group
series of postings. If the subject is, for example, ``uudeview.tgz
(01/04)'', the scanner concludes that this message is the first in a
series of four, and the indicated filename is an ideal key to identify
each of the four parts.

If the subject is incomplete (no part number) or missing, the scanner
tries to make the best of the available information, but some of the
advanced features won't work. For example, without any information
about the part number, it must be assumed that the available parts are
in correct order and can't be automatically rearranged.

All the information is gathered in a linked list. An application can
then examine the nodes of the list and pick individual items for
decoding. The decoding functions will then visit the parts of a file
in correct order and extract the binary data.

Because of heavy testing of the routines against real-life data
and many problem reports from users, the functions have become very
robust, even against input files with few, missing or broken
information.

\begin{figure}
\centering
\makebox{\input{structure.tex}}
\caption{Integration of the Library}
\label{structure}
\end{figure}

Figure \ref{structure} displays how the library can be integrated into
an application. The library does not assume any capabilities of the
operating system or application language, and can thus be used in
almost any environment. The few necessary interfaces must be provided
by the application, which does usually know a great deal more about
the target system.

The idea of the ``language interface'' is to allow integration of the
library services into other programming languages; if the application
is itself written in C, there's no need for a separate interface, of
course. Such an interface currently exists for the Tcl scripting
language; other examples might be Visual Basic, Perl or Delphi.

\subsection{Terminology}

These are some buzzwords that will be used in the following text.
\begin{itemize}
\item
``Encoded data'' is binary data encoded by one of the methods
``uuencoding'', ``xxencoding'', ``Base64'' or ``BinHex''.
\item
``Message'' refers to both complete email messages and Usenet news
postings, including the complete headers. The format of a message is
described in \cite{rfc0822}. A ``message body'' is an email message
or news posting without headers.
\item
A ``mail folder'' is a number of concatenated messages.
\item
``MIME'' refers to the standards set in \cite{rfc1521}.
\item
A ``multipart message'' is an entity described by the MIME
standard. It is a single message divided into one or more individual
parts by a unique boundary.
\item
A ``partial message'' is also described by the MIME standard. It is a
message with an associated identifier and a part number. Large
messages can be split into multiple partial messages on the sender's
side. The recipient's software groups the partial messages by their
identifier and composes them back into the original large message.
\item
The term ``partial message'' only refers to \emph{one part} of the
large message. The original, partialized message is referred to as
``multi-part message'' (note the hyphen). To clarify, one part of a
multi-part message is a partial message.
\end{itemize}

\section{Compiling the Library}

On Unix systems, configuration and compilation is trivial. The
script \texttt{configure} automatically checks your
system and configures the library appropriately. A subsequent
``make'' compiles the modules and builds the final library.

On other systems, you must manually create the configuration file and
the Makefile. The configuration file \texttt{config.h} contains a set
of preprocessor definitions and macros that describe the available
features on your systems.

\subsection{Creating \texttt{config.h} by hand}

You can find all available definitions in \texttt{config.h.in}. This
file undefines all possible definitions; you can create your own
configuration file starting from \texttt{config.h.in} and editing the
necessary differences.

Most definitions are either present or absent, only a few need to have
a value. If not explicitly mentioned, you can activate a definition
by changing the default \texttt{undef} into \texttt{define}.
The following definitions are available:

\subsubsection{System Specific}

\begin{description}
\item[\texttt{SYSTEM\_DOS}]
Define for compilation on a \emph{DOS} system. Currently unused.
\item[\texttt{SYSTEM\_QUICKWIN}]
Define for compilation within a \emph{QuickWin}\footnote{The
Microsoft compilers offer the \emph{QuickWin} target to allow
terminal-oriented programs to run in the Windows environment}
program. Currently unused.
\item[\texttt{SYSTEM\_WINDLL}]
Causes all modules to include \texttt{<windows.h>} before any other
include file. Makes \texttt{uulib.c} export a
\texttt{Dll\-Entry\-Point} function.
\item[\texttt{SYSTEM\_OS2}]
Causes all modules to include \texttt{<os2.h>} before any other
include file.
\end{description}

\subsubsection{Compiler Specific}

\begin{description}
\item[\texttt{PROTOTYPES}]
Define if your compiler supports function prototypes.
\item[\texttt{UUEXPORT}]
This can be a declaration to all functions exported from the decoding
library. Frequently needed when compiling into a shared library.
\item[\texttt{TOOLEXPORT}]
Similar to \texttt{TOOL\-EXPORT}, but for the helper functions from
the replacement functions in \texttt{fptools.c}.
\end{description}

\subsubsection{Header Files}

There are a number of options that define whether header files are
available on your system. Don't worry if some of them are not. If a
header file is present, define ``\texttt{HAVE\_}\emph{name-of-header}'':
\texttt{HAVE\ush{}ERRNO\_H},
\texttt{HAVE\ush{}FCNTL\_H},
\texttt{HAVE\ush{}IO\_H},
\texttt{HAVE\ush{}MALLOC\_H},
\texttt{HAVE\ush{}MEMORY\_H},
\texttt{HAVE\ush{}UNISTD\_H} and
\texttt{HAVE\ush{}SYS\_TIME\_H}
(for \texttt{<sys/time.h>}). Some other include files are needed
as well, but there are no macros for mandatory include files.

There's also a number of header-specific definitions that do not fit
into the general present-or-not-present scheme.

\begin{description}
\item[\texttt{STDC\_HEADERS}]
Define if your header files conform to \emph{ANSI C}. This requires
that \texttt{stdarg.h} is present, that \texttt{stdlib.h} is
available, defining both \texttt{malloc()} and \texttt{free()}, and
that \texttt{string.h} defines the memory functions family
(\texttt{memcpy()} etc).
\item[\texttt{HAVE\_STDARG\_H}]
Implicitly set by \texttt{STDC\ush{}HEADERS}. You only need to define
this one if \texttt{STDC\ush{}HEADERS} is not defined but
\texttt{<stdarg.h>} is available.
\item[\texttt{HAVE\_VARARGS\_H}]
\emph{varargs} can be used as an alternative to \emph{stdarg}. Define
if the above two values are undefined and \texttt{<varargs.h>} is
available.
\item[\texttt{TIME\_WITH\_SYS\_TIME}]
Define if \texttt{HAVE\ush{}SYS\ush{}TIME\_H} and if both \texttt{<sys/time.h>}
and \texttt{<time.h>} can be included without conflicting definitions.
\end{description}

\subsubsection{Functions}

\begin{description}
\item[\texttt{HAVE\_STDIO}]
Define if standard I/O (\texttt{stdin}, \texttt{stdout} and
\texttt{stderr}) is available.
\item[\texttt{HAVE\_GETTIMEOFDAY}]
Define if your system provides the \texttt{gettimeofday()} system
call, which is needed to provide microsecond resolution to the
busy callback. If this function is not available, \texttt{time()} is
used.
\end{description}

\subsubsection{Replacement Functions}

The tools library \texttt{fptools} defines many functions that aren't
standard on all systems. Most of them do not differ in behavior from
their originals, but might be slightly slower. But since they are
usually only needed in non-speed-critical sections, the replacements