next up previous
Next: Encoding Functions Up: The UUDeview Decoding Library Previous: General Functions

Decoding Functions

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.


next up previous
Next: Encoding Functions Up: The UUDeview Decoding Library Previous: General Functions
m68k build daemon 2002-04-15