操作系统接口对象

Small. Fast. Reliable.
Choose any three.

SQLite C接口

操作系统接口对象

typedef struct sqlite3_vfs sqlite3_vfs;
typedef void（* sqlite3_syscall_ptr）（void）;
struct sqlite3_vfs {
  int iVersion; / *结构版本号（当前为3）* /
  int szOsFile; / *子类化sqlite3_file的大小* /
  int mxPathname; / *最大文件路径名长度* /
  sqlite3_vfs * pNext; / *下一个注册的VFS * /
  const char * zName; / *此虚拟文件系统的名称* /
  无效* pAppData; / *指向特定于应用程序的数据的指针* /
  int（* xOpen）（sqlite3_vfs *，const char * zName，sqlite3_file *，
               int标志，int * pOutFlags）;
  int（* xDelete）（sqlite3_vfs *，const char * zName，int syncDir）;
  int（* xAccess）（sqlite3_vfs *，const char * zName，int flags，int * pResOut）;
  int（* xFullPathname）（sqlite3_vfs *，const char * zName，int nOut，char * zOut）;
  无效*（* xDlOpen）（sqlite3_vfs *，const char * zFilename）;
  void（* xDlError）（sqlite3_vfs *，int nByte，char * zErrMsg）;
  void（*（* xDlSym）（sqlite3_vfs *，void *，const char * zSymbol））（无效）;
  void（* xDlClose）（sqlite3_vfs *，void *）;
  int（* xRandomness）（sqlite3_vfs *，int nByte，char * zOut）;
  int（* xSleep）（sqlite3_vfs *，int微秒）;
  int（* xCurrentTime）（sqlite3_vfs *，double *）;
  int（* xGetLastError）（sqlite3_vfs *，int，char *）;
  / *
  **上面的方法在sqlite_vfs对象的版本1中
  ** 定义。第二版或更高版本中添加了以下内容
  * /
  int（* xCurrentTimeInt64）（sqlite3_vfs *，sqlite3_int64 *）;
  / *
  **上面的方法在sqlite_vfs对象的版本1和2中。
  **以下内容适用于版本3和更高版本。
  * /
  int（* xSetSystemCall）（sqlite3_vfs *，const char * zName，sqlite3_syscall_ptr）;
  sqlite3_syscall_ptr（* xGetSystemCall）（sqlite3_vfs *，const char * zName）;
  const char *（* xNextSystemCall）（sqlite3_vfs *，const char * zName）;
  / *
  **上面的方法在sqlite_vfs对象的版本1到版本3中。
  **新字段可能会在将来的版本中附加。iVersion
  **值会在发生这种情况时增加。
  * /
};

sqlite3_vfs对象的实例定义SQLite核心与基础操作系统之间的接口。对象名称中的“ vfs”代表“虚拟文件系统”。有关更多信息，请参见VFS文档。

有时会通过在末尾添加新方法来扩展VFS接口。每次发生此类扩展时，iVersion字段都会增加。iVersion值在2007-09-04的SQLite 3.5.0版中从1开始，然后在2010-07-21的SQLite 3.7.0版中增加到2 ，然后在2011年的SQLite 3.7.6版中增加到3 。 -04-12。其他字段可能会附加到sqlite3_vfs对象，并且在将来的SQLite版本中iVersion值可能会再次增加。请注意，由于疏忽，sqlite3_vfs对象的结构在2008年7月16日从SQLite版本3.5.9过渡到版本3.6.0时发生了变化，但iVersion字段并未增加。

szOsFile字段是此VFS使用的子类sqlite3_file结构的大小。mxPathname是此VFS中路径名的最大长度。

已注册的sqlite3_vfs对象保留在由pNext指针形成的链接列表上。该sqlite3_vfs_register（）和sqlite3_vfs_unregister（）接口管理该名单的线程安全的方式。该sqlite3_vfs_find（）接口搜索列表。应用程序代码或VFS实现均不应使用pNext指针。

pNext字段是sqlite3_vfs结构中SQLite会修改的唯一字段。SQLite将仅在持有特定的静态互斥锁的同时访问或修改此字段。一旦注册了对象，应用程序就永远不要修改sqlite3_vfs对象内的任何内容。

zName字段保存VFS模块的名称。该名称在所有VFS模块中必须唯一。

SQLite保证xOpen的zFilename参数是NULL指针或从xFullPathname（）获得的字符串，并添加了可选的后缀。如果将后缀添加到zFilename参数，它将由单个“-”字符组成，后跟不超过11个字母数字和/或“-”字符。SQLite进一步保证该字符串在调用xClose（）之前是有效且不变的。由于前面的句子，如果由于某种原因需要记住文件名，sqlite3_file可以安全地存储指向文件名的指针。如果xOpen的zFilename参数是NULL指针，则xOpen必须为文件创建自己的临时名称。。

xOpen（）的flags参数包括sqlite3_open_v2（）的flags参数中设置的所有位。或者，如果使用sqlite3_open（）或sqlite3_open16（），则标志至少包括 SQLITE_OPEN_READWRITE | |。SQLITE_OPEN_CREATE。如果xOpen（）以只读方式打开文件，则它将* pOutFlags设置为包括SQLITE_OPEN_READONLY。* pOutFlags中的其他位可以设置。

SQLite还将根据打开的对象向xOpen（）调用添加以下标志之一：

文件I / O实现可以使用对象类型标志来更改其处理文件的方式。例如，一个不关心崩溃恢复或回滚的应用程序可能使日记文件的打开成为无操作。对该日记的写入也将是禁忌操作，并且任何尝试读取该日记的尝试都将返回SQLITE_IOERR。或者实现可能会认识到数据库文件将以随机顺序进行页面对齐的扇区读取和写入，并相应地设置其I / O子系统。

SQLite可能还会在xOpen方法中添加以下标志之一：

该SQLITE_OPEN_DELETEONCLOSE标志意味着当它关闭该文件应予删除。该SQLITE_OPEN_DELETEONCLOSE 将为TEMP数据库及其期刊，短暂的数据库，并subjournals进行设置。

所述SQLITE_OPEN_EXCLUSIVE标志总是与一起使用SQLITE_OPEN_CREATE标志，这两者都是直接类似于POSIX打开（）API的O_EXCL和O_CREAT标志。当与SQLITE_OPEN_CREATE配对使用时，SQLITE_OPEN_EXCLUSIVE标志用于指示应始终创建文件，并且如果该文件已经存在则为错误。它不用于指示应打开文件以进行独占访问。

SQLite至少分配了szOsFile字节的内存，以保存作为第三个参数传递给xOpen的sqlite3_file结构。xOpen方法不必分配结构。只需将其填充即可。请注意，xOpen方法必须将sqlite3_file.pMethods设置为有效的sqlite3_io_methods对象或设置为NULL。即使打开失败，xOpen也必须执行此操作。SQLite希望无论xOpen调用成功与否，在xOpen返回之后sqlite3_file.pMethods元素都将有效。

flags参数到Xaccess文件（）可以是SQLITE_ACCESS_EXISTS 到用于测试的存在的文件的，或SQLITE_ACCESS_READWRITE到测试文件是否是可读写的，或SQLITE_ACCESS_READ 到测试文件是否至少可读。SQLITE_ACCESS_READ标志从不实际使用，也不在SQLite的内置VFS中实现。该文件由第二个参数命名，并且可以是目录。如果出现I / O错误，或者第二个参数中给定的文件名不合法，则xAccess方法成功返回SQLITE_OK或返回一些非零错误代码。如果返回SQLITE_OK，则将非零或零写入* pResOut，以指示该文件是否可访问。

SQLite将始终至少为输出缓冲区xFullPathname分配mxPathname + 1字节。输出缓冲区的确切大小也作为参数传递给这两种方法。如果输出缓冲区不够大，则应返回SQLITE_CANTOPEN。由于这是SQLite的致命错误，因此vfs实现应通过将mxPathname设置为足够大的值来努力防止这种情况的发生。

xRandomness（），xSleep（），xCurrentTime（）和xCurrentTimeInt64（）接口严格来说不是文件系统的一部分，但为了完整性起见，它们包含在VFS结构中。xRandomness（）函数尝试将高质量随机性的nBytes个字节返回到zOut中。返回值是实际获得的随机字节数。xSleep（）方法使调用线程休眠至少给定的微秒数。xCurrentTime（）方法返回当前日期和时间的儒略日编号作为浮点值。xCurrentTimeInt64（）方法以整数形式返回儒略日编号乘以86400000（24小时制中的毫秒数）。

SQLite核心不使用xSetSystemCall（），xGetSystemCall（）和xNestSystemCall（）接口。一些VFS提供了这些可选接口，以方便对VFS代码进行测试。通过使用受其控制的功能覆盖系统调用，测试程序可以模拟否则将难以或无法引发的故障和错误情况。可以覆盖的系统调用集从一个VFS到另一个VFS，以及从同一VFS的一个版本到下一个版本都不同。使用这些接口的应用程序必须为这些接口中的任何一个或所有接口都为NULL或使其行为从一个版本更改为另一个版本做好准备。如果VFS的iVersion小于3，则应用程序不得尝试访问这些方法中的任何一种。

另请参见对象，常量和函数的列表。