Открытие BLOB для инкрементального ввода/вывода

int sqlite3_blob_open(
  sqlite3*,
  const char *zDb,
  const char *zTable,
  const char *zColumn,
  sqlite3_int64 iRow,
  int flags,
  sqlite3_blob **ppBlob
);

Этот интерфейс открывает дескриптор BLOB, расположенного в строке iRow, столбце zColumn, таблице zTable в базе данных zDb; другими словами, тот же самый BLOB, который был бы выбран следующим образом:

SELECT zColumn FROM zDb.zTable WHERE rowid = iRow;

Параметр zDb — это не имя файла, содержащий базу данных, а символическое имя базы данных. Для присоединённых баз данных это имя, которое отображается после ключевого слова AS в операторе ATTACH. Для основного файла базы данных имя базы данных — "main". Для временных таблиц имя базы данных — "temp".

Если параметр flags не равен нулю, то BLOB открывается для чтения и записи. Если параметр flags равен нулю, то BLOB открывается только для чтения.

При успешном выполнении возвращается SQLITE_OK, и новый дескриптор BLOB сохраняется в *ppBlob. В противном случае возвращается код ошибки, и, за исключением случая ошибки SQLITE_MISUSE, *ppBlob устанавливается в значение NULL. Это означает, что, при условии корректного использования API, всегда безопасно вызывать sqlite3_blob_close() для *ppBlob после возвращения этой функции.

Эта функция завершается с ошибкой SQLITE_ERROR, если выполняется любое из следующих условий:

• База данных zDb не существует,
• Таблица zTable не существует в базе данных zDb,
• Таблица zTable является таблицей WITHOUT ROWID,
• Столбец zColumn не существует,
• Строка iRow отсутствует в таблице,
• Указанный столбец строки iRow содержит значение, которое не является значением типа TEXT или BLOB,
• Столбец zColumn является частью индекса, PRIMARY KEY или UNIQUE ограничения, и BLOB открывается для чтения/записи,
• Ограничения внешнего ключа включены, столбец zColumn является частью определения ключа-потомка, и BLOB открывается для чтения/записи.

Если функция не возвращает SQLITE_MISUSE, она устанавливает код ошибки и сообщение об ошибке соединения с базой данных, доступные через sqlite3_errcode() и sqlite3_errmsg() и связанные функции.

BLOB, на который ссылается функция sqlite3_blob_open(), может быть прочитан с помощью интерфейса sqlite3_blob_read() и изменён с помощью интерфейса sqlite3_blob_write(). Дескриптор BLOB может быть перемещён в другую строку той же таблицы с помощью интерфейса sqlite3_blob_reopen(). Однако столбец, таблица или база данных дескриптора BLOB не могут быть изменены после открытия дескриптора BLOB.

Если строка, на которую указывает дескриптор BLOB, изменяется с помощью UPDATE, DELETE или с помощью ON CONFLICT побочных эффектов, то дескриптор BLOB помечается как "просроченный". Это верно, если изменяется любой столбец строки, даже столбец, отличный от того, на котором открыт дескриптор BLOB. Вызовы sqlite3_blob_read() и sqlite3_blob_write() для просроченного дескриптора BLOB завершаются ошибкой с кодом возврата SQLITE_ABORT. Изменения, внесённые в BLOB до истечения срока действия BLOB, не отменяются истечением срока действия BLOB. Такие изменения в конечном итоге будут сохранены, если транзакция завершится успешно.

Используйте интерфейс sqlite3_blob_bytes() для определения размера открытого BLOB. Размер BLOB не может быть изменён с помощью этого интерфейса. Используйте оператор SQL UPDATE для изменения размера BLOB.

Интерфейсы sqlite3_bind_zeroblob() и sqlite3_result_zeroblob(), а также встроенная функция SQL zeroblob могут быть использованы для создания заполненного нулями BLOB для чтения или записи с помощью интерфейса инкрементального BLOB.

Для предотвращения утечки ресурсов каждый открытый дескриптор BLOB должен быть закрыт вызовом sqlite3_blob_close().

См. также: sqlite3_blob_close(), sqlite3_blob_reopen(), sqlite3_blob_read(), sqlite3_blob_bytes(), sqlite3_blob_write().

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