library.ltx

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

are used throughout the library. For a full listing of the available
replacement functions, see section \ref{chap-rf}.

However, there are two functions, \texttt{strerror} and
\texttt{tempnam}, that aren't fully implemented. The replacement
\texttt{strerror} does not have a table of error messages and only
produces the error number as string, and the ``fake''
\texttt{tempnam} does not necessarily use a proper temp directory.

Because some functionality is missing, the replacement functions should
\emph{only} be used if the original is not available.
\begin{description}
\item[\texttt{strerror}]
If your system does not provide a \texttt{strerror} function of its
own, define to \texttt{\_FP\_strerror}. This causes the replacement
function to be used throughout the library.
\item[\texttt{tempnam}]
If your system does not provide a \texttt{tempnam} function of its
own, define to \texttt{\_FP\_tempnam}. This causes the replacement
function to be used throughout the library. Must not be defined if the
function is in fact available.
\end{description}

\subsection{Creating the \texttt{Makefile} by hand}

The \texttt{Makefile} is automatically generated by the configuration
script from the template in \texttt{Makefile.in}. This section
explains how the template must be edited into a proper Makefile.

Just copy \texttt{Makefile.in} to \texttt{Makefile} and edit the
place-holders for the following values.
\begin{description}
\item[\texttt{CC}]
Your system's ``C'' compiler.
\item[\texttt{CFLAGS}]
The compilation flags to be passed to the compiler. This must include
``-I.'' so that the include files from the local directory are found,
and ``\mbox{-DHAVE\_CONFIG\_H}'' to declare that a configuration file
is present.
\item[\texttt{RANLIB}]
Set to ``ranlib'' if such a program is available on your system, or to
``:'' (colon) otherwise.
\item[\texttt{VERSION}]
A string holding the release number of the library, currently
``\uuversion{}''
\item[\texttt{PATCH}]
A string holding the patchlevel, currently ``\uupatch{}''.
\end{description}

Some systems do not know Makefiles but offer the concept of a
``project''.\footnote{Actually, most project-oriented systems compile
the project definitions into a Makefile for use by the back-ends.} In
this case, create a new project targeting a library and add all
source codes to the project. Then, make sure that the include path
includes the current directory. Add options to the compiler command
so that the symbol ``HAVE\_CONFIG\_H'' gets defined.
Additionally, the symbol ``VERSION'' must be defined as a
string holding the release number, currently ``\uuversion{}'' and
``PATCH'' must be defined as a string holding the patch level,
currently ``\uupatch{}''.

On 16-bit systems, the package should be compiled using the ``Large''
memory model, so that more than just 64k data space is available.

\subsection{Compiling your Projects}

Compiling the parts of your project that use the functions from the
decoding library is pretty straightforward:
\begin{itemize}
\item All modules that call library functions must include the
\texttt{<uudeview.h>} header file.
\item Optionally, if you want to use the replacement functions to make
your own application more portable, they may also include
\texttt{<fptools.h>}.
\item If your compiler understands about function prototypes, define
the symbol \texttt{PROTOTYPES}. This causes the library functions to
be declared with a full parameter list.
\item Modify the include file search path so that the compiler finds
the include files (usually with the ``-I'' option).
\item Link with the \texttt{libuu.a} library, usually using the
``-luu'' option.
\item Make sure the library is found (usually with the ``-L'' option).
\end{itemize}

\section{Callback Functions}

\subsection{Intro}

At some points, the decoding library offers to call your custom
procedures to do jobs you want to take care of yourself. Some examples
are the ``Message Callback'' to print a message or the ``Busy
Callback'', which is frequently called during lengthy processing
of data to indicate the progress. You can hook up your functions by
calling some library function with a pointer to your function as a
parameter.

In some cases, you will want that one of your functions receives
certain data as a parameter. One reason to achieve this would be
through global data; another possibility is provided through the
passing of an opaque data pointer.

All callback functions are declared to take an additional parameter of
type \texttt{void*}. When hooking up one of your callbacks, you can
specify a value that will passed whenever your function is
called. Since this pointer is never touched by the library, it can be
any kind of data, usually some composed structure. Some application
for the Message Callback might be a \texttt{FILE*} pointer to log the
messages to.

For portability reasons, you should declare your callbacks with the
first parameter actually being a \texttt{void*} pointer and only cast
this pointer to its real type within the function body. This prevents
compiler warnings about the callback setup.

\subsection{Message Callback}
\label{Section-Msg-Callback}

For portability reasons, the library does not assume the availability
of a terminal, so it does not initially know where to print messages
to. The library generates some messages about its progress as well
as more serious warnings and errors. An application should provide a
message callback that displays them. The function might also choose to
ignore informative messages and only display the fatal ones.

A Message Callback takes three parameters. The first one is the opaque
data pointer of type \texttt{void*}. The second one is a text message
of more or less arbitrary length without line breaks. The last
parameter is an indicator of the seriousness of this message. A string
representation of the warning level is also prefixed to the message.
\begin{description}
\item[\texttt{UUMSG\_MESSAGE}]
This is just a plain informative message, nothing important. The
application can choose to simply ignore the message. If a log file
is available, it should be logged, but the message should never result
in a modal dialogue.
\item[\texttt{UUMSG\_NOTE}] ``Note:''
Still an informative message, meaning that the library made a decision
on its own that might interest the user. One example for a note is
that the setuid bit has been stripped from a file mode for security
reasons. Notes are nothing serious and may still be ignored.
\item[\texttt{UUMSG\_WARNING}] ``Warning:''
A warning indicates that a non-serious problem occurred which did not
stop the library from proceeding with the current action. One example
is a temporary file that could not be removed. Warnings should be
displayed, but an application may decide to continue even without user
intervention.
\item[\texttt{UUMSG\_ERROR}] ``ERROR:''
A problem occurred that caused termination of the current request, for
example if the library tried to access a non-existing file. After an
error has occurred, the application should closely examine the
resulting return code of the operation. Error messages are usually
printed in modal dialogues; another option is to save the error
message string somewhere and later print the error message after the
application has examined the operation's return value.
\item[\texttt{UUMSG\_FATAL}] ``Fatal Error:''
This would indicate that a serious problem has occurred that prevents
the library from processing any more requests. Currently unused.
\item[\texttt{UUMSG\_PANIC}] ``Panic:''
Such a message would indicate a panic condition, meaning the
application should terminate without further clean-up handling.
Unused so far.\footnote{It is not intended that this and the previous
error levels will ever be used. Currently, there's no need to include
handling for them.}
\end{description}

\subsection{Busy Callback}
\label{Section-Busy-Callback}

Some library functions, like scanning of an input file or decoding an
output file, can take quite some time. An application will usually
want to inform the user of the progress. A custom ``Busy Callback''
can be provided to take care of this job. This function will then be
called frequently while a large action is being executed within the
library. It is not called when the application itself has control.

Apart from the usual opaque data pointer, the Busy Callback receives a
structure of type \texttt{uuprogress} with the following members:
\begin{description}
\item[\texttt{action}]
What the library is currently doing. One of the following integer
constants:
\begin{description}
\item[\texttt{UUACT\_IDLE}]
The library is idle. This value shouldn't be seen in the Busy
Callback, because the Busy Callback is never called in an idle state.
\item[\texttt{UUACT\_SCANNING}] Scanning an input file.
\item[\texttt{UUACT\_DECODING}] Decoding a file.
\item[\texttt{UUACT\_COPYING}]  Copying a file.
\item[\texttt{UUACT\_ENCODING}] Encoding a file.
\end{description}
\item[\texttt{curfile}]
The name of the file we're working on. May include the full
path. Guaranteed to be 256 characters or shorter.
\item[\texttt{partno}]
When decoding a file, this is the current part number we're working
on. May be zero.
\item[\texttt{numparts}]
The maximum part number of this file. Guaranteed to be positive
(non-zero).
\item[\texttt{percent}]
The percentage of the current \emph{part} already processed. The total
percentage can be calculated as $(100*partno-percent)/numparts$.
\item[\texttt{fsize}]
The size of the current file. The percent information is only valid if
this field is \emph{positive}. Whenever the size of a file cannot be
properly determined, this field is set to -1; in this case, the
percent field may hold garbage.
\end{description}

In some cases, it is possible that the percent counter jumps
backwards. This happens seldom enough not to worry about it, but the
callback should take care not to crash in this case.\footnote{This
happens if, in a MIME multipart posting, the final boundary cannot be
found. After searching the boundary until the end-of-file, the scanner
resets itself to the location of the previous boundary.}

The Busy Callback is declared to return an integer value. If a
\emph{non-zero} value is returned, the current operation from
which the callback was called is canceled, which then aborts with
a return value of \texttt{UURET\ush{}CANCEL} (see later).

\subsection{File Callback}
\label{Section-File-Callback}

Input files are usually needed twice, first for scanning and then for
decoding. If the input files are downloaded from a remote server,
perhaps by \emph{NNTP}, they would have to be stored on the local disk
and await further handling. However, the user may choose not to decode
some files after all.

If disk space is important, it is possible to install a ``File
Callback''. When scanning a file, it is assigned an ``Id''. After
scanning has completed, the application can delete the input file. If
it should be required later on for decoding, the File Callback is
called to map the Id back to a filename, possibly retrieving
another copy and disposing of it afterwards.

The File Callback receives four parameters. The first is the opaque
data pointer, the second is the Id that was assigned to the file while
scanning. The fourth parameter is an integer. If it is non-zero, then
the function is supposed to retrieve the file in question, store it on
local disk, and write the resulting filename into the area to which
the third parameter (a \texttt{char*} pointer) points. A fourth
parameter of zero indicates that the decoder is done handling the
file, so that the function can decide whether or not to remove the
file.

The function must return \texttt{UURET\_OK} upon success, or any other
appropriate error code upon failure.

Since it can usually be assumed that disk space is plentily available,
and storing a file is ``cheaper'' than retrieving it twice, this
mechanism has not been used so far.

\subsection{Filename Filter}
\label{Section-FName-Filter}

For portability reasons, the library does not make any assumptions of
the legality of certain filenames. It will pick up a ``garbage'' file
name from the encoded file and happily use it if not told
otherwise. For example, on DOS systems many filenames must be
truncated in order to be valid.

If a ``Filename Filter'' is installed, the library will pass each
potential filename to the filter and then use the filename that the
filter function returns. The filter also has to remove all directory
information from the filename -- the library itself does not know
about directories at all.

The filter function receives the potential filename as string and must
return a pointer to a string with the corrected filename. It may
either return a pointer to some position in the original string or a
pointer to some static area, but it should not modify the source
string.

Two examples of filename filters can be found among the UUDeview
distribution as \texttt{uufnflt.c}. The DOS filter function disposes
directory information, uses only the first 8 characters of the base
filename and the first three characters after the last '.'~(since a
filename might have two extensions). Also, space characters are
replaced by underscores. The Unix filter just returns a pointer to the