作業系統介面檔案虛擬方法物件 (OS 介面檔案虛擬方法物件)

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

SQLite C 介面

作業系統介面檔案虛擬方法物件 (OS 介面檔案虛擬方法物件)

typedef struct sqlite3_io_methods sqlite3_io_methods;
struct sqlite3_io_methods {
  int iVersion;
  int (*xClose)(sqlite3_file*);
  int (*xRead)(sqlite3_file*, void*, int iAmt, sqlite3_int64 iOfst);
  int (*xWrite)(sqlite3_file*, const void*, int iAmt, sqlite3_int64 iOfst);
  int (*xTruncate)(sqlite3_file*, sqlite3_int64 size);
  int (*xSync)(sqlite3_file*, int flags);
  int (*xFileSize)(sqlite3_file*, sqlite3_int64 *pSize);
  int (*xLock)(sqlite3_file*, int);
  int (*xUnlock)(sqlite3_file*, int);
  int (*xCheckReservedLock)(sqlite3_file*, int *pResOut);
  int (*xFileControl)(sqlite3_file*, int op, void *pArg);
  int (*xSectorSize)(sqlite3_file*);
  int (*xDeviceCharacteristics)(sqlite3_file*);
  /* Methods above are valid for version 1 */
  int (*xShmMap)(sqlite3_file*, int iPg, int pgsz, int, void volatile**);
  int (*xShmLock)(sqlite3_file*, int offset, int n, int flags);
  void (*xShmBarrier)(sqlite3_file*);
  int (*xShmUnmap)(sqlite3_file*, int deleteFlag);
  /* Methods above are valid for version 2 */
  int (*xFetch)(sqlite3_file*, sqlite3_int64 iOfst, int iAmt, void **pp);
  int (*xUnfetch)(sqlite3_file*, sqlite3_int64 iOfst, void *p);
  /* Methods above are valid for version 3 */
  /* Additional methods may be added in future releases */
};

每個透過 sqlite3_vfs.xOpen 方法開啟的檔案都會填入一個 sqlite3_file 物件（或者更常見的是 sqlite3_file 物件的子類別），並指向此物件的實例。這個物件定義了用於對由 sqlite3_file 物件表示的已開啟檔案執行各種操作的方法。

如果 sqlite3_vfs.xOpen 方法將 sqlite3_file.pMethods 元素設定為非 NULL 指標，則即使 sqlite3_vfs.xOpen 回報失敗，也可能會呼叫 sqlite3_io_methods.xClose 方法。防止在 sqlite3_vfs.xOpen 失敗後呼叫 xClose 的唯一方法是讓 sqlite3_vfs.xOpen 將 sqlite3_file.pMethods 元素設定為 NULL。

xSync 的 flags 參數可以是 SQLITE_SYNC_NORMAL 或 SQLITE_SYNC_FULL。第一個選項是普通的 fsync()。第二個選項是 Mac OS X 風格的 fullsync。SQLITE_SYNC_DATAONLY 旗標可以透過 OR 運算加入，表示只需要同步檔案的數據，而不需要同步其 inode。

xLock() 和 xUnlock() 的整數值是以下其中之一：

xLock() 升級資料庫檔案鎖定。換句話說，xLock() 將資料庫檔案鎖定從 NONE 向 EXCLUSIVE 方向移動。 xLock() 的參數始終是 SHARED、RESERVED、PENDING 或 EXCLUSIVE 其中之一，絕不會是 SQLITE_LOCK_NONE。如果資料庫檔案鎖定已經達到或高於請求的鎖定，則呼叫 xLock() 沒有任何作用。xUnlock() 將資料庫檔案鎖定降級為 SHARED 或 NONE。如果鎖定已經達到或低於請求的鎖定狀態，則呼叫 xUnlock() 沒有任何作用。 xCheckReservedLock() 方法檢查是否有任何資料庫連線（在此程序中或在其他程序中）持有檔案的 RESERVED、PENDING 或 EXCLUSIVE 鎖定。如果存在此類鎖定，則返回 true，否則返回 false。

xFileControl() 方法是一個通用介面，允許自定義 VFS 實作使用 sqlite3_file_control() 介面直接控制已開啟的檔案。第二個「op」參數是一個整數操作碼。第三個參數是一個通用指標，旨在指向一個結構，該結構可能包含參數或用於寫入返回值的空間。 xFileControl() 的潛在用途可能是啟用具有逾時的阻塞鎖定、更改鎖定策略（例如使用點檔案鎖定）、查詢鎖定狀態或打破過時鎖定的函數。 SQLite 核心保留所有小於 100 的操作碼供自己使用。提供了小於 100 的操作碼列表。定義自定義 xFileControl 方法的應用程式應使用大於 100 的操作碼，以避免衝突。 VFS 實作應為其無法識別的檔案控制操作碼返回 SQLITE_NOTFOUND。

xSectorSize() 方法返回檔案底層裝置的扇區大小。扇區大小是不會干擾檔案中其他位元組的最小寫入量。 xDeviceCharacteristics() 方法返回一個位向量，描述底層裝置的行為

SQLITE_IOCAP_ATOMIC 屬性表示任何大小的寫入都是原子性的。SQLITE_IOCAP_ATOMICnnn 值表示寫入大小為 nnn 位元組且地址對齊為 nnn 整數倍的區塊是原子性的。SQLITE_IOCAP_SAFE_APPEND 值表示當資料附加到檔案時，會先附加資料，然後再擴展檔案大小，絕不會反過來。SQLITE_IOCAP_SEQUENTIAL 屬性表示資訊寫入磁碟的順序與呼叫 xWrite() 的順序相同。

如果 xRead() 返回 SQLITE_IOERR_SHORT_READ，它也必須用零填充緩衝區中未讀取的部分。一個未能以零填充短讀的 VFS 可能看起來可以正常運作。然而，未能以零填充短讀最終將導致資料庫損毀。

另請參閱物件、常數和函式的列表。