setup gui callback for user interaction
If you use the driver from a GUI you might want to react on some events or show the progress of the current operation. The registered callback will be for progress status as well as for user interaction depending on the parameters.
The callback will require a progress dialog if the parameter "progress" is set to anthing else than -1. Developers using this callback to show a progress status should make sure:
The first call must have a progress of 0 and a title is set. Subsequent calls have a progress from 0..100. The msg parameter can be set. The last call must have a progress of 100.
If you supply a pointer to a cancel variable from the first call on, you can cancel the operation if the value of the variable changes from 0 to 1.
Developers implementing the callback function must make sure:
A progress of 0 will setup the progress dialog. Any subsequent progress of 0 is handled like any other progress. The dialog's title is set. If there is a pointer to a cancel variable the dialog should provide a way to cancel the operation. The dialog must make sure ther pointer is valid for subsequent calls. The operation is canceled if "*cancel = 1;" Any subsequent call can have a message parameter, but it mustn't have one. A progress of 100 should remove the progress dialog. There can be subsequent calls with a progress of 100.
A progress of -1 will create a blocking message box. Depending on the pointers ok and cancel the dialog should show ok and cancel button. The integer variables will be set to true or false according to the button pressed.
The supplied void pointer will be passed to every callback call and is free to be used by the GUI for what ever purpose it needs.