Bug 787804 - Rewrite quota handling (eliminate test_quota.c). r=bent,asuth,vladan

To move to a new version:

Copy the sqlite3.h and sqlite3.c files from the amalgamation of sqlite. Also,

copy test_quota.h and test_quota.c from the full source package.

Copy the sqlite3.h and sqlite3.c files from the amalgamation of sqlite.

(We no longer use test_quota.h and test_quota.c)

Be sure to update SQLITE_VERSION accordingly in $(topsrcdir)/configure.in as

well as the version number at the top of this file.

        sqlite3_transfer_bindings

        sqlite3_unlock_notify

        sqlite3_update_hook

        sqlite3_uri_parameter

        sqlite3_user_data

        sqlite3_value_blob

        sqlite3_value_bytes

/*

** 2011 December 1

**

** The author disclaims copyright to this source code.  In place of

** a legal notice, here is a blessing:

**

**    May you do good and not evil.

**    May you find forgiveness for yourself and forgive others.

**    May you share freely, never taking more than you give.

**

*************************************************************************

**

** This file contains the interface definition for the quota a VFS shim.

**

** This particular shim enforces a quota system on files.  One or more

** database files are in a "quota group" that is defined by a GLOB

** pattern.  A quota is set for the combined size of all files in the

** the group.  A quota of zero means "no limit".  If the total size

** of all files in the quota group is greater than the limit, then

** write requests that attempt to enlarge a file fail with SQLITE_FULL.

**

** However, before returning SQLITE_FULL, the write requests invoke

** a callback function that is configurable for each quota group.

** This callback has the opportunity to enlarge the quota.  If the

** callback does enlarge the quota such that the total size of all

** files within the group is less than the new quota, then the write

** continues as if nothing had happened.

*/

#ifndef _QUOTA_H_

#include "sqlite3.h"

#include <stdio.h>

#include <sys/types.h>

#include <sys/stat.h>

#if SQLITE_OS_UNIX

# include <unistd.h>

#endif

#if SQLITE_OS_WIN

# include <windows.h>

#endif

/* Make this callable from C++ */

#ifdef __cplusplus

extern "C" {

#endif

/*

** Initialize the quota VFS shim.  Use the VFS named zOrigVfsName

** as the VFS that does the actual work.  Use the default if

** zOrigVfsName==NULL.  

**

** The quota VFS shim is named "quota".  It will become the default

** VFS if makeDefault is non-zero.

**

** THIS ROUTINE IS NOT THREADSAFE.  Call this routine exactly once

** during start-up.

*/

int sqlite3_quota_initialize(const char *zOrigVfsName, int makeDefault);

/*

** Shutdown the quota system.

**

** All SQLite database connections must be closed before calling this

** routine.

**

** THIS ROUTINE IS NOT THREADSAFE.  Call this routine exactly once while

** shutting down in order to free all remaining quota groups.

*/

int sqlite3_quota_shutdown(void);

/*

** Create or destroy a quota group.

**

** The quota group is defined by the zPattern.  When calling this routine

** with a zPattern for a quota group that already exists, this routine

** merely updates the iLimit, xCallback, and pArg values for that quota

** group.  If zPattern is new, then a new quota group is created.

**

** The zPattern is always compared against the full pathname of the file.

** Even if APIs are called with relative pathnames, SQLite converts the

** name to a full pathname before comparing it against zPattern.  zPattern

** is a glob pattern with the following matching rules:

**

**      '*'       Matches any sequence of zero or more characters.

**

**      '?'       Matches exactly one character.

**

**     [...]      Matches one character from the enclosed list of

**                characters.  "]" can be part of the list if it is

**                the first character.  Within the list "X-Y" matches

**                characters X or Y or any character in between the

**                two.  Ex:  "[0-9]" matches any digit.

**

**     [^...]     Matches one character not in the enclosed list.

**

**     /          Matches either / or \.  This allows glob patterns

**                containing / to work on both unix and windows.

**

** Note that, unlike unix shell globbing, the directory separator "/"

** can match a wildcard.  So, for example, the pattern "/abc/xyz/" "*"

** matches any files anywhere in the directory hierarchy beneath

** /abc/xyz.

**

** The glob algorithm works on bytes.  Multi-byte UTF8 characters are

** matched as if each byte were a separate character.

**

** If the iLimit for a quota group is set to zero, then the quota group

** is disabled and will be deleted when the last database connection using

** the quota group is closed.

**

** Calling this routine on a zPattern that does not exist and with a

** zero iLimit is a no-op.

**

** A quota group must exist with a non-zero iLimit prior to opening

** database connections if those connections are to participate in the

** quota group.  Creating a quota group does not affect database connections

** that are already open.

**

** The patterns that define the various quota groups should be distinct.

** If the same filename matches more than one quota group pattern, then

** the behavior of this package is undefined.

*/

int sqlite3_quota_set(

  const char *zPattern,           /* The filename pattern */

  sqlite3_int64 iLimit,           /* New quota to set for this quota group */

  void (*xCallback)(              /* Callback invoked when going over quota */

     const char *zFilename,         /* Name of file whose size increases */

     sqlite3_int64 *piLimit,        /* IN/OUT: The current limit */

     sqlite3_int64 iSize,           /* Total size of all files in the group */

     void *pArg                     /* Client data */

  ),

  void *pArg,                     /* client data passed thru to callback */

  void (*xDestroy)(void*)         /* Optional destructor for pArg */

);

/*

** Bring the named file under quota management, assuming its name matches

** the glob pattern of some quota group.  Or if it is already under

** management, update its size.  If zFilename does not match the glob

** pattern of any quota group, this routine is a no-op.

*/

int sqlite3_quota_file(const char *zFilename);

/*

** The following object serves the same role as FILE in the standard C

** library.  It represents an open connection to a file on disk for I/O.

**

** A single quota_FILE should not be used by two or more threads at the

** same time.  Multiple threads can be using different quota_FILE objects

** simultaneously, but not the same quota_FILE object.

*/

typedef struct quota_FILE quota_FILE;

/*

** Create a new quota_FILE object used to read and/or write to the

** file zFilename.  The zMode parameter is as with standard library zMode.

*/

quota_FILE *sqlite3_quota_fopen(const char *zFilename, const char *zMode);

/*

** Perform I/O against a quota_FILE object.  When doing writes, the

** quota mechanism may result in a short write, in order to prevent

** the sum of sizes of all files from going over quota.

*/

size_t sqlite3_quota_fread(void*, size_t, size_t, quota_FILE*);

size_t sqlite3_quota_fwrite(const void*, size_t, size_t, quota_FILE*);

/*

** Flush all written content held in memory buffers out to disk.

** This is the equivalent of fflush() in the standard library.

**

** If the hardSync parameter is true (non-zero) then this routine

** also forces OS buffers to disk - the equivalent of fsync().

**

** This routine return zero on success and non-zero if something goes

** wrong.

*/

int sqlite3_quota_fflush(quota_FILE*, int hardSync);

/*

** Close a quota_FILE object and free all associated resources.  The

** file remains under quota management.

*/

int sqlite3_quota_fclose(quota_FILE*);

/*

** Move the read/write pointer for a quota_FILE object.  Or tell the

** current location of the read/write pointer.

*/

int sqlite3_quota_fseek(quota_FILE*, long, int);

void sqlite3_quota_rewind(quota_FILE*);

long sqlite3_quota_ftell(quota_FILE*);

/*

** Test the error indicator for the given file.

**

** Return non-zero if the error indicator is set.

*/

int sqlite3_quota_ferror(quota_FILE*);

/*

** Truncate a file previously opened by sqlite3_quota_fopen().  Return

** zero on success and non-zero on any kind of failure.

**

** The newSize argument must be less than or equal to the current file size.

** Any attempt to "truncate" a file to a larger size results in 

** undefined behavior.

*/

int sqlite3_quota_ftruncate(quota_FILE*, sqlite3_int64 newSize);

/*

** Return the last modification time of the opened file, in seconds

** since 1970.

*/

int sqlite3_quota_file_mtime(quota_FILE*, time_t *pTime);

/*

** Return the size of the file as it is known to the quota system.

**

** This size might be different from the true size of the file on

** disk if some outside process has modified the file without using the

** quota mechanism, or if calls to sqlite3_quota_fwrite() have occurred

** which have increased the file size, but those writes have not yet been

** forced to disk using sqlite3_quota_fflush().

**

** Return -1 if the file is not participating in quota management.

*/

sqlite3_int64 sqlite3_quota_file_size(quota_FILE*);

/*

** Return the true size of the file.

**

** The true size should be the same as the size of the file as known

** to the quota system, however the sizes might be different if the

** file has been extended or truncated via some outside process or if

** pending writes have not yet been flushed to disk.

**

** Return -1 if the file does not exist or if the size of the file

** cannot be determined for some reason.

*/

sqlite3_int64 sqlite3_quota_file_truesize(quota_FILE*);

/*

** Determine the amount of data in bytes available for reading

** in the given file.

**

** Return -1 if the amount cannot be determined for some reason.

*/

long sqlite3_quota_file_available(quota_FILE*);

/*

** Delete a file from the disk, if that file is under quota management.

** Adjust quotas accordingly.

**

** If zFilename is the name of a directory that matches one of the

** quota glob patterns, then all files under quota management that

** are contained within that directory are deleted.

**

** A standard SQLite result code is returned (SQLITE_OK, SQLITE_NOMEM, etc.)

** When deleting a directory of files, if the deletion of any one

** file fails (for example due to an I/O error), then this routine

** returns immediately, with the error code, and does not try to 

** delete any of the other files in the specified directory.

**

** All files are removed from quota management and deleted from disk.

** However, no attempt is made to remove empty directories.

**

** This routine is a no-op for files that are not under quota management.

*/

int sqlite3_quota_remove(const char *zFilename);

#ifdef __cplusplus

}  /* end of the 'extern "C"' block */

#endif

#endif /* _QUOTA_H_ */

  media \

  messages \

  power \

  quota \

  settings \

  sms \

  mms \