Next: File Callback
Up: Callback Functions
Previous: Message Callback
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 uuprogress with the following members:
- action
- What the library is currently doing. One of the following integer
constants:
- 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.
- UUACT_SCANNING
- Scanning an input file.
- UUACT_DECODING
- Decoding a file.
- UUACT_COPYING
- Copying a file.
- UUACT_ENCODING
- Encoding a file.
- curfile
- The name of the file we're working on. May include the full
path. Guaranteed to be 256 characters or shorter.
- partno
- When decoding a file, this is the current part number we're working
on. May be zero.
- numparts
- The maximum part number of this file. Guaranteed to be positive
(non-zero).
- percent
- The percentage of the current part already processed. The total
percentage can be calculated as
2#2.
- fsize
- The size of the current file. The percent information is only valid if
this field is 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.
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.4
The Busy Callback is declared to return an integer value. If a
non-zero value is returned, the current operation from
which the callback was called is canceled, which then aborts with
a return value of UURET-_CANCEL (see later).
Next: File Callback
Up: Callback Functions
Previous: Message Callback
2005-01-11