Объект интерфейса OS

typedef struct sqlite3_vfs sqlite3_vfs;
typedef void (*sqlite3_syscall_ptr)(void);
struct sqlite3_vfs {
  int iVersion;            /* Structure version number (currently 3) */
  int szOsFile;            /* Size of subclassed sqlite3_file */
  int mxPathname;          /* Maximum file pathname length */
  sqlite3_vfs *pNext;      /* Next registered VFS */
  const char *zName;       /* Name of this virtual file system */
  void *pAppData;          /* Pointer to application-specific data */
  int (*xOpen)(sqlite3_vfs*, sqlite3_filename zName, sqlite3_file*,
               int flags, 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);
  void *(*xDlOpen)(sqlite3_vfs*, const char *zFilename);
  void (*xDlError)(sqlite3_vfs*, int nByte, char *zErrMsg);
  void (*(*xDlSym)(sqlite3_vfs*,void*, const char *zSymbol))(void);
  void (*xDlClose)(sqlite3_vfs*, void*);
  int (*xRandomness)(sqlite3_vfs*, int nByte, char *zOut);
  int (*xSleep)(sqlite3_vfs*, int microseconds);
  int (*xCurrentTime)(sqlite3_vfs*, double*);
  int (*xGetLastError)(sqlite3_vfs*, int, char *);
  /*
  ** The methods above are in version 1 of the sqlite_vfs object
  ** definition.  Those that follow are added in version 2 or later
  */
  int (*xCurrentTimeInt64)(sqlite3_vfs*, sqlite3_int64*);
  /*
  ** The methods above are in versions 1 and 2 of the sqlite_vfs object.
  ** Those below are for version 3 and greater.
  */
  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);
  /*
  ** The methods above are in versions 1 through 3 of the sqlite_vfs object.
  ** New fields may be appended in future versions.  The iVersion
  ** value will increment whenever this happens.
  */
};

Экземпляр объекта sqlite3_vfs определяет интерфейс между ядром SQLite и основной операционной системой. "vfs" это сокращение от "virtual file system".

Интерфейс VFS иногда расширяется, добавляя новые методы. Каждый раз, когда такое расширение происходит, поле iVersion растет. Значение iVersion начинается с 1 в SQLite version 3.5.0 on 2007-09-04, растет до 2 в SQLite version 3.7.0 on 2010-07-21 и до 3 в SQLite version 3.7.6 on 2011-04-12. Дополнительные области могут быть добавлены к объекту sqlite3_vfs и значение iVersion может увеличиться снова в будущих версиях SQLite. Обратите внимание на то, что из-за надзора, структура объекта sqlite3_vfs изменилась между версиями SQLite version 3.5.9 и version 3.6.0 on 2008-07-16, но поле iVersion не поменялось.

Поле szOsFile это размер структуры sqlite3_file в VFS. mxPathname максимальная длина пути в этом VFS.

Зарегистрированные объекты sqlite3_vfs сохранены в связанном списке, сформированном указателем pNext. Интерфейсы sqlite3_vfs_register() и sqlite3_vfs_unregister() управляют этим списком ориентированным на многопотоковое исполнение способом. Интерфейс sqlite3_vfs_find() ищет в списке. Ни код приложения, ни внедрение VFS не должны использовать указатель pNext.

Поле pNext это единственная область в sqlite3_vfs, которую будет когда-либо изменять SQLite. SQLite получит доступ или изменит эту область, только держа конкретный статический mutex. Приложение ничего никогда не должно изменять в объекте sqlite3_vfs, как только объект был зарегистрирован.

Поле zName хранит название модуля VFS. Имя должно быть уникальным через все модули VFS.

гарантирует, что параметр zFilename в xOpen это NULL или последовательность, полученная из xFullPathname() с дополнительным добавленным суффиксом. Если суффикс будет добавлен к параметру zFilename, он будет состоять из символа "-", сопровождаемого не больше, чем 11 алфавитно-цифровыми символами и/или "-". SQLite гарантирует, что последовательность будет действительна и неизменна до xClose(). Из-за предыдущего предложения sqlite3_file может безопасно сохранить указатель на имя файла, если это должно помнить имя файла по некоторым причинам. Если параметр zFilename в xOpen = NULL, xOpen должен изобрести его собственное временное имя файла. Каждый раз, когда xFilename = NULL будет также иметь место, что параметр флагов будет включать SQLITE_OPEN_DELETEONCLOSE.

Аргумент флагов xOpen() включает весь набор бит в аргумент флагов sqlite3_open_v2().Если применено sqlite3_open() или sqlite3_open16(), то флаги включают по крайней мере SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE. Если xOpen() открывает файл как read-only, он устанавливает *pOutFlags, чтобы тот включал SQLITE_OPEN_READONLY. Другие биты в *pOutFlags могут быть установлены.

SQLite также добавит один из следующих флагов к xOpen(), в зависимости от открываемого объекта:

• SQLITE_OPEN_MAIN_DB
• SQLITE_OPEN_MAIN_JOURNAL
• SQLITE_OPEN_TEMP_DB
• SQLITE_OPEN_TEMP_JOURNAL
• SQLITE_OPEN_TRANSIENT_DB
• SQLITE_OPEN_SUBJOURNAL
• SQLITE_OPEN_SUPER_JOURNAL
• SQLITE_OPEN_WAL

Внедрение файлового ввода-вывода может использовать флаги типа объекта, чтобы изменить способ, которым оно имеет дело с файлами. Например, приложение, которое не заботится о восстановлении катастрофы или обратной перемотке, могло бы игнорировать файл журнала. Запись этого журнала была бы невозможна, а любая попытка прочитать журнал возвратит SQLITE_IOERR. Или внедрение могло бы признать, что файл базы данных будет выровнен по сектору, а чтение и запись идут в произвольном порядке, и настроило свою подсистему I/O соответственно.

SQLite мог бы также добавить один из следующих флагов к

• SQLITE_OPEN_DELETEONCLOSE
• SQLITE_OPEN_EXCLUSIVE

Флаг SQLITE_OPEN_DELETEONCLOSE означает, что файл должен быть удален, когда это закрывается. SQLITE_OPEN_DELETEONCLOSE будет установлен для баз данных TEMP и их журналов, переходных баз данных и поджурналов.

Флаг SQLITE_OPEN_EXCLUSIVE всегда используется вместе с флагом SQLITE_OPEN_CREATE, которые непосредственно аналогичны O_EXCL и O_CREAT в POSIX open() API. SQLITE_OPEN_EXCLUSIVE, когда соединен с SQLITE_OPEN_CREATE, используется, чтобы указать, что файл должен всегда создаваться, и что есть ошибка, если это уже существует. Это не используется, чтобы указать, что файл должен быть открыт для эксклюзивного доступа.

По крайней мере, szOsFile байт памяти ассигнуются SQLite, чтобы хранить структуру sqlite3_file как третий аргумент xOpen. Метод xOpen не должен ассигновать структуру, он должен просто ее заполнить. Обратите внимание на то, что метод xOpen должен установить sqlite3_file.pMethods в действительный объект sqlite3_io_methods или в NULL. xOpen должен сделать это, даже если открытие терпит неудачу. SQLite ожидает, что sqlite3_file.pMethods будет действителен после xOpen независимо от успешности или неуспешности xOpen.

Аргументом флагов xAccess() может быть SQLITE_ACCESS_EXISTS, чтобы проверить на существование файла или SQLITE_ACCESS_READWRITE, чтобы проверить, удобочитаемый ли файл и перезаписываемый, или SQLITE_ACCESS_READ, чтобы проверить, удобочитаемый ли файл, по крайней мере. Флаг SQLITE_ACCESS_READ на самом деле никогда не используется и не осуществляется во встроенном VFS SQLite. Имя файла это второй аргумент и может быть каталогом. Метод xAccess возвращает SQLITE_OK при успехе или некоторый код ошибки, отличный от нуля, если есть ошибка I/O или если название файла, данного во втором аргументе, неправильно. Если SQLITE_OK возвращен, то отличное от нуля или ноль вписано в *pResOut, чтобы указать, доступен ли файл.

SQLite будет всегда ассигновать, по крайней мере, mxPathname+1 байт для буфера вывода xFullPathname. Точный размер буфера вывода также передается в качестве параметра обоим методам. Если буфер вывода недостаточно большой, вернется SQLITE_CANTOPEN. Так как это обработано как фатальная ошибка SQLite, внедрения vfs должны пытаться предотвращать это, устанавливая mxPathname к достаточно большому значению.

Интерфейсы xRandomness(), xSleep(), xCurrentTime() и xCurrentTimeInt64() не строго часть файловой системы, но они включены в структуру VFS для полноты. xRandomness() пытается возвратить nBytes байт хаотичности хорошего качества в zOut. Возвращаемое значение это фактическое число байтов полученной хаотичности. xSleep() заставляет вызывающий поток спать по крайней мере данное число микросекунд. xCurrentTime() возвращает Julian Day Number для текущей даты и время как значение с плавающей точкой. xCurrentTimeInt64() вернет как целое число Julian Day Number, умноженное на 86400000 (количество миллисекунд в 24-часовой день). SQLite будет использовать метод xCurrentTimeInt64(), чтобы получить текущую дату и время, если тот метод будет доступен (если iVersion равняется 2 или больше и указатель функции не NULL) и отступит к xCurrentTime(), если xCurrentTimeInt64() недоступен.

Интерфейсы xSetSystemCall(), xGetSystemCall() и xNestSystemCall() не используются ядром SQLite. Эти дополнительные интерфейсы обеспечиваются некоторыми VFS, чтобы облегчить тестирование кода VFS. Наиважнейшими системными вызовами с функциями под ее контролем тестовая программа может моделировать ошибки и состояние ошибки, которое иначе было бы трудно или невозможным вызвать. Набор системных вызовов, которые могут быть отвергнуты, варьируется от одного VFS до другого, и от одной версии того же самого VFS к следующей. Запросы, которые используют эти интерфейсы, должны быть готовы к любым из этих интерфейсов быть NULL или к их поведению, чтобы измениться от одного выпуска до следующего. Запросы не должны пытаться получить доступ к любому из этих методов, если iVersion VFS меньше 3.