blockcachevfs.h

/*
** 2020-04-01
**
******************************************************************************
** Public interface used by Cloud Backed SQLite (CBS) database clients.
*/

/*
** OVERVIEW
**
** This module provides a VFS that provides access to databases stored in
** Cloud-Backed-SQLite format in remote cloud containers. The VFS may operate
** in two modes:
**
**   1) Daemonless mode. This mode provides read/write access to remote
**      databases.
**
**   2) Daemon mode. This mode provides read-only access to remote databases,
**      but allows database clients from multiple processes to share a
**      single cache directory. This mode requires that the daemon process
**      be started before any VFS objects are created.
**
** In general, the same API is used to interface with a daemon or daemonless
** mode VFS. Please refer to the website documentation for more information.
**
** APPLICATION PROGRAMMING
**
** Creating and destroying VFS objects:
**
**   The application creates a Cloud Backed SQLite VFS object using the
**   sqlite3_bcvfs_create() API. Parameters to this call specify the name of
**   the VFS to create, and the path to a directory that the VFS will use to
**   store its various files. The directory should either be completely empty,
**   or a directory used previously by a Cloud Backed SQLite VFS, or a directory
**   that has a running CBS daemon using it. If the directory has a daemon
*    running in it, then the new VFS automatically connects to
**   that daemon and runs in daemon mode. Otherwise, if there is no daemon,
**   then the created VFS object runs in daemonless mode.
**
**   If the specified directory does not have a running CBS daemon, but was
**   used previously, then the new VFS object is initialized based on the state
**   of the directory - meaning that all containers that were attached when 
**   the previous VFS was shutdown are automatically reattached.
**
**   As well as creating a VFS object that may be used by database clients,
**   a successful call to sqlite3_bcvfs_create() returns an opaque handle
**   (type sqlite3_bcvfs*) that may be used to configure the VFS, attach
**   and detach containers, and other operations described below.
**
**   Once an application has finished with it and all database clients have
**   disconnected, the application may destroy the CBS VFS object
**   and reclaim all associated resources using sqlite3_bcvfs_destroy().
**
**   An application may create any number of VFS objects, but usually one
**   is sufficient. A single VFS object may be used to access databases
**   stored in multiple cloud containers across multiple providers.
**
** Configuring VFS objects:
**
**   Once a VFS object has been created, it must be configured. A VFS object
**   may be configured or reconfigured at any time, but most applications
**   will find it sufficient to configure the object once immediately after
**   it has been created.
**
**   Almost all applications will need to configure the VFS object with
**   an authentication callback using sqlite3_bcvfs_auth_callback(). This
**   callback is the only way the authentication data (e.g. an Azure SAS 
**   string or Google Cloud access token) may be provided to cloud storage
**   modules that require it.
**
**   Application logging (i.e. for debugging) is configure using
**   sqlite3_bcvfs_log_callback().
**
**   Various integer parameters may also be configured using
**   sqlite3_bcvfs_config(). Notably, the SQLITE_BCV_CACHESIZE parameter
**   may be usd with sqlite3_bcvfs_config() to configure the maximum size of
**   the local block cache in bytes.
**
** Attaching and detaching containers:
**
**   Before databases may be accessed, the cloud container that they reside
**   in must be "attached" to the VFS. Containers are attached using the
**   sqlite3_bcvfs_attach() API function. To attach a container, the
**   application specifies cloud storage system (e.g. "azure" or "google"),
**   the user-name used to connect to cloud storage, the name of the cloud
**   storage container as used by the remote system, and an alias that will
**   be used to refer to the container locally.
**
**   Unused containers may be detached from a VFS using sqlite3_bcvfs_detach().
**
** Opening and accessing databases:
**
**   Once one or more containers have been attached to the VFS, databases
**   contained within them may be opened and accessed by SQLite database
**   clients. This is done by specifying a path consisting of the container
**   alias (local name) and the database name, as follows:
**
**      /ALIAS/DATABASE
**
**   and using either an SQLite URI filename or the sqlite3_open_v[23]()
**   interface to specify the VFS name.
**
**   For example, with all error handling omitted, to create a new VFS
**   that uses directory "dirname" to store its files, then to use it
**   to access database "mydb.db" in container "mycont" belonging to 
**   Azure user "myuser":
**
**     sqlite3_bcvfs *pFs;
**     sqlite3 *db;
**
**     sqlite3_bcvfs_create("dirname", "myvfs", &pFs);
**     // ... configure VFS ...
**     sqlite3_bcvfs_attach(pFs, "azure", "myuser", "mycont", "myalias", 0, 0);
**     sqlite3_open_v2("/myalias/mydb.db", &db, SQLITE_OPEN_READWRITE, "myvfs");
**
**   Assuming URI filenames are enabled (SQLITE_CONFIG_URI), the following
**   may be used in place of the sqlite3_open_v2() call above:
**
**     sqlite3_open("file:/myalias/mydb.db?vfs=myvfs", &db);
**
** Poll and Upload operations:
**
**   The sqlite3_bcvfs_poll() and sqlite3_bcvfs_upload() and
**   APIs are used to perform "poll" and "upload" operations on a specified 
**   attached container. Also available are the "PRAGMA bcv_poll"
**   and "PRAGMA bcv_upload" SQL commands.
**
**   Poll operations: When a container is first attached, its "manifest" file
**   is downloaded from cloud storage. The manifest file contains the list
**   of databases in the container and the list of immutable blocks that
**   each database consists of. By default, this manifest is used until the
**   container is detached, only being updated according to local "upload"
**   operations (see below). A "poll" operation downloads a new copy of the
**   manifest from cloud storage, making any changes to the list of
**   available databases and their contents visible to local clients.
**
**   Upload operations: After a database has been modified locally, using the
**   usual SQLite interfaces (i.e. SQL statements), the changes may be uploaded
**   to cloud storage. An "upload" operation uploads all locally modified
**   databases that are part of the specified container.
**
**   When databases modifications are uploaded, or databases are deleted
**   from cloud storage containers altogether, old, unused blocks are left 
**   in cloud storage. The system allows these blocks to linger in case 
**   other clients are still using them instead of deleting them immediately.
**   To actually delete old, unused, blocks from cloud storage, see the
**   sqlite3_bcv_cleanup() API (in bcvutil.h).
**
** VIRTUAL TABLE INTERFACE
**
**   The sqlite3_bcvfs_register_vtab() API is used to register four read-only 
**   eponymous virtual tables, "bcv_database", "bcv_container", "bcv_block",
**   and "bcv_http_log", and one read-write table, "bcv_kv". If the main
**   database of the database handle that these are registered with is open on
**   a CBS database, the four read-only tables provide information regarding 
**   the current state of the VFS object. The "bcv_kv" table provides 
**   read-write access to a key-value store stored in the cloud container 
**   that may be useful for advisory locks or other communication between 
**   remote database clients.
**
**   The four read-only virtual tables are available to both daemon and
**   daemonless mode VFS clients, but bcv_kv is only available in daemonless 
**   mode.
**
** The bcv_container table:
**
**   The "bcv_container" table contains one row for each container attached
**   to the VFS. It has the equivalent of the following schema:
**
**     CREATE TABLE bcv_container(
**       name      TEXT,          -- local name (alias) of container 
**       storage   TEXT,          -- cloud storage system (e.g. "azure")
**       user      TEXT,          -- cloud storage username
**       container TEXT,          -- container name in cloud storage
**       ncleanup  INTEGER        -- number of blocks eligible for cleanup
**     )
**
**   The "ncleanup" column usually contains the number of blocks that will 
**   be deleted from cloud storage if a cleanup operation (see the 
**   sqlite3_bcv_cleanup() API)is run on the container. However, if
**   errors or client crashes have occurred while uploading changes to
**   cloud storage, then there may be extra unused blocks left in the
**   cloud storage container. In this case those blocks will be deleted
**   by the next cleanup operation, but are not included in the value
**   stored in the "ncleanup" column of the "bcv_container" table.
**
** The bcv_database table:
**
**   The "bcv_database" table contains one row for each database in each
**   attached container. It has the equivalent of the following schema:
**
**     CREATE TABLE bcv_database(
**       container TEXT,          -- local name (alias) of container
**       database  TEXT,          -- name of database
**       nblock INTEGER,          -- total number of blocks in database
**       ncache INTEGER,          -- number of blocks in cache
**       ndirty INTEGER,          -- number of dirty blocks in cache
**       walfile BOOLEAN,         -- true if transactions in local wal file
**       state TEXT               -- state of database (see below)
**     )
**
**   The "state" column usually contains an empty string. There are two
**   exceptions:
** 
**      * If the database has been created using sqlite3_bcvfs_copy() but
**        not yet uploaded, then this column contains the text 'copied'.
**
**      * If the database has been deleted using sqlite3_bcvfs_delete() but
**        the delete operation has not yet uploaded, then this column contains 
**        the text 'deleted'.
**
** The bcv_block table:
**
**   The "bcv_block" table contains one row for each block in each database 
**   in each attached container. It has the equivalent of the following 
**   schema:
**
**     CREATE TABLE bcv_block(
**       container TEXT,          -- local name (alias) of container
**       database  TEXT,          -- name of database
**       blockno   INTEGER,       -- block number within database
**       blockid   BLOB,          -- block id (or NULL)
**       cache     BOOLEAN,       -- true if block is in cache
**       dirty     BOOLEAN        -- true if block is dirty
**     ) 
**
**   The first three columns, "container", "database" and "blockno", identify
**   a block within a specific database. Blocks are numbered starting from
**   zero.
**
**   The "blockid" column usually contains a unique block identifier. Or, if
**   the block in question has been appended to the database since it was
**   last uploaded, this column contains a NULL value. The boolean "cache"
**   column is true if the block is currently cached locally, and "dirty"
**   is true if the block is dirty and a new version needs to be uploaded.
**
** The bcv_http_log table:
**
**   The "bcv_http_log" table contains one row for each HTTP request made
**   by the VFS or connected daemon. It has the equivalent of the following
**   for a schema:
**
**     CREATE TABLE bcv_http_log(
**       id INTEGER,              -- Unique, monotonically increasing id value
**       start_time INTEGER,      -- Time request was made, as iso-8601
**       end_time INTEGER,        -- Time reply received, as iso-8601 (or NULL)
**       method TEXT,             -- "PUT", "GET" etc.
**       client TEXT,             -- Name of client that caused request
**       logmsg TEXT,             -- Log message associated with request
**       uri TEXT,                -- URI of request
**       httpcode INTEGER         -- HTTP response code (e.g. 200)
**     ) 
**
**   For those requests that can be associated with a single SQLite database
**   handle, the contents of the "client" column is the client name as
**   configured using the "PRAGMA bcv_client" command. For requests associated
**   with a prefetch operation, it contains the string 'prefetch'.
**
**   To prevent it from consuming an ever-increasing amount of memory, entries 
**   are automatically removed from the bcv_http_log on a first-in/first-out
**   according to the values configured for the SQLITE_BCV_HTTPLOG_TIMEOUT 
**   and SQLITE_BCV_HTTPLOG_NENTRY parameters. Or, in daemon mode, according
**   to the values passed via the --httplogtimeout and --httplognentry 
**   command-line options.
**
**   Including various overheads, each entry may be assumed to consume 
**   256 bytes of memory or less. So allowing 4096 entries to accumulate in
**   the bcv_http_log table may require up to 1MiB of memory.
**
** The bcv_kv table:
**
**   The schema of the "bcv_kv" table is:
**
**     CREATE TABLE bcv_kv(
**       name TEXT PRIMARY KEY,   -- Key value 
**       value                    -- Associated payload value
**     )
**
**   The contents of the bcv_kv table is stored as a separate file (an
**   SQLite database) in the cloud container - "bcv_kv.bcv". The table
**   is empty when the container is first created.
**
**   The bcv_kv table implements transaction-like properties. As follows:
**
**     * The first time in a database transaction that the bcv_kv table 
**       is read or written, the file is downloaded from cloud storage and
**       cached for the duration of the transaction. All user queries -
**       read and write - are executed against this cached version of the 
**       bcv_kv table. This ensures that each transaction sees a consistent 
**       version of the table contents.
**
**     * When a read/write transaction is committed, a new version of the
**       bcv_kv table data is uploaded to cloud storage. At this point,
**       if it is found that the file has been modified within cloud storage
**       since it was downloaded at the beginning of the transaction (because
**       some other client wrote to it), the commit fails and the transaction
**       is rolled back. The extended error code in this case is 
**       SQLITE_BUSY_SNAPSHOT.
**
** Virtual tables without a database:
**
**   Sometimes, it may be convenient to access the virtual table interface
**   without having to identify and open a cloud container database. To
**   support this, paths of the forms:
**
**      /
**      /CONTAINER
**
**   may be opened with bcvfs VFSs, where CONTAINER is the local name (alias)
**   of an attached container. The databases opened by either of these two
**   forms of path are empty. Attempting to create any new tables within them
**   fails. However, if sqlite3_bcvfs_register_vtab() is called on the
**   database handle, they may be used to access the bcvfs virtual table
**   interface.
**
**   If the path opened is simply "/", then only the "bcv_database" and
**   "bcv_container" tables are available. If the path is of the form
**   "/CONTAINER", then all three virtual tables are available.
*/

#include "sqlite3.h"

#ifdef __cplusplus
extern "C" {
#endif

/*
** Opaque Cloud Backed SQLite VFS handle type.
*/
typedef struct sqlite3_bcvfs sqlite3_bcvfs;

/*
** Create a new Cloud Backed SQLite VFS in the current process. Parameter zDir
** must point to a nul-terminated buffer containing the path (absolute
** or relative) of the directory to use for the various files created
** by Cloud Backed SQLite. Parameter zName should point to a buffer containing 
** the name of the new VFS.
**
** Unless there is a daemon process running in the directory, this routine
** requires exclusive access to the directory. If it is already in use by
** some other Cloud Backed SQLite VFS, in this or another process, this routine 
** fails with SQLITE_BUSY.
*/
int sqlite3_bcvfs_create(
  const char *zDir,               /* Directory to use */
  const char *zName,              /* New VFS name */
  sqlite3_bcvfs **ppFs,           /* OUT: Handle for new object */
  char **pzErr                    /* OUT: Error message */
);

/*
** Configure a VFS object created by a call to sqlite3_bcv_new().
**
** This API is only available for local (non-daemon) VFS objects. It
** always returns SQLITE_NOTFOUND if called on a daemon VFS.
*/
int sqlite3_bcvfs_config(sqlite3_bcvfs *pFs, int op, sqlite3_int64 iVal);

/*
** SQLITE_BCV_CACHESIZE:
**   Argument sets the maximum size of the cachefile in bytes. This option
**   is only available for daemonless mode VFSs.
**
** SQLITE_BCV_NREQUEST:
**   Argument sets the maximum number of simultaneous HTTPS requests
**   used when writing to cloud storage (e.g. to upload database changes).
**   This option is only available for daemonless mode VFSs.
**
** SQLITE_BCV_HTTPTIMEOUT:
**   Argument sets the number of seconds after which to assume an HTTPS
**   request has been lost. Default value is 600.
**
** SQLITE_BCV_CURLVERBOSE:
**   The argument enables (non-zero) or disables (zero) verbose libcurl
**   logging.
**
** SQLITE_BCV_HTTPLOG_TIMEOUT:
**   The parameter specifies the number of seconds for which entries should
**   remain in the bcv_http_log virtual table. A value of less than 0 means
**   that entries should never time out. The default value is 3600.
**
** SQLITE_BCV_HTTPLOG_NENTRY:
**   The maximum number of entries that the bcv_http_log table may contain.
**   A value less than 0 means there is no limit on the number of entries.
**   The default value is -1.
*/
#define SQLITE_BCV_CACHESIZE   1
#define SQLITE_BCV_NREQUEST    2
#define SQLITE_BCV_HTTPTIMEOUT 3
#define SQLITE_BCV_CURLVERBOSE 4
#define SQLITE_BCV_HTTPLOG_TIMEOUT 5
#define SQLITE_BCV_HTTPLOG_NENTRY  6

/*
** Return true if this VFS is connected to a daemon process. Or false if
** it accesses cloud storage directly (daemonless mode).
*/
int sqlite3_bcvfs_isdaemon(sqlite3_bcvfs*);

/*
** Configure an authentication callback.
**
** An authentication callback is required by both daemon and daemonless 
** mode VFS.
*/
int sqlite3_bcvfs_auth_callback(
  sqlite3_bcvfs *pFs,
  void *pAuthCtx,
  int(*xAuth)(
      void *pCtx, 
      const char *zStorage,
      const char *zAccount,
      const char *zContainer,
      char **pzAuthToken
  )
);

/*
** Configure a logging callback.
*/
int sqlite3_bcvfs_log_callback(
  sqlite3_bcvfs *pFs,
  void *pLogCtx,
  int mask,                       /* mask of SQLITE_BCV_LOG_XXX flags */
  void(*xLog)(void *pCtx, int mLog, const char *zMsg)
);

/*
** Flags for the 3rd argument to sqlite3_bcvfs_log_callback().
*/
#define SQLITE_BCV_LOG_HTTP      0x0001
#define SQLITE_BCV_LOG_UPLOAD    0x0002
#define SQLITE_BCV_LOG_CLEANUP   0x0004
#define SQLITE_BCV_LOG_EVENT     0x0008
#define SQLITE_BCV_LOG_HTTPRETRY 0x0010

/*
** Attach the specified container to the VFS. Parameters zStorage, zAccount
** and zContainer identify the cloud storage container to attach. zAlias is the
** alias to use for the attached container. If parameter zAlias is NULL, the
** alias is the same as the container name (zContainer).
**
** This API is available for both both daemon and daemonless mode VFS.
*/
int sqlite3_bcvfs_attach(
  sqlite3_bcvfs *pFs,
  const char *zStorage,
  const char *zAccount,
  const char *zContainer,
  const char *zAlias,
  int flags,                      /* Mask of SQLITE_BCV_ATTACH_XXX flags */
  char **pzErr                    /* OUT: Error message */
);

/*
** Flags for the 6th argument to sqlite3_bcvfs_attach().
**
** SQLITE_BCV_ATTACH_SECURE:
**   Specifying this flag has no effect when using a single-process VFS
**   (one created by sqlite3_bcvfs_create()). When used with a proxy
**   VFS connected to a daemon process, it requests that the daemon
**   attach the database in secure mode - encrypting blocks stored in
**   the cachefile and sharing the key only with clients that have
**   proven that they have the credentials required to access the cloud
**   storage container.
**
** SQLITE_BCV_ATTACH_IFNOT:
**   Usually, if an attempt is made to attach a container with the same
**   name (alias) as one that is already attached, it is an error. However,
**   if this flag is specified, then the operation instead returns SQLITE_OK
**   immediately.
*/
#define SQLITE_BCV_ATTACH_SECURE 0x0001
#define SQLITE_BCV_ATTACH_IFNOT  0x0002

/*
** Detach a container. A container may be detached only if both of the
** following are true:
**
**   1) There are no clients connected to databases within the container.
**   2) There are no local changes that have not been pushed to the cloud
**      to any databases within the container.
**
** If the container is successfully detached, SQLITE_OK is returned. If 
** either of the two conditions above are not met, SQLITE_BUSY is returned
** and the container remains attached.
**
** This API is available for both both daemon and daemonless mode VFS.
*/
int sqlite3_bcvfs_detach(sqlite3_bcvfs *pFs, const char *zAlias, char **pzErr);


/*
** Poll the named container for a new manifest.
**
** This API is available for both both daemon and daemonless mode VFS.
*/
int sqlite3_bcvfs_poll(sqlite3_bcvfs *pFs, const char *zCont, char **pzErr);


/*
** Attempt to upload all locally modified databases in container zCont to
** cloud storage.
**
** Uploading a modified database to cloud storage involves running the
** equivalent of "PRAGMA wal_checkpoint = full" on the database. If it
** is not NULL, then the xBusy parameter specifies a callback function
** that may be invoked in the same way as an SQLite busy-handler function
** to wait on any read or write clients blocking the checkpoint. If this
** callback function is invoked, a copy of parameter pBusyArg is passed
** as the first argument. The second argument is passed the number of times
** that the busy-handler has already been invoked by the current call to
** sqlite3_bcvfs_upload().
**
** If all locally modified databases are succesfully uploaded, SQLITE_OK
** is returned. If parameter pzErr is not NULL, *pzErr is set to NULL in
** this case. 
**
** Otherwise, if an error occurs, either an SQLite or HTTPS error code 
** is returned.
**
** If this function returns a value other than SQLITE_OK and parameter pzErr
** is not NULL, then (*pzErr) may be set to point to point to a buffer
** containing an English language error message. In this case it is the
** responsibility of the caller to free the buffer using sqlite3_free().
** If it is not set to point to a buffer containing an error message,
** (*pzErr) is set to NULL.
**
** This API always returns SQLITE_OK without doing anything for daemonless
** mode VFS (as there are never any local changes to upload). This is true
** even if the specified container does not exist.
*/
int sqlite3_bcvfs_upload(
  sqlite3_bcvfs *pFs,             /* VFS handle */
  const char *zCont,              /* Container (alias) to upload databases of */
  int (*xBusy)(void*,int),        /* Busy-handler callback */
  void *pBusyArg,                 /* First argument passed to xBusy */
  char **pzErr                    /* OUT: Error message */
);

/*
** This function is used to create a copy of a database within container
** zCont, which must be the name (alias) of an attached container. The
** database to make a copy of is identified by parameter zFrom, the name
** of the new copy will be zTo.
**
** If successful, this function returns SQLITE_OK. Otherwise, it returns
** an SQLite error code. If parameter pzErr is not NULL, then (*pzErr)
** may be set to a buffer containing an English language error message.
** It is the responsibility of the caller to ensure that this buffer
** is eventually freed using sqlite3_free().
**
** It is an error if database zFrom does not exist within the attached
** container, or if database zTo already exists.
**
** The copy operation creates the new database locally only. It is not
** uploaded to cloud storage until the next call to sqlite3_bcvfs_upload()
** on the container. Until that time it is a "local-only" database. A
** local-only database may be read and written locally in the same way
** as any other database. There are the following eccentricities:
**
**   * a local-only database may not be copied using sqlite3_bcvfs_copy().
**
**   * if another client creates a database in the container using the
**     same name as the local-only database, then this is handled in the
**     same way as a write collision - subsequent attempts to update the
**     local manifest using sqlite3_bcvfs_poll() (or "PRAGMA bcv_poll") 
**     will fail.
**
**   * if another client manipulates the parent database in such a way
**     as to make blocks that the local-only database depends on eligible
**     for deletion, this also counts as a write collision.
**
**   * if the database being copied is dirty (has changes that have yet
**     to be uploaded to the cloud), these are not included in the copy.
**     The copy is based on the uploaded version of the database, not
**     the local version.
*/
int sqlite3_bcvfs_copy(
  sqlite3_bcvfs *pFs,
  const char *zCont,              /* Name (alias) of attached container */
  const char *zFrom,
  const char *zTo,
  char **pzErr                    /* OUT: error message */
);

/*
** Delete database zDb from container zCont, which must be the name (alias)
** of an attached container. 
**
** This operation deletes the named database locally only. The database 
** is not deleted from cloud storage until the next call to 
** sqlite3_bcvfs_upload(). If there are local changes to the deleted 
** database, they are lost.
**
** If there are local connections holding the database open, this operation
** may fail with SQLITE_BUSY.
*/
int sqlite3_bcvfs_delete(
  sqlite3_bcvfs *pFs,
  const char *zCont,              /* Name (alias) of attached container */
  const char *zDb,
  char **pzErr                    /* OUT: error message */
);

/*
** Free a VFS created by a call to sqlite3_bcvfs_new(). This call will fail
** and return SQLITE_BUSY if there are still one or more database clients
** using the VFS.
*/
int sqlite3_bcvfs_destroy(sqlite3_bcvfs *pFs);

/*
** Register the eponymous vtab modules "bcv_database" and "bcv_container" 
** with the database handle passed as the only argument.
**
** This API is available for both both daemon and daemonless mode VFS.
*/
int sqlite3_bcvfs_register_vtab(sqlite3*);

typedef struct sqlite3_prefetch sqlite3_prefetch;

/*
** Create a new prefetch object. A prefetch object can be used to manage
** prefetching blocks belonging to database zDb in container zCont.
**
** If successful, (*ppOut) is set to point to the new prefetch object
** and SQLITE_OK is returned. Otherwise, if an error occurs, an
** SQLite error code is returned and (*ppOut) is set to NULL.
*/
int sqlite3_bcvfs_prefetch_new(
  sqlite3_bcvfs *pFs,
  const char *zCont,
  const char *zDb,
  sqlite3_prefetch **ppOut
);

/*
** Do some prefetching. Calling this function issues HTTP requests
** for blocks of the database file that are not currently in the
** local cache until either (a) there are in total nRequest such
** requests outstanding, or (b) there are requests outstanding
** for all blocks not currently in the cache.
**
** This function does not return until either one of the outstanding
** HTTP requests has completed or the timeout of nMs ms has expired.
** It returns SQLITE_DONE if all blocks of the specified file have
** been fetched, SQLITE_OK if no error has occurred but the entire
** file has not yet been cached, or an SQLite or HTTP error code
** if an error has occured.
**
** Once an error has occurred, all subsequent calls to
** sqlite3_bcvfs_prefetch_run() immediately return the same error code.
**
** IMPORTANT: If there are outstanding requests and no error has
** occurred, applications must call sqlite3_bcvfs_prefetch_run()
** or sqlite3_bcvfs_prefetch_destroy() in a timely manner. This is
** because those outstanding requests will not be handled (or abandoned)
** until one of those two is called, and there may be other threads
** also waiting on the same requests.
*/
int sqlite3_bcvfs_prefetch_run(
  sqlite3_prefetch*,              /* Prefetch handle */
  int nRequest,                   /* Maximum number of outstanding requests */
  int nMs                         /* Timeout in ms */
);

/*
** If sqlite3_bcvfs_prefetch_run() has encountered an error - returned
** some value other than SQLITE_OK or SQLITE_DONE - this function returns
** a pointer to a buffer containing an English language error message.
*/
const char *sqlite3_bcvfs_prefetch_errmsg(sqlite3_prefetch*);
int sqlite3_bcvfs_prefetch_errcode(sqlite3_prefetch*);

/*
** Query a prefetch object for various quantities. The specific value
** queried for is determined by the second parameter, which must be
** one of the SQLITE_BCVFS_PFS_* values. If successful, SQLITE_OK is
** returned and output parameter (*piVal) set to the queried value.
** Otherwise, an SQLite error code is returned and the final value
** of (*piVal) is undefined.
*/
int sqlite3_bcvfs_prefetch_status(
  sqlite3_prefetch*, 
  int op, 
  sqlite3_int64 *piVal
);

/*
** Candidates for the second argument to sqlite3_bcvfs_prefetch_status().
**
** SQLITE_BCVFS_PFS_NOUTSTANDING:
**   The total number of outstanding requests managed by the
**   prefetch object.
**
** SQLITE_BCVFS_PFS_NDEMAND:
**   The number of clients waiting on on-demand requests currently outstanding
**   when the most recent call to prefetch_run() returned.
*/
#define SQLITE_BCVFS_PFS_NOUTSTANDING 1
#define SQLITE_BCVFS_PFS_NDEMAND      2

/*
** Free a prefetch object created using sqlite3_bcvfs_prefetch_new().
**
** If there are outstanding HTTP requests managed by the prefetch
** object when this function is called, they are abandoned.
*/
void sqlite3_bcvfs_prefetch_destroy(sqlite3_prefetch*);

/*
** Revert all changes made to the container identified by the second
** argument since the last successful call to sqlite3_bcvfs_upload(),
** including database writes, sqlite3_bcvfs_copy() and sqlite3_bcvfs_delete()
** operations.
**
** If successful, SQLITE_OK is returned. Otherwise, an SQLite error code
** is returned and output variable (*pzErr) may be set to point to a buffer
** containing an English language error message. In this case it is the
** responsibility of the caller to eventually free the buffer using
** sqlite3_free(). This function performs no network IO, so there is no
** chance of an HTTP error code being returned.
**
** This function fails with SQLITE_BUSY if there exist one or more clients
** with open read or write transactions on databases within the named 
** container.
**
** If the VFS passed as the first argument is a proxy VFS, then this
** function is a no-op that always returns SQLITE_OK. This is true even if
** zCont is not the name of an attached container.
*/
int sqlite3_bcvfs_revert(sqlite3_bcvfs*, const char *zCont, char **pzErr);


#ifdef __cplusplus
} /* end of the extern "C" block */
#endif