Annotation of embedaddon/sqlite3/src/test_quota.h, revision 1.1
1.1 ! misho 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_ */
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to test_quota.h CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / sqlite3 / src