Обратные вызовы прогресса запросов

void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);

Интерфейс sqlite3_progress_handler(D,N,X,P) вызывает функцию обратного вызова X периодически во время длительных вызовов sqlite3_step() и sqlite3_prepare(), и аналогичных для подключения к базе данных D. Пример использования этого интерфейса — обновление графического интерфейса во время выполнения большого запроса.

Параметр P передаётся в качестве единственного параметра функции обратного вызова X. Параметр N — приблизительное количество виртуальных инструкций машины, которые выполняются между последовательными вызовами обратного вызова X. Если N меньше единицы, обработчик прогресса отключается.

Только один обработчик прогресса может быть определён в один момент времени для каждого подключения к базе данных; установка нового обработчика прогресса отменяет старый. Установка параметра X в значение NULL отключает обработчик прогресса. Обработчик прогресса также отключается при установке N со значением меньше 1.

Если функция обратного вызова прогресса возвращает ненулевое значение, операция прерывается. Эта функция может быть использована для реализации кнопки «Отмена» в диалоговом окне прогресса графического интерфейса.

Функция обратного вызова обработчика прогресса не должна выполнять никаких действий, которые изменят подключение к базе данных, вызвавшее обработчик прогресса. Обратите внимание, что sqlite3_prepare_v2() и sqlite3_step() оба изменяют свои подключения к базе данных в смысле «изменение» в этом абзаце.

Функция обратного вызова обработчика прогресса изначально вызывалась только из движка байткода. Она всё ещё может вызываться во время sqlite3_prepare() и аналогичных функций, потому что эти функции могут принудительно перепарсить схему, что включает запуск движка байткода. Однако, начиная с версии SQLite 3.41.0, функция обратного вызова обработчика прогресса может также вызываться непосредственно из sqlite3_prepare() при анализе и генерации кода для сложных запросов.

См. также списки Объектов, Констант и Функций.