OS Interface File Virtual Methods Object

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标志可能已经或者进入以指示只有文件的数据而不是它的inode需要被同步。

xLock()和xUnlock()的整数值是其中之一

SQLITE_LOCK_NONE,

SQLITE_LOCK_SHARED,

SQLITE_LOCK_RESERVED,

SQLITE_LOCK_PENDING, or

SQLITE_LOCK_EXCLUSIVE.

xLock()会增加锁定。xUnlock()减少锁定。xCheckReservedLock()方法检查在此进程或其他进程中的任何数据库连接是否持有该文件上的RESERVED，PENDING或EXCLUSIVE锁。如果存在这样的锁，它将返回true，否则返回false。

xFileControl()方法是一个通用接口，允许自定义VFS实现使用sqlite3_file_control()接口直接控制打开的文件。第二个“op”参数是一个整数操作码。第三个参数是一个通用指针，用于指向一个结构，该结构可能包含用于写入返回值的参数或空间。xFileControl()的潜在用途可能是启用超时阻塞锁定，更改锁定策略（例如使用点文件锁定），查询锁定状态或打破陈旧锁定的函数。SQLite核心保留所有小于100的操作码供自己使用。小于100的操作码列表可用。定义自定义xFileControl方法的应用程序应使用大于100的操作码以避免冲突。

xSectorSize()方法返回文件底层设备的扇区大小。扇区大小是可以在不干扰文件中的其他字节的情况下执行的最小写入。xDeviceCharacteristics()方法返回描述底层设备行为的位向量：

SQLITE_IOCAP_ATOMIC

SQLITE_IOCAP_ATOMIC512

SQLITE_IOCAP_ATOMIC1K

SQLITE_IOCAP_ATOMIC2K

SQLITE_IOCAP_ATOMIC4K

SQLITE_IOCAP_ATOMIC8K

SQLITE_IOCAP_ATOMIC16K

SQLITE_IOCAP_ATOMIC32K

SQLITE_IOCAP_ATOMIC64K

SQLITE_IOCAP_SAFE_APPEND

SQLITE_IOCAP_SEQUENTIAL

SQLITE_IOCAP_UNDELETABLE_WHEN_OPEN

SQLITE_IOCAP_POWERSAFE_OVERWRITE

SQLITE_IOCAP_IMMUTABLE

SQLITE_IOCAP_BATCH_ATOMIC

SQLITE_IOCAP_ATOMIC属性意味着任何大小的所有写入都是原子的。SQLITE_IOCAP_ATOMICnnn值意味着大小为nnn个字节的块的写入与nnn整数倍的地址对齐是原子的。SQLITE_IOCAP_SAFE_APPEND值意味着，当数据被附加到文件时，数据被首先追加，然后扩展文件的大小，而不是相反。SQLITE_IOCAP_SEQUENTIAL属性表示按照与调用xWrite()相同的顺序将信息写入磁盘。

如果xRead()返回SQLITE_IOERR_SHORT_READ，它也必须用零填充缓冲区的未读部分。无法填充短读取的VFS似乎可行。但是，未能填充短读取数据最终会导致数据库损坏。

本文档系腾讯云开发者社区成员共同维护，如有问题请联系 cloudcommunity@tencent.com

最后更新于：2017-12-18