|
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.
If the progress callback returns non-zero, the operation is interrupted. This feature can be used to implement a "Cancel" button on a GUI progress dialog box.
The progress handler must not do anything that will modify the database connection that invoked the progress handler. Note that sqlite3_prepare_v2() and sqlite3_step() both modify their database connections for the meaning of "modify" in this paragraph.
H12911 | The callback function registered by sqlite3_progress_handler() is invoked periodically during long running calls to sqlite3_step(). |
H12912 | The progress callback is invoked once for every N virtual machine opcodes, where N is the second argument to the sqlite3_progress_handler() call that registered the callback. If N is less than 1, sqlite3_progress_handler() acts as if a NULL progress handler had been specified. |
H12913 | The progress callback itself is identified by the third argument to sqlite3_progress_handler(). |
H12914 | The fourth argument to sqlite3_progress_handler() is a void pointer passed to the progress callback function each time it is invoked. |
H12915 | If a call to sqlite3_step() results in fewer than N opcodes being executed, then the progress callback is never invoked. |
H12916 | Every call to sqlite3_progress_handler() overwrites any previously registered progress handler. |
H12917 | If the progress handler callback is NULL then no progress handler is invoked. |
H12918 |
If the progress callback returns a result other than 0, then
the behavior is a if sqlite3_interrupt() had been called.
|
See also lists of Objects, Constants, and Functions.