開啟 BLOB 以進行增量 I/O

小巧、快速、可靠。
三選一。

SQLite C 介面

開啟 BLOB 以進行增量 I/O

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

此介面會開啟一個控制代碼，指向位於資料庫 zDb 中表格 zTable 的第 iRow 列、zColumn 欄的 BLOB；換句話說，也就是與以下查詢指令所選取的 BLOB 相同：

SELECT zColumn FROM zDb.zTable WHERE rowid = iRow;

參數 zDb 不是包含資料庫的檔案名稱，而是資料庫的符號名稱。對於附加的資料庫，這是 ATTACH 陳述式中 AS 關鍵字後出現的名稱。對於主資料庫檔案，資料庫名稱為 "main"。對於 TEMP 資料表，資料庫名稱為 "temp"。

如果 flags 參數非零，則 BLOB 會以讀寫存取模式開啟。如果 flags 參數為零，則 BLOB 會以唯讀存取模式開啟。

成功時，會回傳 SQLITE_OK，並將新的 BLOB 控制代碼儲存在 *ppBlob 中。否則會回傳錯誤碼，除非錯誤碼為 SQLITE_MISUSE，否則 *ppBlob 會設為 NULL。這表示，只要 API 沒有被誤用，在此函式回傳後，呼叫 *ppBlob 上的 sqlite3_blob_close() 一定是安全的。

如果符合以下任何條件，此函式會以 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() 以及相關函式存取的資料庫連線錯誤碼和訊息。

可以使用 sqlite3_blob_read() 介面讀取 sqlite3_blob_open() 參考的 BLOB，並使用 sqlite3_blob_write() 修改。可以使用 sqlite3_blob_reopen() 介面將 BLOB 控制代碼移動到同一表格的不同列。但是，在開啟 BLOB 控制代碼後，無法變更其欄位、表格或資料庫。

如果 BLOB 控制代碼指向的列被 UPDATE、DELETE 或 ON CONFLICT 副作用修改，則該控制代碼會被標記為「過期」。即使變更的欄位不是 BLOB 控制代碼開啟的欄位，只要該列的任何欄位被變更，此情況就會成立。對過期的 BLOB 控制代碼呼叫 sqlite3_blob_read() 和 sqlite3_blob_write() 會失敗，並回傳 SQLITE_ABORT。在 BLOB 過期之前寫入 BLOB 的變更不會因為 BLOB 過期而回滾。如果交易繼續完成，這些變更最終將會被提交。

使用 sqlite3_blob_bytes() 介面來決定已開啟 BLOB 的大小。此介面無法變更 BLOB 的大小。使用 UPDATE SQL 指令來變更 BLOB 的大小。

sqlite3_bind_zeroblob() 和 sqlite3_result_zeroblob() 介面以及內建的 zeroblob SQL 函式可用於建立零填充的 BLOB，以便使用增量 BLOB 介面進行讀寫。

為了避免資源洩漏，每個開啟的 BLOB 控制代碼 (BLOB handle) 最終都應該透過呼叫 sqlite3_blob_close() 來釋放。

另請參閱：sqlite3_blob_close()、sqlite3_blob_reopen()、sqlite3_blob_read()、sqlite3_blob_bytes()、sqlite3_blob_write()。

另請參閱物件 (Objects)、常數 (Constants) 和函式 (Functions) 列表。