library.ltx

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

plain-text parts from MIME multipart messages. Since they usually
don't have associated filenames, a unique name will be created from a
sequential four-digit number.

\item[\texttt{UUOPT\_PREAMB}] {\small (integer, default=0)} \\
Whether to use the plain-text preamble and epilogue from MIME
multipart messages. The standard defines they're supposed to
be ignored, so there's no real reason to set this option.

\item[\texttt{UUOPT\_TINYB64}] {\small (integer, default=0)} \\
Support for tiny Base64 data.
If set to off, the scanner does not recognize stand-alone Base64
encoded data with less than 3 lines. The problem is that in some
cases plain text might be misinterpreted as Base64 data, since,
for example, any four-character alphanumerical string like ``Argh''
appearing on a line of its own is valid Base64 data. Since encoded
files are usually longer, and there is considerable confusion about
erroneous Base64 detection, this option is off by default. There's
probably no need to present this option separately to the user. It's
reasonable to associate it with the ``desperate mode'' described
above.

Note that this option only affects \emph{stand-alone} data. Input
from Mime messages with the encoding type correctly specified in
the ``Content-Transfer-Encoding'' header is always evaluated.

There is also no problem with encoding types different than Base64,
since they have an explicit notion of the beginning and end of a
file, and no danger of misinterpretation exists.

\item[\texttt{UUOPT\_ENCEXT}] {\small (string, default=(empty))} \\
When encoding into a file on the local disk, the target files
usually receive an extension composed of the three-digit part
number. This may be considered inappropriate for single-part files.
If this option is set, its value is attached to the base file name as
extension for the target file. A dot `.' is inserted automatically.
When using uuencoding, a sensible value might be ``uue''.

This option does not alter the behaviour on multi-part files, where
the individual parts always receive the three-digit part number as
extension.

\item[\texttt{UUOPT\_REMOVE}] {\small (integer, default=0)} \\
If true, input files are deleted if data was successfully decoded from
them. Be careful with this option, as the library does not care if the
file contains any other useful information besides the decoded
data. And it also does not and can not check the integrity of the
decoded file. Therefore, if in doubt of the incoming data, you should
do a confidence check first and then delete the relevant input files
afterwards. But then, this option was requested by many users.

\item[\texttt{UUOPT\_MOREMIME}] {\small (integer, default=0)} \\
Makes the library behave more MIME-compliant. Normally, some liberties
are taken with seemingly MIME files in order to find encoded data
within it, therefore also finding files within broken MIME
messages. If this option is set to 1, the library is more strict in
its handling of MIME files, and will for example not allow Base 64
data outside of properly tagged subparts, and will not accept
``random'' encoded data.

You can also set the value of this option to 2 to enforce strict MIME
adherance. If the option is 1, the library will still look into plain
text attachments and try to find encoded data within it. This causes
for example uuencoded files that were then sent in a MIME envelope to
be recognized. With an option value of 2, the library won't even do
that, trusting all MIME header information.
\end{description}

\section{General Functions}

After describing all the framework in the previous chapters, it is
time to mention some function calls. Still, the functions presented
here don't actually \emph{do} anything, they just query and modify the
behavior of the core functions.

\begin{description}
\item[\texttt{int UUInitialize (void)}] \hfill{} \\
This function initializes the library and must be called before any
other decoding or encoding function. During initialization, several
arrays are allocated. If memory is exhausted,
\texttt{UURET\ush{}NOMEM} is returned, otherwise the initialization
will return successfully with \texttt{UURET\ush{}OK}.
\item[\texttt{int UUCleanUp (void)}] \hfill{} \\
Cleans up all resources that have been allocated during a program run:
memory structures, temporary files and everything. No library function
may be called afterwards, with the exception of \texttt{UUInitialize}
to start another run.
\item[\texttt{int UUGetOption (int opt, int *ival, char *cval, int len)}] \hfill{} \\
Retrieves the configuration option (see section \ref{Section-Options})
opt. If the option is integer, it is stored in \texttt{ival} (only if
\texttt{ival!=NULL}) and also returned as return value. String options
are copied to \texttt{cval}. Including the final nullbyte, at most
\texttt{len} characters are written to \texttt{cval}. If the progress
information is queried with
\texttt{UUOPT\ush{}PROGRESS}, \texttt{cval} must
point to a \texttt{uuprogress} structure and \texttt{len} must equal
\texttt{sizeof(uuprogress)}.

For integer options, \texttt{cval} may be NULL and \texttt{len} 0 and
vice versa: for string options, \texttt{ival} is not evaluated.
\item[\texttt{int UUSetOption (int opt, int ival, char *cval)}] \hfill{} \\
Sets one of the configuration options. Integer options are set via
\texttt{ival} (\texttt{cval} may be \texttt{NULL}), and string options
are copied from the null-ter\-mina\-ted string \texttt{cval}
(\texttt{ival} may be 0). Returns
\texttt{UURET\ush{}ILLVAL} if you try to set a
read-only value, or \texttt{UURET\_OK} otherwise.
\item[\texttt{char *UUstrerror (int errcode)}] \hfill{} \\
Maps the return values \texttt{UURET\_*} into error messages:
\begin{description}
\item[\texttt{UURET\_OK}] ``OK''
\item[\texttt{UURET\_IOERR}] ``File I/O Error''
\item[\texttt{UURET\_NOMEM}] ``Not Enough Memory''
\item[\texttt{UURET\_ILLVAL}] ``Illegal Value''
\item[\texttt{UURET\_NODATA}] ``No Data found''
\item[\texttt{UURET\_NOEND}] ``Unexpected End of File''
\item[\texttt{UURET\_UNSUP}] ``Unsupported function''
\item[\texttt{UURET\_EXISTS}] ``File exists''
\end{description}
\item[\texttt{int UUSetMsgCallback (void *opaque, void (*func) ())}] \hfill{} \\
Sets the Message Callback function to \texttt{func} (see section
\ref{Section-Msg-Callback}). \texttt{opaque} is the opaque data
pointer that is passed untouched to the callback whenever it is
called. To prevent compiler warnings, a prototype of the callback
should appear before this line. Always returns
\texttt{UURET\ush{}OK}. If \texttt{func==NULL}, the callback is
disabled.
\item[\texttt{int UUSetBusyCallback (void *, void (*func) (), long msecs)}] \hfill{} \\
Sets the Busy Callback function to \texttt{func} (see section
\ref{Section-Busy-Callback}). \texttt{msecs} gives a timespan in
milliseconds; the library will try to call the callback after this
timespan has passed. On some systems, the time can only be queried
with second resolution -- in that case, timing will be quite
inaccurate. The semantics for the other two parameters are the same as
in the previous function. If \texttt{func==NULL}, the busy callback is
disabled.
\item[\texttt{int UUSetFileCallback (void *opaque, int (*func) ())}] \hfill{} \\
Sets the File Callback function to \texttt{func} (see section
\ref{Section-File-Callback}). Semantics identical to the previous
two functions. There is no need to install a file callback if this
feature isn't used.
\item[\texttt{int UUSetFNameFilter (void *opaque, char * (*func) ())}] \hfill{} \\
Sets the Filename Filter function to \texttt{func} (see section
\ref{Section-FName-Filter}). Semantics identical to the previous
three functions. If no filename filter is installed, any filename is
accepted. This may result in failures to write a file because of an
invalid filename.
\item[\texttt{char * UUFNameFilter (char *fname)}] \hfill{} \\
Calls the current filename filter on \texttt{fname}. This function is
provided so that certain parts of applications do not need to know
which filter is currently installed. This is handy for applications
that are supposed to run on more than one system. If no filename
filter is installed, the string itself is returned. Since a filename
filter may return a pointer to static memory or a pointer into the
parameter, the result from this function must not be written to.
\end{description}

\section{Decoding Functions}

Now for the more useful functions. The functions within this section
are everything you need to scan and decode files.

\begin{description}
\item[\texttt{int UULoadFile (char *fname, char *id, int delflag)}] \hfill{} \\
Scans a file for encoded data and inserts the result into the file
list. Each input file must only be scanned once; it may contain many
parts as well as multiple encoded files, thus it is possible that many
decodeable files are found after scanning one input file. On the other
hand it is also possible that \emph{no} decodeable data is
found. There is no limit to the number of files.\footnote{Strictly
speaking, the memory is of course limited. But try to fill a sensible
amount with structures in the 100-byte region.}

If \texttt{id} is non-NULL, its value is used instead of the filename,
and the file callback is used to map the id back into a filename
whenever this input file is needed again. If \texttt{id} \emph{is}
\texttt{NULL}, then the input file must not be deleted or modified
until \texttt{UUCleanUp} has been called.

If \texttt{delflag} is non-zero, the input file will automatically be
removed within \texttt{UUCleanUp}. This is useful when the decoder's
input are also temporary files -- this way, the application can forget
about them right after they're ``loaded''. The value of
\texttt{delflag} is ignored, however, if \texttt{id} is non-NULL;
combining both options does not make sense.

The behavior of this function is influenced by some of the options,
most notably \texttt{UUOPT\ush{}FAST}. The two most
probable return values are \texttt{UURET\ush{}OK}, indicating
successful completion, or \texttt{UURET\ush{}IOERR} in case of some
error while reading the file. The other return values are less likely
to appear.

Note that files are even scheduled for destruction if an error
\emph{did} happen during scanning (with the exception of a file that
could not be opened). But error handling is slightly problematic here
anyway, since it might be possible that useful data was found before
the error occurred.

\item[\texttt{int UULoadFileWithPartNo (char *fname, char *id, int delflag, int partno)}] \hfill{} \\
Same as above, but assigns a part number to the data in the file. This
function can be used if the callee is certain of the part number and
there is thus no need to depend on UUDeview's heuristics. However, it
must not be used if the referenced file may contain more than one
piece of encoded data.

\item[\texttt{uulist * UUGetFileListItem (int num)}] \hfill{} \\
Returns a pointer to the \texttt{num}th item of the file list. The
elements of this structure are described in section \ref{file-list}.
The list is zero-based. If \texttt{num} is out-of-range, \texttt{NULL}
is returned. Usage of this function is pretty straightforward: loop
with an increasing value until \texttt{NULL} is returned. The
structure must not be modified by the application itself. Also, none
of the structure's value should be ``cached'' elsewhere, as they are
not constant: they may change after each loaded file.

\item[\texttt{int UURenameFile (uulist *item, char *newname)}] \hfill{} \\
Renames one item of the file list. The old name is discarded and
replaced by \texttt{newname}. The new name is copied and may thus
point to volatile memory. The name should be a local filename without
any directory information, which would be stripped by the filename
filter anyway.

\item[\texttt{int UUDecodeToTemp (uulist *item)}] \hfill{} \\
Decodes the given item of the file list and places the decoded output
into a temporary file. This is intended to allow ``previews'' of an
encoded file without copying it to its final location (which would
probably overwrite other files). The name of the temporary file can be
retrieved afterwards by re-retrieving the node of the file list and
looking at its \texttt{binfile} member.

\texttt{UURET\ush{}OK} is returned upon successful completion. Most
other error codes can occur, too. \texttt{UURET\ush{}NODATA} is
returned if you try to decode parts without encoded data or with a
missing beginning (\emph{uuencoded} and \emph{xxencoded} files only)
-- of course, this condition would also have been obvious from the
\texttt{state} value of the file list structure.

The setting of \texttt{UUOPT\ush{}DESPERATE} changes the behavior if
an unexpected end of file was found (usually meaning that one or more
parts are missing). Normally, the partially-written target file is
removed and the value \texttt{UURET\ush{}NOEND} is returned. In
desperate mode, the same error code is returned, but the target file
is not removed.

The target file is removed in all other error conditions.

\item[\texttt{int UURemoveTemp (uulist *item)}] \hfill{} \\
After a file has been decoded into a temporary file and is needed no
longer, this function can be called to free the disk space immediately
instead of having to wait until \texttt{UUCleanUp}. If a decode
operation is called for later on, the file will simply be recreated.

\item[\texttt{int UUDecodeFile (uulist *item, char *target)}] \hfill{} \\
This is the function you have been waiting for. The file is decoded
and copied to its final location. Calling \texttt{UUDecodeToTemp}
beforehand is not required. If \texttt{target} is non-NULL, then it is
immediately used as filename for the target file (without prepending
the save path and without passing it through the filename
filter). Otherwise, if \texttt{target==NULL}, the final filename is
composed by concatenating the save path and the result of the filename
filter used upon the filename found in the encoded file.

If the target file already exists, the value of the
\texttt{UUOPT\ush{}OVERWRITE} option is checked. If it is false
(zero), then the error \texttt{UURET\ush{}EXISTS} is generated and
decoding fails. If the option is true, the target file is silently
overwritten.\footnote{If we don't have permission to overwrite the
target file, an I/O error is generated.}

The file is first decoded into a temporary file, then the temporary
file is copied to the final location. This is done to prevent
overwriting target files with data that turns out too late to be
invalid.

\item[\texttt{int UUInfoFile (uulist *item, void *opaque, int (*func) ())}] \hfill{} \\
This function can be used to query information about the encoded
file. This is either the zeroth part of a file if available, or the
beginning of the first part up to the encoded data otherwise. Once
again, a callback function is used to do the job. \texttt{func} must
be a function with two parameters. The first one is an opaque data