Now for the more useful functions. The functions within this section
are everything you need to scan and decode files.
- int UULoadFile (char *fname, char *id, int delflag)
-
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 no decodeable data is
found. There is no limit to the number of files.7
If 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 id is
NULL, then the input file must not be deleted or modified
until UUCleanUp has been called.
If delflag is non-zero, the input file will automatically be
removed within 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
delflag is ignored, however, if 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 UUOPT-_FAST. The two most
probable return values are UURET-_OK, indicating
successful completion, or UURET-_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
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.
- uulist * UUGetFileListItem (int num)
-
Returns a pointer to the numth item of the file list. The
elements of this structure are described in section 4.
The list is zero-based. If num is out-of-range, NULL
is returned. Usage of this function is pretty straightforward: loop
with an increasing value until 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.
- int UURenameFile (uulist *item, char *newname)
-
Renames one item of the file list. The old name is discarded and
replaced by 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.
- int UUDecodeToTemp (uulist *item)
-
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 binfile member.
UURET-_OK is returned upon successful completion. Most
other error codes can occur, too. UURET-_NODATA is
returned if you try to decode parts without encoded data or with a
missing beginning (uuencoded and xxencoded files only)
- of course, this condition would also have been obvious from the
state value of the file list structure.
The setting of UUOPT-_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 UURET-_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.
- int UURemoveTemp (uulist *item)
-
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 UUCleanUp. If a decode
operation is called for later on, the file will simply be recreated.
- int UUDecodeFile (uulist *item, char *target)
-
This is the function you have been waiting for. The file is decoded
and copied to its final location. Calling UUDecodeToTemp
beforehand is not required. If 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 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
UUOPT-_OVERWRITE option is checked. If it is false
(zero), then the error UURET-_EXISTS is generated and
decoding fails. If the option is true, the target file is silently
overwritten.8
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.
- int UUInfoFile (uulist *item, void *opaque, int (*func) ())
-
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. func must
be a function with two parameters. The first one is an opaque data
pointer (the value of 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.
- int UUSmerge (int pass)
-
Attempts a ``Smart Merge'' of parts that seem to belong to different
files but which 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 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 pass==0,
then with pass==1 and at last with pass=99.