library.ltx

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

filename part of the name (without directory information).

The ``garbage'' filename mentioned above was just for the sake of
argument. It is generally safe to assume that the input filename is
not too weird; after all, it is a filename valid on \emph{some}
system. Still, the user should always be granted the possibility of
renaming a file before decoding it, to allow decoding of files with
insane filenames.

\section{The File List}
\label{file-list}

While scanning the input files, a linked list is built. Each node is
of type \texttt{uulist} and describes one file, possibly composed of
several parts. This section describes the members of the structure
that may be of interest to an application.

\begin{description}
\item[\texttt{state}]
Describes the state of this file. Either the value
\texttt{UUFILE\ush{}READ}\footnote{This value should
only appear internally, never to be seen by an application.} or a
bitfield of the following values:
\begin{description}
\item[\texttt{UUFILE\_MISPART}]
The file is missing at least one part. This bit is set if the part
numbers are non-sequential. Usually results in incorrect decoding.
\item[\texttt{UUFILE\_NOBEGIN}]
No ``begin'' line was detected. Since \emph{Base64}
files do not have begin lines, this bit is never set on them.
For \emph{BinHex} files, the initial colon is used.
\item[\texttt{UUFILE\_NOEND}]
No ``end'' line was detected. Since \emph{Base64}
files do not have end lines, this bit is never set on them. A missing
end on \emph{uuencoded} or \emph{xxencoded} files usually means that
the file is incomplete. For \emph{BinHex}, the trailing colon is
used as end marker.
\item[\texttt{UUFILE\_NODATA}]
No encoded data was found within these parts.
\item[\texttt{UUFILE\_OK}]
This file appears to be okay, and decoding is likely to be successful.
\item[\texttt{UUFILE\_ERROR}]
A decode operation was attempted, but failed, usually because of an
I/O error.
\item[\texttt{UUFILE\_DECODED}]
This file has already been successfully decoded.
\item[\texttt{UUFILE\_TMPFILE}]
The file has been decoded into a temporary file, which can be found
using the \texttt{binfile} member (see below). This flag gets removed
if the temporary file is deleted.
\end{description}
\item[\texttt{mode}]
For \emph{uuencoded} and \emph{xxencoded} files, this is the file mode
found on the ``begin'' line, \emph{Base64} and \emph{BinHex} files
receive a default of 0644. A decode operation will try to restore this
mode.
\item[\texttt{uudet}]
The type of encoding this file uses. May be 0 if
\texttt{UUFILE\ush{}NODATA} or one of the following
values:
\begin{description}
\item[\texttt{UU\_ENCODED}] for \emph{uuencoded} data,
\item[\texttt{B64ENCODED}]  for \emph{Base64} encoded data,
\item[\texttt{XX\_ENCODED}] for \emph{xxencoded} data,
\item[\texttt{BH\_ENCODED}] for \emph{BinHex} data,
\item[\texttt{PT\_ENCODED}] for plain-text ``data'', or
\item[\texttt{QT\_ENCODED}] for MIME \emph{quoted-printable} encoded
text.
\end{description}
\item[\texttt{size}]
The approximate size of the resulting file. It is an estimated value
and can be a few percent off the final value, hence the suggestion to
display the size in kilobytes only.
\item[\texttt{filename}]
The filename. For \emph{uuencoded} and \emph{xxencoded} files, it is
extracted from the ``begin'' line. The name of \emph{BinHex} files
is encoded in the first data bytes. \emph{Base64} files have the
filename given in the ``Content-Type'' header. This field may be
\texttt{NULL} if \texttt{state!=UUFILE\ush{}OK}.
\item[\texttt{subfname}]
A unique identifier for this group of parts, usually derived from the
``Subject'' header of each part. It is possible that two
nodes with the same identifier exist in the file list: If a group of
files is considered ``complete'', a new node is opened up for more
parts with the same Id.
\item[\texttt{mimeid}]
Stores the ``id'' field from the ``Content-Type'' information if
available. Actually, this Id is the first choice for grouping of
files, but not surprisingly, non-MIME mails or articles do not have
this information.
\item[\texttt{mimetype}]
Stores this part's ``Content-Type'' if available.
\item[\texttt{binfile}]
After decoding, this is the name of the temporary file the data was
decoded to and stored in. This value is non-NULL if the flag
\texttt{UUFILE\ush{}TMPFILE} is set in the state member above.
\item[\texttt{haveparts}]
The part numbers found for this group of files as a zero-terminated
ordered integer array. Some extra care must be taken, because a file
may have a zeroth part as its first part. Thus if
\texttt{haveparts[0]} is zero, it indicates a zeroth part, and the
list of parts continues. A file may have at most one zeroth part, so
if both \texttt{haveparts[0]} and \texttt{haveparts[1]} are zero, the
zeroth part is the only part of this file.

No more than 256 parts are listed here.
\item[\texttt{misparts}]
Similar to \texttt{haveparts}; a zero-terminated ordered integer array
of missing parts, or simply \texttt{NULL} if no parts are
missing. Since we don't mind if a file doesn't have a zeroth part,
this array does not have the above problems.
\end{description}

\section{Return Values}

Most of the library functions return a value indicating success or the
type of error occurred. The following values can be returned:

\begin{description}
\item[\texttt{UURET\_OK}]
The action completed successfully.
\item[\texttt{UURET\_IOERR}]
An I/O error occurred. There may be many reasons from ``File not
found'' to ``Disk full''. This return code indicates that the
application should consult \texttt{errno} for more information.
\item[\texttt{UURET\_NOMEM}]
A \texttt{malloc()} operation returned \texttt{NULL}, indicating that
memory resources are exhausted. Never seen this one in a VM system.
\item[\texttt{UURET\_ILLVAL}]
You tried to call some operation with invalid parameters.
\item[\texttt{UURET\_NODATA}]
An attempt was made to decode a file, but no encoded data was found
within its parts. Also returned if decoding a \emph{uuencoded} or
\emph{xxencoded} file with missing ``begin'' line.
\item[\texttt{UURET\_NOEND}]
A decoding operation was attempted, but the decoded data didn't have a
proper ``end'' line. A similar condition can also be detected for
\emph{BinHex} files (where the colon is used as end marker).
\item[\texttt{UURET\_UNSUP}]
You tried to encode using an unsupported communications channel, for
example piping to a command on a system without pipes.
\item[\texttt{UURET\_EXISTS}]
The target file already exists (upon decoding), and you didn't allow
to overwrite existing files.
\item[\texttt{UURET\_CONT}]
This is a special return code, indicating that the current operation
must be continued. This return value is used only by two encoding
functions, so see the documentation there.
\item[\texttt{UURET\_CANCEL}]
The current operation was canceled, meaning that the Busy Callback
returned a non-zero value usually because of user request. The library
does not produce this return value on its own, so if your Busy
Callback always returns zero, there's no need to handle this
``Error''.
\end{description}

\section{Options}
\label{Section-Options}
An application program can set and query a number of options. Some of
them are read-only, but others can modify the behavior quite
drastically. Some of them are intended to be set by the end user via
an options menu.

\begin{description}
\item[\texttt{UUOPT\_VERSION}] {\small (string, read-only)} \\
Retrieves the full version number of the library, composed as
\emph{MA\-JOR}.\emph{MI\-NOR}\discretionary{}{}{}pl\emph{PATCH}
(the major and minor version
numbers and the patchlevel are integers).

\item[\texttt{UUOPT\_FAST}] {\small (integer, default=0)} \\
If set to 1, the library will assume that each input file consists of
exactly one email message or newsgroup posting. After finding encoded
data within a file, the scanner will not continue to look for more
data below. This strategy can save a lot of time, but has the drawback
that files also cannot be checked for completeness -- since the
scanner does not look for ``end'' lines, we don't notice them missing.

This flag does not have any effect on MIME multipart messages, which
are always scanned to the end (alas, the Epilogue will be skipped).
Actually, with this flag set, the scanner becomes more MIME-compliant.

\item[\texttt{UUOPT\_DUMBNESS}] {\small (integer, default=0)} \\
As already mentioned, the library evaluates
information found in the part's ``Subject'' header line if
available. The heuristics here are versatile, but cannot be guaranteed
to be completely failure-proof. If false information is derived, the
parts will be ordered and grouped wrong, resulting in wrong decoding.

If the ``dumbness'' is set to 1, the code to derive a part number is
disabled; it will then be assumed that all parts within a group appear
in correct order: the first one is assigned number 1 etc. However,
part numbers found in MIME-headers are still used (I haven't yet found
a file where these were wrong).

A dumbness of 2 also switches off the code to select a unique
identifier from the subject line. This does still work with
single-part files\footnote{Of course, this option wouldn't make sense
with single-part files, since there's no ``grouping'' involved that
might fail.} and \emph{might} work with multi-part files, as long as
they're in correct order and not mixed. The filename is found on
the first part and then passed on to the following parts.

This option only takes effect for files scanned afterwards.

\item[\texttt{UUOPT\_BRACKPOL}] {\small (integer, default=0)} \\
Series of multi-part postings on the Usenet usually have subject lines
like ``You must see this! [1/3] (2/4)''. How to parse this
information? Is this the second part of four in a series of three
postings, or is it the first of three parts and the second in a series
of four postings? The library cannot know, and simply gives numbers in
() parentheses precedence over number in [] brackets. If this
assumption fails, the parts will be grouped and ordered completely
wrong.

Setting the ``bracket policy'' to 1 changes this precedence.
If now both parentheses and brackets are present, the
numbers within brackets will be evaluated first.

This option only takes effect for files scanned afterwards.

\item[\texttt{UUOPT\_VERBOSE}] {\small (integer, default=1)} \\
If set to 0, the Message Callback will not be bothered with messages
of level
\texttt{UUMSG\ush{}MESSAGE} or
\texttt{UUMSG\ush{}NOTE}.
The default is to generate these messages.

\item[\texttt{UUOPT\_DESPERATE}] {\small (integer, default=0)} \\
By default, the library refuses to decode incomplete files and
generates errors. But if switched into ``desperate mode'' these kinds
of errors are ignored, and all \emph{available} data is decoded.
The usefulness of the resulting corrupt file depends on the type of
the file.

\item[\texttt{UUOPT\_IGNREPLY}] {\small (integer, default=0)} \\
If set to 1, the library will ignore email messages and news postings
which were sent as ``Reply'', since they are less likely to feature
useful data. There's no real reason to turn on this option any more
(earlier versions got easily confused by replies).

\item[\texttt{UUOPT\_OVERWRITE}] {\small (integer, default=1)} \\
When the decoder finds that the target file already exists, it is
simply overwritten silently by default. If this option is set to 0,
the decoder fails instead, generating a
\texttt{UURET\ush{}EXIST} error.

\item[\texttt{UUOPT\_SAVEPATH}] {\small (string, default=(empty))} \\
Without setting this option, files are decoded to the current
directory. This ``save path'' is handled as prefix to each
filename. Because the library does not know about directory layouts,
the resulting filename is simply the concatenation of the save path
and the target file, meaning that the path must include a final
directory separator (slash, backslash, or whatever).

\item[\texttt{UUOPT\_IGNMODE}] {\small (integer, default=0)} \\
Usually, the decoder tries to restore the file mode found on the
``begin'' line of \emph{uuencoded} and \emph{xxencoded} files. This is
turned off if this option is set to 1.

\item[\texttt{UUOPT\_DEBUG}] {\small (integer, default=0)} \\
If set to 1, all messages will be prefixed with the exact sourcecode
location (filename and line number) where they were created. Might be
useful if this is not clear from context.

\item[\texttt{UUOPT\_ERRNO}] {\small (integer, read-only)} \\
This ``option'' can be queried after an operation failed with
\texttt{UURET\ush{}IOERR} and returns the
\texttt{errno} value that originally caused the problem. The ``real''
value of this variable might already be obscured by secondary
problems.

\item[\texttt{UUOPT\_PROGRESS}] {\small (uuprogress, read-only)} \\
Returns the progress structure. This would only make sense in
multi-threaded environments where the decoder runs in one thread and
is controlled from another. Although some care is taken while updating
the structure's values, there might still be synchronization problems.

\item[\texttt{UUOPT\_USETEXT}] {\small (integer, default=0)} \\
If this flag is true, plain text files will be presented for
``decoding''. This includes non-decodeable messages as well as