Методы объекта файлового интерфейса виртуальной 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 в ненулевой указатель, то метод sqlite3_io_methods.xClose может быть вызван, даже если sqlite3_vfs.xOpen сообщил, что это потерпело неудачу. Единственный способ предотвратить вызов xClose после неудавшегося sqlite3_vfs.xOpen это установить sqlite3_file.pMethods = NULL.

Аргумент флагов xSync может быть одним из SQLITE_SYNC_NORMAL или SQLITE_SYNC_FULL. Предпочтительный вариант: обычный fsync(). Второй выбор это стиль Mac OS X fullsync. Флаг SQLITE_SYNC_DATAONLY может быть ORed, чтобы указать, что только данные файла, но не его inode должны синхронизироваться.

Целочисленные значения в xLock() and xUnlock() это одно из:

• SQLITE_LOCK_NONE,
• SQLITE_LOCK_SHARED,
• SQLITE_LOCK_RESERVED,
• SQLITE_LOCK_PENDING или
• SQLITE_LOCK_EXCLUSIVE.

Метод xFileControl() это универсальный интерфейс, который позволяет VFS непосредственно управлять открытым файлом, используя интерфейс sqlite3_file_control(). Второй аргумент "op" это код операции целого числа. Третий аргумент это универсальный указатель, предназначенный, чтобы указать на структуру, которая может содержать аргументы или место, в котором можно написать возвращаемые значения. Потенциальное использование для xFileControl() могло бы быть функциями, чтобы позволить блокировать с перерывами, изменить стратегию захвата (например, чтобы использовать блокировки точечного файла), справиться о статусе или снять блокировки. Ядро SQLite резервирует все коды операции меньше 100 для собственного использования. Список opcodes меньше 100 доступны. Приложения, которые определяют метод xFileControl, должны использовать коды операции больше 100, чтобы избежать конфликтов. Внедрения VFS должны возвратить SQLITE_NOTFOUND для кодов операции контроля за файлом, которые они не распознали.

Метод 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, который терпит неудачу при заполнении нулями, вроде бы работает. Но рано или поздно это повредит БД.