Return to test_quota.h CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / sqlite3 / src

sqlite3

    1: /*
    2: ** 2011 December 1
    3: **
    4: ** The author disclaims copyright to this source code.  In place of
    5: ** a legal notice, here is a blessing:
    6: **
    7: **    May you do good and not evil.
    8: **    May you find forgiveness for yourself and forgive others.
    9: **    May you share freely, never taking more than you give.
   10: **
   11: *************************************************************************
   12: **
   13: ** This file contains the interface definition for the quota a VFS shim.
   14: **
   15: ** This particular shim enforces a quota system on files.  One or more
   16: ** database files are in a "quota group" that is defined by a GLOB
   17: ** pattern.  A quota is set for the combined size of all files in the
   18: ** the group.  A quota of zero means "no limit".  If the total size
   19: ** of all files in the quota group is greater than the limit, then
   20: ** write requests that attempt to enlarge a file fail with SQLITE_FULL.
   21: **
   22: ** However, before returning SQLITE_FULL, the write requests invoke
   23: ** a callback function that is configurable for each quota group.
   24: ** This callback has the opportunity to enlarge the quota.  If the
   25: ** callback does enlarge the quota such that the total size of all
   26: ** files within the group is less than the new quota, then the write
   27: ** continues as if nothing had happened.
   28: */
   29: #ifndef _QUOTA_H_
   30: #include "sqlite3.h"
   31: #include <stdio.h>
   32: 
   33: /* Make this callable from C++ */
   34: #ifdef __cplusplus
   35: extern "C" {
   36: #endif
   37: 
   38: /*
   39: ** Initialize the quota VFS shim.  Use the VFS named zOrigVfsName
   40: ** as the VFS that does the actual work.  Use the default if
   41: ** zOrigVfsName==NULL.  
   42: **
   43: ** The quota VFS shim is named "quota".  It will become the default
   44: ** VFS if makeDefault is non-zero.
   45: **
   46: ** THIS ROUTINE IS NOT THREADSAFE.  Call this routine exactly once
   47: ** during start-up.
   48: */
   49: int sqlite3_quota_initialize(const char *zOrigVfsName, int makeDefault);
   50: 
   51: /*
   52: ** Shutdown the quota system.
   53: **
   54: ** All SQLite database connections must be closed before calling this
   55: ** routine.
   56: **
   57: ** THIS ROUTINE IS NOT THREADSAFE.  Call this routine exactly once while
   58: ** shutting down in order to free all remaining quota groups.
   59: */
   60: int sqlite3_quota_shutdown(void);
   61: 
   62: /*
   63: ** Create or destroy a quota group.
   64: **
   65: ** The quota group is defined by the zPattern.  When calling this routine
   66: ** with a zPattern for a quota group that already exists, this routine
   67: ** merely updates the iLimit, xCallback, and pArg values for that quota
   68: ** group.  If zPattern is new, then a new quota group is created.
   69: **
   70: ** The zPattern is always compared against the full pathname of the file.
   71: ** Even if APIs are called with relative pathnames, SQLite converts the
   72: ** name to a full pathname before comparing it against zPattern.  zPattern
   73: ** is a glob pattern with the following matching rules:
   74: **
   75: **      '*'       Matches any sequence of zero or more characters.
   76: **
   77: **      '?'       Matches exactly one character.
   78: **
   79: **     [...]      Matches one character from the enclosed list of
   80: **                characters.  "]" can be part of the list if it is
   81: **                the first character.  Within the list "X-Y" matches
   82: **                characters X or Y or any character in between the
   83: **                two.  Ex:  "[0-9]" matches any digit.
   84: **
   85: **     [^...]     Matches one character not in the enclosed list.
   86: **
   87: **     /          Matches either / or \.  This allows glob patterns
   88: **                containing / to work on both unix and windows.
   89: **
   90: ** Note that, unlike unix shell globbing, the directory separator "/"
   91: ** can match a wildcard.  So, for example, the pattern "/abc/xyz/" "*"
   92: ** matches any files anywhere in the directory hierarchy beneath
   93: ** /abc/xyz.
   94: **
   95: ** The glob algorithm works on bytes.  Multi-byte UTF8 characters are
   96: ** matched as if each byte were a separate character.
   97: **
   98: ** If the iLimit for a quota group is set to zero, then the quota group
   99: ** is disabled and will be deleted when the last database connection using
  100: ** the quota group is closed.
  101: **
  102: ** Calling this routine on a zPattern that does not exist and with a
  103: ** zero iLimit is a no-op.
  104: **
  105: ** A quota group must exist with a non-zero iLimit prior to opening
  106: ** database connections if those connections are to participate in the
  107: ** quota group.  Creating a quota group does not affect database connections
  108: ** that are already open.
  109: **
  110: ** The patterns that define the various quota groups should be distinct.
  111: ** If the same filename matches more than one quota group pattern, then
  112: ** the behavior of this package is undefined.
  113: */
  114: int sqlite3_quota_set(
  115:   const char *zPattern,           /* The filename pattern */
  116:   sqlite3_int64 iLimit,           /* New quota to set for this quota group */
  117:   void (*xCallback)(              /* Callback invoked when going over quota */
  118:      const char *zFilename,         /* Name of file whose size increases */
  119:      sqlite3_int64 *piLimit,        /* IN/OUT: The current limit */
  120:      sqlite3_int64 iSize,           /* Total size of all files in the group */
  121:      void *pArg                     /* Client data */
  122:   ),
  123:   void *pArg,                     /* client data passed thru to callback */
  124:   void (*xDestroy)(void*)         /* Optional destructor for pArg */
  125: );
  126: 
  127: /*
  128: ** Bring the named file under quota management, assuming its name matches
  129: ** the glob pattern of some quota group.  Or if it is already under
  130: ** management, update its size.  If zFilename does not match the glob
  131: ** pattern of any quota group, this routine is a no-op.
  132: */
  133: int sqlite3_quota_file(const char *zFilename);
  134: 
  135: /*
  136: ** The following object serves the same role as FILE in the standard C
  137: ** library.  It represents an open connection to a file on disk for I/O.
  138: **
  139: ** A single quota_FILE should not be used by two or more threads at the
  140: ** same time.  Multiple threads can be using different quota_FILE objects
  141: ** simultaneously, but not the same quota_FILE object.
  142: */
  143: typedef struct quota_FILE quota_FILE;
  144: 
  145: /*
  146: ** Create a new quota_FILE object used to read and/or write to the
  147: ** file zFilename.  The zMode parameter is as with standard library zMode.
  148: */
  149: quota_FILE *sqlite3_quota_fopen(const char *zFilename, const char *zMode);
  150: 
  151: /*
  152: ** Perform I/O against a quota_FILE object.  When doing writes, the
  153: ** quota mechanism may result in a short write, in order to prevent
  154: ** the sum of sizes of all files from going over quota.
  155: */
  156: size_t sqlite3_quota_fread(void*, size_t, size_t, quota_FILE*);
  157: size_t sqlite3_quota_fwrite(void*, size_t, size_t, quota_FILE*);
  158: 
  159: /*
  160: ** Flush all written content held in memory buffers out to disk.
  161: ** This is the equivalent of fflush() in the standard library.
  162: **
  163: ** If the hardSync parameter is true (non-zero) then this routine
  164: ** also forces OS buffers to disk - the equivalent of fsync().
  165: **
  166: ** This routine return zero on success and non-zero if something goes
  167: ** wrong.
  168: */
  169: int sqlite3_quota_fflush(quota_FILE*, int hardSync);
  170: 
  171: /*
  172: ** Close a quota_FILE object and free all associated resources.  The
  173: ** file remains under quota management.
  174: */
  175: int sqlite3_quota_fclose(quota_FILE*);
  176: 
  177: /*
  178: ** Move the read/write pointer for a quota_FILE object.  Or tell the
  179: ** current location of the read/write pointer.
  180: */
  181: int sqlite3_quota_fseek(quota_FILE*, long, int);
  182: void sqlite3_quota_rewind(quota_FILE*);
  183: long sqlite3_quota_ftell(quota_FILE*);
  184: 
  185: /*
  186: ** Delete a file from the disk, if that file is under quota management.
  187: ** Adjust quotas accordingly.
  188: **
  189: ** If zFilename is the name of a directory that matches one of the
  190: ** quota glob patterns, then all files under quota management that
  191: ** are contained within that directory are deleted.
  192: **
  193: ** A standard SQLite result code is returned (SQLITE_OK, SQLITE_NOMEM, etc.)
  194: ** When deleting a directory of files, if the deletion of any one
  195: ** file fails (for example due to an I/O error), then this routine
  196: ** returns immediately, with the error code, and does not try to 
  197: ** delete any of the other files in the specified directory.
  198: **
  199: ** All files are removed from quota management and deleted from disk.
  200: ** However, no attempt is made to remove empty directories.
  201: **
  202: ** This routine is a no-op for files that are not under quota management.
  203: */
  204: int sqlite3_quota_remove(const char *zFilename);
  205: 
  206: #ifdef __cplusplus
  207: }  /* end of the 'extern "C"' block */
  208: #endif
  209: #endif /* _QUOTA_H_ */