Обработчик предварительного обновления

Обработчик предварительного обновления.

#if defined(SQLITE_ENABLE_PREUPDATE_HOOK)
void *sqlite3_preupdate_hook(
  sqlite3 *db,
  void(*xPreUpdate)(
    void *pCtx,                   /* Copy of third arg to preupdate_hook() */
    sqlite3 *db,                  /* Database handle */
    int op,                       /* SQLITE_UPDATE, DELETE or INSERT */
    char const *zDb,              /* Database name */
    char const *zName,            /* Table name */
    sqlite3_int64 iKey1,          /* Rowid of row about to be deleted/updated */
    sqlite3_int64 iKey2           /* New rowid value (for a rowid UPDATE) */
  ),
  void*
);
int sqlite3_preupdate_old(sqlite3 *, int, sqlite3_value **);
int sqlite3_preupdate_count(sqlite3 *);
int sqlite3_preupdate_depth(sqlite3 *);
int sqlite3_preupdate_new(sqlite3 *, int, sqlite3_value **);
int sqlite3_preupdate_blobwrite(sqlite3 *);
#endif

Эти интерфейсы доступны только в том случае, если SQLite скомпилирован с опцией SQLITE_ENABLE_PREUPDATE_HOOK на этапе компиляции.

Интерфейс sqlite3_preupdate_hook() регистрирует функцию обратного вызова, которая вызывается перед каждой операцией ВСТАВКИ, ОБНОВЛЕНИЯ и УДАЛЕНИЯ в таблице базы данных. В одно время на одном соединении с базой данных может быть зарегистрирован только один обработчик предварительного обновления; каждый вызов sqlite3_preupdate_hook() перезаписывает предыдущее значение. Обработчик предварительного обновления отключается путем вызова sqlite3_preupdate_hook() со значением NULL в качестве второго параметра. Третий параметр sqlite3_preupdate_hook() передается в качестве первого параметра функциям обратного вызова.

Обработчик предварительного обновления срабатывает только для изменений в реальных таблицах базы данных; обработчик предварительного обновления не вызывается для изменений в виртуальных таблицах или в системных таблицах, таких как sqlite_sequence или sqlite_stat1.

Второй параметр обратного вызова предварительного обновления — указатель на соединение с базой данных, которое зарегистрировало обработчик предварительного обновления. Третий параметр обратного вызова предварительного обновления — одна из констант SQLITE_INSERT, SQLITE_DELETE или SQLITE_UPDATE для определения типа операции обновления, которая будет выполняться. Четвертый параметр обратного вызова предварительного обновления — имя базы данных в рамках соединения с базой данных, которая изменяется. Это будет «main» для основной базы данных или «temp» для временных таблиц, или имя, заданное после ключевого слова AS в операторе ПРИСОЕДИНЕНИЕ для подключенных баз данных. Пятый параметр обратного вызова предварительного обновления — имя таблицы, которая изменяется.

При операции UPDATE или DELETE в таблице с идентификатором строки шестым параметром, передаваемым в обработчик предварительного обновления, является начальный идентификатор строки изменяемой или удаляемой строки. При операции ВСТАВКИ в таблицу с идентификатором строки или любой операции в таблице БЕЗ ИДЕНТИФИКАТОРА СТРОКИ значение шестого параметра не определено. При операции ВСТАВКИ или UPDATE в таблице с идентификатором строки седьмым параметром является конечное значение идентификатора строки вставляемой или обновляемой строки. Значение седьмого параметра, переданного в функцию обратного вызова, не определено для операций в таблицах БЕЗ ИДЕНТИФИКАТОРА СТРОКИ или для операций УДАЛЕНИЯ в таблицах с идентификатором строки.

Функция sqlite3_preupdate_hook(D,C,P) возвращает аргумент P из предыдущего вызова на том же соединении с базой данных D или NULL для первого вызова на D.

Интерфейсы sqlite3_preupdate_old(), sqlite3_preupdate_new(), sqlite3_preupdate_count() и sqlite3_preupdate_depth() предоставляют дополнительную информацию о событии предварительного обновления. Эти функции могут быть вызваны только изнутри функции обратного вызова предварительного обновления. Вызов любой из этих функций извне функции обратного вызова предварительного обновления или с указателем соединения с базой данных, отличным от переданного в функцию обратного вызова предварительного обновления, приводит к неопределенному и, вероятно, нежелательному поведению.

Интерфейс sqlite3_preupdate_count(D) возвращает количество столбцов в строке, которая вставляется, обновляется или удаляется.

Интерфейс sqlite3_preupdate_old(D,N,P) записывает в P указатель на защищенный sqlite3_value, содержащий значение N-го столбца строки таблицы до ее обновления. Параметр N должен быть от 0 до числа столбцов минус один, иначе поведение будет неопределенным. Это должно использоваться только в функциях обратного вызова предварительного обновления SQLITE_UPDATE и SQLITE_DELETE; если это используется в функции обратного вызова SQLITE_INSERT, то поведение неопределенно. sqlite3_value, на который указывает P, будет уничтожен при возвращении функции обратного вызова предварительного обновления.

Интерфейс sqlite3_preupdate_new(D,N,P) записывает в P указатель на защищенный sqlite3_value, содержащий значение N-го столбца строки таблицы после ее обновления. Параметр N должен быть от 0 до числа столбцов минус один, иначе поведение будет неопределенным. Это должно использоваться только в функциях обратного вызова предварительного обновления SQLITE_INSERT и SQLITE_UPDATE; если это используется в функции обратного вызова SQLITE_DELETE, то поведение неопределенно. sqlite3_value, на который указывает P, будет уничтожен при возвращении функции обратного вызова предварительного обновления.

Интерфейс sqlite3_preupdate_depth(D) возвращает 0, если функция обратного вызова предварительного обновления была вызвана в результате прямой операции вставки, обновления или удаления; 1 для вставок, обновлений или удалений, вызываемых триггерами верхнего уровня; или 2 для изменений, вызванных триггерами, вызываемыми триггерами верхнего уровня; и так далее.

При использовании API sqlite3_blob_write() для обновления столбца BLOB функция предварительного обновления вызывается с SQLITE_DELETE. Это связано с тем, что в этом случае новые значения недоступны. В этом случае, когда обратный вызов, сделанный с op==SQLITE_DELETE, на самом деле является записью с использованием API sqlite3_blob_write(), sqlite3_preupdate_blobwrite() возвращает индекс записываемого столбца. В других случаях, когда функция предварительного обновления вызывается по какой-либо другой причине, включая обычное УДАЛЕНИЕ, sqlite3_preupdate_blobwrite() возвращает -1.

См. также: sqlite3_update_hook()

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