Примените Changeset к базе данных

int sqlite3changeset_apply(
  sqlite3 *db,                    /* Apply change to "main" db of this handle */
  int nChangeset,                 /* Size of changeset in bytes */
  void *pChangeset,               /* Changeset blob */
  int(*xFilter)(
    void *pCtx,                   /* Copy of sixth arg to _apply() */
    const char *zTab              /* Table name */
  ),
  int(*xConflict)(
    void *pCtx,                   /* Copy of sixth arg to _apply() */
    int eConflict,                /* DATA, MISSING, CONFLICT, CONSTRAINT */
    sqlite3_changeset_iter *p     /* Handle describing change and conflict */
  ),
  void *pCtx                      /* First argument passed to xConflict */
);
int sqlite3changeset_apply_v2(
  sqlite3 *db,                    /* Apply change to "main" db of this handle */
  int nChangeset,                 /* Size of changeset in bytes */
  void *pChangeset,               /* Changeset blob */
  int(*xFilter)(
    void *pCtx,                   /* Copy of sixth arg to _apply() */
    const char *zTab              /* Table name */
  ),
  int(*xConflict)(
    void *pCtx,                   /* Copy of sixth arg to _apply() */
    int eConflict,                /* DATA, MISSING, CONFLICT, CONSTRAINT */
    sqlite3_changeset_iter *p     /* Handle describing change and conflict */
  ),
  void *pCtx,                     /* First argument passed to xConflict */
  void **ppRebase, int *pnRebase, /* OUT: Rebase data */
  int flags                       /* SESSION_CHANGESETAPPLY_* flags */
);

Примените changeset или patchset к базе данных. Эти функции пытаются обновить БД "main", присоединенную к db, с изменениями, найденными в changeset, переданном через второй и третий аргументы.

Четвертый аргумент (xFilter), переданный этим функциям, это "отзыв фильтра". Если это не NULL, то для каждой таблицы, затронутой по крайней мере одним изменением в changeset, отзыв фильтра вызван с именем таблицы как второй аргумент и копией указателя контекста, переданного как шестой аргумент, как первый. Если "отзыв фильтра" возвращает ноль, то никакая попытка не предпринята, чтобы применить любые изменения таблицы. Иначе, если возвращаемое значение отличное от нуля, или аргументом xFilter является NULL, все изменения, связанные с таблицей, предприняты.

Для каждой таблицы, которая не исключена отзывом фильтра, эта функция проверяет, что целевая база данных содержит совместимую таблицу. Ее считают совместимой, если все следующее верно:

• У таблицы есть то же самое имя как имя, зарегистрированное в changeset
• У таблицы есть, по крайней мере, столько же колонок, сколько зарегистрировано в changeset
• У таблицы есть колонки первичного ключа в том же самом положении, как зарегистрировано в changeset

Если нет никакого совместимой таблицы, это не ошибка, но ни одно из изменений, связанных с таблицей, не применяется. Предупреждающее сообщение выпущено через механизм sqlite3_log() с кодом ошибки SQLITE_SCHEMA. Самое большее одно такое предупреждение выпущено для каждой таблицы в changeset.

Для каждого изменения, для которого есть совместимая таблица, предпринята попытка изменить содержание таблицы согласно изменению UPDATE, INSERT или DELETE. Если изменение не может быть применено чисто, функция-обработчик конфликта, переданная как пятый аргумент sqlite3changeset_apply(), может быть вызвана. Описание точно, когда обработчик конфликта вызван для каждого типа изменения, ниже.

В отличие от аргумента xFilter, xConflict не может быть передан NULL. Результаты прохождения чего-либо, кроме действительного указателя функции, как аргумент xConflict не определены.

Каждый раз, когда функция-обработчик конфликта вызвана, она должна возвратить одно из SQLITE_CHANGESET_OMIT , SQLITE_CHANGESET_ABORT или SQLITE_CHANGESET_REPLACE. SQLITE_CHANGESET_REPLACE может быть возвращен только если вторым аргументом, переданным обработчику конфликта, является SQLITE_CHANGESET_DATA или SQLITE_CHANGESET_CONFLICT. Если обработчик конфликта возвращает неправильное значение, любые изменения, уже внесенные, отменены, и обращение к sqlite3changeset_apply() вернет SQLITE_MISUSE. Различные меры приняты sqlite3changeset_apply() в зависимости от значения, возвращенного каждым вызовом функции-обработчика конфликта. Обратитесь к документации для трех доступных возвращаемых значений для деталей.

DELETE

Для каждого изменения DELETE функция проверяет, содержит ли целевая база данных строку с тем же самым значением первичного ключа (или значениями), как первоначальные значения строки, сохраненные в changeset. Если это так, и значения, сохраненные во всех колонках непервичного ключа, также соответствуют значениям, сохраненным в changeset, строка удалена из целевой базы данных.

Если строка с соответствием значениям первичного ключа найдена, но одна или больше областей непервичного ключа содержит значение, отличающееся от первоначального значения строки, сохраненной в changeset, функция-обработчик конфликта вызвана с SQLITE_CHANGESET_DATA как второй аргумент. Если у таблицы базы данных есть больше колонок, чем зарегистрировано в changeset, только значения тех областей непервичного ключа сравнены с текущим содержанием базы данных, любые другие колонки таблицы базы данных проигнорированы.

Если никакой строки с соответствием значениям первичного ключа не найдено в базе данных, функция-обработчик конфликта вызвана с SQLITE_CHANGESET_NOTFOUND, переданным как второй аргумент.

Если операция DELETE предпринята, но SQLite возвращает SQLITE_CONSTRAINT (который может произойти только если ограничение внешнего ключа нарушено), функция-обработчик конфликта вызвана с SQLITE_CHANGESET_CONSTRAINT, переданным как второй аргумент. Это включает случай, где операция DELETE предпринята потому что более раннее обращение к функции-обработчику конфликта вернуло SQLITE_CHANGESET_REPLACE.

INSERT

Для каждого изменения INSERT предпринята попытка вставить новую строку в базу данных. Если changeset содержит меньше областей, чем таблица базы данных, дополнительные области наполнены их значениями по умолчанию.

Если попытка вставить строку терпит неудачу, потому что база данных уже содержит строку с теми же самыми значениями первичного ключа, функция-обработчик конфликта вызвана со вторым аргументом SQLITE_CHANGESET_CONFLICT.

Если попытка вставить строку терпит неудачу из-за некоторого другого ограничительного нарушения (например, NOT NULL или UNIQUE), функция-обработчик конфликта вызвана со вторым аргументом SQLITE_CHANGESET_CONSTRAINT. Это включает случай, где операция INSERT повторно предпринята потому, что более раннее обращение к функции-обработчику конфликта вернуло SQLITE_CHANGESET_REPLACE.

UPDATE

Для каждого изменения UPDATE функция проверяет, содержит ли целевая база данных строку с тем же самым значением первичного ключа (или значениями), как первоначальные значения строки, сохраненные в changeset. Если это так, и значения, сохраненные во всех измененных колонках непервичного ключа также соответствуют значениям, сохраненным в changeset, строка обновляется в целевой базе данных.

Если строка с соответствием значениям первичного ключа найдена, но одна или больше измененных областей непервичного ключа содержит значение, отличающееся от первоначального значения строки, сохраненной в changeset, функция-обработчик конфликта вызвана с вторым параметром SQLITE_CHANGESET_DATA. Так как UPDATE содержит только значения для областей непервичного ключа, которые должны быть изменены, только те области должны соответствовать исходным значениям, чтобы избежать отзыва обработчика конфликта SQLITE_CHANGESET_DATA.

Если никакая строка с соответствием значениям первичного ключа не найдена в базе данных, функция-обработчик конфликта вызвана с SQLITE_CHANGESET_NOTFOUND, переданным как второй аргумент.

Если операция UPDATE предпринята, но SQLite возвращает SQLITE_CONSTRAINT, функция-обработчик конфликта вызвана с SQLITE_CHANGESET_CONSTRAINT, переданным как второй аргумент. Это включает случай, где операция UPDATE предпринята после более раннего обращения к функции-обработчику конфликта, вернувшей SQLITE_CHANGESET_REPLACE .

Безопасно выполнить SQL-операторы, включая тех, которые пишут таблицу, связанную с отзывом, из отзыва xConflict. Это может использоваться, чтобы далее настроить стратегию разрешения конфликтов применения.

Все изменения, внесенные этими функциями, приложены в транзакции точки сохранения. Если какая-либо другая ошибка (кроме ограничительной неудачи, пытаясь написать целевой базе данных) происходит, то транзакция точки сохранения отменена, вернув целевую базу данных к ее исходному состоянию и возвратив код ошибки SQLite.

Если параметры вывода (ppRebase) и (pnRebase) не NULL, а вход changeset (не patchset), то sqlite3changeset_apply_v2() может установить (*ppRebase), чтобы указывать на "rebase", которая может использоваться с буфером sqlite3_rebaser API перед возвращением. В этом случае (*pnRebase) установлен в размер буфера в байтах. Ответственность вызывающего в конечном счете освободить любой такой буфер, используя sqlite3_free(). Буфер ассигнован и наполнен только если с одним или более конфликтами столкнулись, применяя patchset. См. комментарии sqlite3_rebaser API.

Поведение sqlite3changeset_apply_v2() может быть изменено, передав комбинацию поддержанных флагов как 9-й параметр.

Обратите внимание на то, что sqlite3changeset_apply_v2() API все еще экспериментален и поэтому подлежит изменению.