Перехват перед обновлением

#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() регистрирует функцию обратного вызова, которая вызвана до каждого INSERT, UPDATE и DELETE на таблице базы данных. Самое большее один перехват перед обновлением может быть зарегистрирован за один раз на связи единой базы данных, каждый вызов sqlite3_preupdate_hook() отвергает предыдущее урегулирование. Перехват перед обновлением отключен sqlite3_preupdate_hook() с NULL как второй параметр. Через третий параметр sqlite3_preupdate_hook() передают первый параметр к отзывам.

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

Второй параметр отзыва перед обновлением это указатель на соединение с базой данных, которое зарегистрировало перехват перед обновлением. Третий параметр к отзыву перед обновлением это одна из констант SQLITE_INSERT, SQLITE_DELETE или SQLITE_UPDATE, чтобы определить вид операции по обновлению, которая собирается произойти. Четвертый параметр отзыва перед обновлением задает название базы данных в рамках соединения с базой данных, которое изменяется. Это будет "main" для главной базы данных, "temp" для таблиц TEMP или имя, данное после ключевого слова AS в ATTACH. Пятый параметр определяет название таблицы, которая изменяется.

Для UPDATE или DELETE на таблице rowid шестой параметр0 является начальным rowid строки, изменяемой или удаленной. Для операции INSERT на таблице rowid или любой операции на таблице WITHOUT ROWID значение шестого параметра не определена. Для INSERT или UPDATE на таблице rowid седьмой параметр указывает финальное значение rowid строки, вставляемой или обновленной. Значение седьмого параметра, переданного к функции обратного вызова, не определяется для операций на таблицах WITHOUT ROWID или для DELETE на таблицах rowid.

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 указатель на protected sqlite3_value, который содержит значение столбца N строки таблицы, прежде чем это будет обновлено. Параметр N должен быть между 0 и меньше, чем количество колонок, или поведение будет не определено. Это должно использоваться только в SQLITE_UPDATE и SQLITE_DELETE, если это используется отзывом SQLITE_INSERT, поведение не определено. sqlite3_value, на который указывает P, будет разрушен, когда отзыв перед обновлением возвратит значение.

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

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

Когда sqlite3_blob_write() API используется, чтобы обновить колонку blob, перехват перед обновлением вызван с SQLITE_DELETE. Это вызвано тем, что в этом случае новые значения недоступны. В этом случае, когда отзыв, сделанный с op==SQLITE_DELETE, на самом деле пишет через sqlite3_blob_write() API, sqlite3_preupdate_blobwrite() возвращает индекс написанной колонки. В других случаях, где перехват перед обновлением вызывается по некоторой другой причине, включая регулярный DELETE, sqlite3_preupdate_blobwrite() вернет -1.

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