|
void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
This routine configures a callback function - the progress callback - that is invoked periodically during long running calls to sqlite3_exec(), sqlite3_step() and sqlite3_get_table(). An example use for this interface is to keep a GUI updated during a large query.
The progress callback is invoked once for every N virtual machine opcodes, where N is the second argument to this function. The progress callback itself is identified by the third argument to this function. The fourth argument to this function is a void pointer passed to the progress callback function each time it is invoked.
If a call to sqlite3_exec(), sqlite3_step(), or sqlite3_get_table() results in fewer than N opcodes being executed, then the progress callback is never invoked.
Only a single progress callback function may be registered for each open database connection. Every call to sqlite3_progress_handler() overwrites the results of the previous call. To remove the progress callback altogether, pass NULL as the third argument to this function.
If the progress callback returns a result other than 0, then the current query is immediately terminated and any database changes rolled back. The containing sqlite3_exec(), sqlite3_step(), or sqlite3_get_table() call returns SQLITE_INTERRUPT. This feature can be used, for example, to implement the "Cancel" button on a progress dialog box in a GUI.
See also lists of Objects, Constants, and Functions.