|
A restore progress callback mechanism has been added to the SAT/SAB restore functionality. This callback provides the restore progress information needed by an application to implement a progress widget. An example of how the data can be used to implement a Windows progress bar is included in the scm/main/windows/wstdio.cxx source file.
|
|
|
The progress mechanism uses either the entity count or the size of the restore file to measure progress. When the entity count is available it is used by default. Otherwise an attempt is made to acquire the restore file size, and if successful is used to measure progress. The customer can change the progress measurement by setting a custom file size during the very first call to the callback function. This is useful when the file size was not obtainable or the customer has a better understanding of the ACIS data block within the restore file that possibly contains customer data or multiple ACIS data blocks.
|
|
|
The callback frequency can be managed by the customer and is by default set to cause the callback to get called roughly every percent. This can be set to cause the callback to get called more or less often as desired.
|
|
|
The callback mechanism is enabled by installing a custom callback function with the set_restore_progress_callback function. The set_restore_progress_callback function accepts one argument, which is the custom callback function.
|
|
|
An example call to install the callback looks like this:
|
|
|
set_restore_progress_callback( my_restore_progress_callback);
|
|
|
The installed callback function will be called during every restore operation unless it is either disabled (discussed later) or uninstalled by calling the set_restore_progress_callback with a NULL argument.
|
|
|
An example call to uninstall the callback looks like this:
|
|
|
set_restore_progress_callback(NULL);
|
|
|
The custom callback prototype is typedefed to proc_restore_progress_callback in the savres.hxx header. The function receives a pointer to a restore_progress_data object, which provides all of the progress information, as an argument and returns an integer as a success indicator.
|
|
|
A simple example of a custom callback implementation looks like this:
|
|
|
#include "kernel/acis.hxx"
|
|
#include "kernel/kerndata/savres/savres.hxx"
|
|
|
|
int my_restore_progress_callback( restore_progress_data * pd) { }
|
|
|
The restore_progress_data object has 4 methods available to the application that can be used to modify the default behavior of the callback and to retrieve the progress data. They are public exported methods of the restore_progress_data class and have the following signatures:
|
|
|
int count() const;
|
|
int index() const;
|
|
int size( int input_size = -1);
|
|
int interval( int input_interval = -1);
|
|
|
The count method returns a positive integer count that is either the number of entities to restore or the size of the restore file when the entity count is not available, or a zero when none of this information is available or obtainable.
|
|
|
An example call looks like this:
|
|
|
if( pd->count() > 0 ) { }
|
|
|
The index method returns a positive integer of the achieved progress, which can be either the number of entities restored or the number of bytes read from the file, or a zero on the very first callback call. The customer can modify the progress measurement during the very first call as mentioned above.
|
|
|
An example call looks like this:
|
|
|
if( pd->index() == 0 ) { } // first call
|
|
|
The size method returns a positive integer of the acquired size of the restore file, or a zero if the entity count is available or the file size could not be obtained. The size method accepts an integer input size from the customer on the very first callback call useful to replace the default restore measurement.
|
|
|
An example call looks like this:
|
|
|
if( pd->size() > 250000 ) {} // file size greater than 250000 bytes
|
|
|
The interval method returns a positive integer indicating the current callback frequency, which is set to 1 by default. The method accepts an integer indicating the customer desired callback frequency on the very first call to the callback. A frequency of 1 causes the callback to get called roughly every percent. A frequency of 2 causes the callback to get called for every entity restored, which could be quite often. Setting the frequency to zero will disable the callback for this restore only.
|
|
|
An example call looks like this:
|
|
|
if( pd->size() > 0 && pd->size() < 250000 )
|
|
|
// don't bother with the progress meter if the restore is minimal
|
|
pd->interval(0);
|
|
|
else
|
|
|
|
pd->interval(1);
|
|
|
Alternatively, one can simply return a -1 from the custom callback to disable the callback for the current restore.
|