Interfaz de sistema operativo de objetos métodos de archivos virtual

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 */
  /* Additional methods may be added in future releases */
};

Cada fichero abierto por el método sqlite3_vfs.xOpen rellena un objeto sqlite3_file (o, más comunmente, una subclase del objeto sqlite3_file) con un puntero a una instancia de este objeto. Este objeto define los métodos usados para realizar varias operaciones con el fichero abierto representado por el objeto sqlite3_file.

Si el método sqlite3_vfs.xOpen asigna el elemento sqlite3_file.pMethod a un punetro no NULL, entonces el método sqlite3_io_methods.xClose puede ser invocado aunque sqlite3_vfs.xOpen haya indicado que ha fallado. la única manera de evitar una llamada a xClose después de un sqlite3_vfs.xOpen fallido es que sqlite3_vfs.xOpen asigne NULL al elemento sqlite3_file.pMethods.

Los argumentos flags para xSync puede ser uno de SQLITE_SYNC_NORMAL o SQLITE_SYNC_FULL. La primera opción es el fsync() normal. La segunda es en estilo fullsync para ele sistema operativo X de Mac. La bandera SQLITE_SYNC_DATAONLY puede ser ORed para indicar que se necesita el dato del fichero y no el su inode para ser sincronizado.

Los valores enteros para xLock() y xUnlock() son uno de:

• SQLITE_LOCK_NONE,
• SQLITE_LOCK_SHARED,
• SQLITE_LOCK_RESERVED,
• SQLITE_LOCK_PENDING, o
• SQLITE_LOCK_EXCLUSIVE.

xLock() incrementa el bloqueo. xUnlock() decrementa el bloqueo. El método xCheckReservedLock() verifica si alguna conexión de base de datos, sea en este proceso o en otro, está manteniendo un bloque RESERVED, PENDING o EXCLUSIVE en el fichero. Devuelve un valor verdadero si existe un bloque y falso en otro caso.

El método xFileControl() es un interfaz genérico que permite implementaciones VFS a medida para controlar directamente un fichero abierto usando la interfaz sqlite3_file_control(). El segundo argumento "op" es un código de operación entero. El tercer argumento es un puntero es un puntero genérico destinado para apuntar a una estructura que puede contener argumentos o espacio en el que pueden escribirse valores de retorno. Usos potenciales para xFileControl() podrían ser funciones para permitir bloqueos con tiempos de espera, para cambiar la estrategia de bloqueo (por ejemplo para usar archivos de puntos seguros), para preguntar sobre el estado de un bloqueo, o para romper bloqueos robados. El núcleo de SQLite reserva todos los códigos de operación menores de 100 para su propio uso. La lista de los códigos de operación menores de 100 está disponible. Las aplicaciones que definen un método xFileControl propio usan códigos de operación mayores de 100 para evitar conflictos. Las implementaciones VFS deben retornar SQLITE_NOTFOUND para códigos de operación de control de fichero que no reconozcan.

El método xSectorSize() retorna el tamaño de sector del dispositivo que que subyace al fichero. El tamaño de sector es la escritura mínima que puede ser realizada sin modificar otros bytes en el fichero. El método xDeviceCharacteristics() devuelve un vector de bits que describen comportamientos del dispositivo subyacente:

• 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

La propiedad SQLITE_IOCAP_ATOMIC significa que todas las escrituras de cualquier tamaño son atómicas. Los valores SQLITE_IOCAP_ATOMICnnn significan que escrituras de bloques que tengan nnn bytes de tamaño y estén alineadas a una dirección que sea un múltiplo entero de nnn son atómicas. El valor SQLITE_IOCAP_SAFE_APPEND significa que cuando se añaden datos a un fichero, los datos se añaden primero y después se extiende el tamaño del fichero, nunca al revés. La propiedad SQLITE_IOCAP_SEQUENTIAL significa que la información se escribe en el disco en el mismo orden que las llamadas a xWrite().

Si xRead() retorna SQLITE_IOERR_SHORT_READ también debe rellenar las porciones no leídas del buffer con ceros. Un VFS que falle en el relleno con ceros para lecturas cortas podría parecer que funciona. Sin embargo, fallar en relleno con ceros en lecturas cortas finalmente conducirá a una corrupción de la base de datos.