** ** There are two column (M==2) and three rows (N==3). Thus the ** result table has 8 entries. Suppose the result table is stored ** in an array names azResult. Then azResult holds this content: ** **** Name | Age ** ----------------------- ** Alice | 43 ** Bob | 28 ** Cindy | 21 **
** ** The sqlite3_get_table() function evaluates one or more ** semicolon-separated SQL statements in the zero-terminated UTF-8 ** string of its 2nd parameter. It returns a result table to the ** pointer given in its 3rd parameter. ** ** After the calling function has finished using the result, it should ** pass the pointer to the result table to sqlite3_free_table() in order to ** release the memory that was malloc-ed. Because of the way the ** [sqlite3_malloc()] happens within sqlite3_get_table(), the calling ** function must not try to call [sqlite3_free()] directly. Only ** [sqlite3_free_table()] is able to release the memory properly and safely. ** ** The sqlite3_get_table() interface is implemented as a wrapper around ** [sqlite3_exec()]. The sqlite3_get_table() routine does not have access ** to any internal data structures of SQLite. It uses only the public ** interface defined here. As a consequence, errors that occur in the ** wrapper layer outside of the internal [sqlite3_exec()] call are not ** reflected in subsequent calls to [sqlite3_errcode()] or ** [sqlite3_errmsg()]. ** ** INVARIANTS: ** ** {F12371} If a [sqlite3_get_table()] fails a memory allocation, then ** it frees the result table under construction, aborts the ** query in process, skips any subsequent queries, sets the ** *resultp output pointer to NULL and returns [SQLITE_NOMEM]. ** ** {F12373} If the ncolumn parameter to [sqlite3_get_table()] is not NULL ** then [sqlite3_get_table()] write the number of columns in the ** result set of the query into *ncolumn if the query is ** successful (if the function returns SQLITE_OK). ** ** {F12374} If the nrow parameter to [sqlite3_get_table()] is not NULL ** then [sqlite3_get_table()] write the number of rows in the ** result set of the query into *nrow if the query is ** successful (if the function returns SQLITE_OK). ** ** {F12376} The [sqlite3_get_table()] function sets its *ncolumn value ** to the number of columns in the result set of the query in the ** sql parameter, or to zero if the query in sql has an empty ** result set. *) {$IFDEF S}function{$ELSE}var{$ENDIF}sqlite3_get_table{$IFDEF D}: function{$ENDIF}( db: psqlite3; (* An open database *) sql: pchar; (* SQL to be evaluated *) pResult: pppchar; (* Results of the query *) nrow: pcint; (* Number of result rows written here *) ncolumn: pcint; (* Number of result columns written here *) errmsg: ppchar (* Error msg written here *) ): cint; cdecl;{$IFDEF S}external Sqlite3Lib;{$ENDIF} {$IFDEF S}procedure{$ELSE}var{$ENDIF}sqlite3_free_table{$IFDEF D}: procedure{$ENDIF}(result: ppchar); cdecl;{$IFDEF S}external Sqlite3Lib;{$ENDIF} (* ** CAPI3REF: Formatted String Printing Functions {F17400} ** ** These routines are workalikes of the "printf()" family of functions ** from the standard C library. ** ** The sqlite3_mprintf() and sqlite3_vmprintf() routines write their ** results into memory obtained from [sqlite3_malloc()]. ** The strings returned by these two routines should be ** released by [sqlite3_free()]. Both routines return a ** NULL pointer if [sqlite3_malloc()] is unable to allocate enough ** memory to hold the resulting string. ** ** In sqlite3_snprintf() routine is similar to "snprintf()" from ** the standard C library. The result is written into the ** buffer supplied as the second parameter whose size is given by ** the first parameter. Note that the order of the ** first two parameters is reversed from snprintf(). This is an ** historical accident that cannot be fixed without breaking ** backwards compatibility. Note also that sqlite3_snprintf() ** returns a pointer to its buffer instead of the number of ** characters actually written into the buffer. We admit that ** the number of characters written would be a more useful return ** value but we cannot change the implementation of sqlite3_snprintf() ** now without breaking compatibility. ** ** As long as the buffer size is greater than zero, sqlite3_snprintf() ** guarantees that the buffer is always zero-terminated. The first ** parameter "n" is the total size of the buffer, including space for ** the zero terminator. So the longest string that can be completely ** written will be n-1 characters. ** ** These routines all implement some additional formatting ** options that are useful for constructing SQL statements. ** All of the usual printf formatting options apply. In addition, there ** is are "%q", "%Q", and "%z" options. ** ** The %q option works like %s in that it substitutes a null-terminated ** string from the argument list. But %q also doubles every '\'' character. ** %q is designed for use inside a string literal. By doubling each '\'' ** character it escapes that character and allows it to be inserted into ** the string. ** ** For example, so some string variable contains text as follows: ** **** azResult[0] = "Name"; ** azResult[1] = "Age"; ** azResult[2] = "Alice"; ** azResult[3] = "43"; ** azResult[4] = "Bob"; ** azResult[5] = "28"; ** azResult[6] = "Cindy"; ** azResult[7] = "21"; **
** ** One can use this text in an SQL statement as follows: ** **** char *zText = "It's a happy day!"; **
** char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES('%q')", zText);
** sqlite3_exec(db, zSQL, 0, 0, 0);
** sqlite3_free(zSQL);
**
** INSERT INTO table1 VALUES('It''s a happy day!')
**
** INSERT INTO table1 VALUES('It's a happy day!');
**
** char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES(%Q)", zText);
** sqlite3_exec(db, zSQL, 0, 0, 0);
** sqlite3_free(zSQL);
** SQLITE_MEMORY_SIZE=NNN** ** where NNN is an integer, then SQLite create a static ** array of at least NNN bytes in size and use that array ** for all of its dynamic memory allocation needs. {END} Additional ** memory allocator options may be added in future releases. ** ** In SQLite version 3.5.0 and 3.5.1, it was possible to define ** the SQLITE_OMIT_MEMORY_ALLOCATION which would cause the built-in ** implementation of these routines to be omitted. That capability ** is no longer provided. Only built-in memory allocators can be ** used. ** ** The windows OS interface layer calls ** the system malloc() and free() directly when converting ** filenames between the UTF-8 encoding used by SQLite ** and whatever filename encoding is used by the particular windows ** installation. Memory allocation errors are detected, but ** they are reported back as [SQLITE_CANTOPEN] or ** [SQLITE_IOERR] rather than [SQLITE_NOMEM]. ** ** INVARIANTS: ** ** {F17303} The [sqlite3_malloc(N)] interface returns either a pointer to ** newly checked-out block of at least N bytes of memory ** that is 8-byte aligned, ** or it returns NULL if it is unable to fulfill the request. ** ** {F17304} The [sqlite3_malloc(N)] interface returns a NULL pointer if ** N is less than or equal to zero. ** ** {F17305} The [sqlite3_free(P)] interface releases memory previously ** returned from [sqlite3_malloc()] or [sqlite3_realloc()], ** making it available for reuse. ** ** {F17306} A call to [sqlite3_free(NULL)] is a harmless no-op. ** ** {F17310} A call to [sqlite3_realloc(0,N)] is equivalent to a call ** to [sqlite3_malloc(N)]. ** ** {F17312} A call to [sqlite3_realloc(P,0)] is equivalent to a call ** to [sqlite3_free(P)]. ** ** {F17315} The SQLite core uses [sqlite3_malloc()], [sqlite3_realloc()], ** and [sqlite3_free()] for all of its memory allocation and ** deallocation needs. ** ** {F17318} The [sqlite3_realloc(P,N)] interface returns either a pointer ** to a block of checked-out memory of at least N bytes in size ** that is 8-byte aligned, or a NULL pointer. ** ** {F17321} When [sqlite3_realloc(P,N)] returns a non-NULL pointer, it first ** copies the first K bytes of content from P into the newly allocated ** where K is the lessor of N and the size of the buffer P. ** ** {F17322} When [sqlite3_realloc(P,N)] returns a non-NULL pointer, it first ** releases the buffer P. ** ** {F17323} When [sqlite3_realloc(P,N)] returns NULL, the buffer P is ** not modified or released. ** ** LIMITATIONS: ** ** {U17350} The pointer arguments to [sqlite3_free()] and [sqlite3_realloc()] ** must be either NULL or else a pointer obtained from a prior ** invocation of [sqlite3_malloc()] or [sqlite3_realloc()] that has ** not been released. ** ** {U17351} The application must not read or write any part of ** a block of memory after it has been released using ** [sqlite3_free()] or [sqlite3_realloc()]. ** *) {$IFDEF S}function{$ELSE}var{$ENDIF}sqlite3_malloc{$IFDEF D}: function{$ENDIF}(size: cint): pointer;cdecl;{$IFDEF S}external Sqlite3Lib;{$ENDIF} {$IFDEF S}function{$ELSE}var{$ENDIF}sqlite3_realloc{$IFDEF D}: function{$ENDIF}(ptr: pointer; size: cint): pointer;cdecl;{$IFDEF S}external Sqlite3Lib;{$ENDIF} {$IFDEF S}procedure{$ELSE}var{$ENDIF}sqlite3_free{$IFDEF D}: procedure{$ENDIF}(ptr: pointer);cdecl;{$IFDEF S}external Sqlite3Lib;{$ENDIF} (* ** CAPI3REF: Memory Allocator Statistics {F17370} ** ** SQLite provides these two interfaces for reporting on the status ** of the [sqlite3_malloc()], [sqlite3_free()], and [sqlite3_realloc()] ** the memory allocation subsystem included within the SQLite. ** ** INVARIANTS: ** ** {F17371} The [sqlite3_memory_used()] routine returns the ** number of bytes of memory currently outstanding ** (malloced but not freed). ** ** {F17373} The [sqlite3_memory_highwater()] routine returns the maximum ** value of [sqlite3_memory_used()] ** since the highwater mark was last reset. ** ** {F17374} The values returned by [sqlite3_memory_used()] and ** [sqlite3_memory_highwater()] include any overhead ** added by SQLite in its implementation of [sqlite3_malloc()], ** but not overhead added by the any underlying system library ** routines that [sqlite3_malloc()] may call. ** ** {F17375} The memory highwater mark is reset to the current value of ** [sqlite3_memory_used()] if and only if the parameter to ** [sqlite3_memory_highwater()] is true. The value returned ** by [sqlite3_memory_highwater(1)] is the highwater mark ** prior to the reset. *) {$IFDEF S}function{$ELSE}var{$ENDIF}sqlite3_memory_used{$IFDEF D}: function{$ENDIF}(): sqlite3_int64; cdecl;{$IFDEF S}external Sqlite3Lib;{$ENDIF} {$IFDEF S}function{$ELSE}var{$ENDIF}sqlite3_memory_highwater{$IFDEF D}: function{$ENDIF}(resetFlag: cint): sqlite3_int64; cdecl;{$IFDEF S}external Sqlite3Lib;{$ENDIF} (* ** CAPI3REF: Pseudo-Random Number Generator {F17390} ** ** SQLite contains a high-quality pseudo-random number generator (PRNG) used to ** select random ROWIDs when inserting new records into a table that ** already uses the largest possible ROWID. The PRNG is also used for ** the build-in random() and randomblob() SQL functions. This interface allows ** appliations to access the same PRNG for other purposes. ** ** A call to this routine stores N bytes of randomness into buffer P. ** ** The first time this routine is invoked (either internally or by ** the application) the PRNG is seeded using randomness obtained ** from the xRandomness method of the default [sqlite3_vfs] object. ** On all subsequent invocations, the pseudo-randomness is generated ** internally and without recourse to the [sqlite3_vfs] xRandomness ** method. ** ** INVARIANTS: ** ** {F17392} The [sqlite3_randomness(N,P)] interface writes N bytes of ** high-quality pseudo-randomness into buffer P. *) {$IFDEF S}procedure{$ELSE}var{$ENDIF}sqlite3_randomness{$IFDEF D}: procedure{$ENDIF}(N: cint; P: pointer); cdecl;{$IFDEF S}external Sqlite3Lib;{$ENDIF} (* ** CAPI3REF: Compile-Time Authorization Callbacks {F12500} ** ** This routine registers a authorizer callback with a particular ** [database connection], supplied in the first argument. ** The authorizer callback is invoked as SQL statements are being compiled ** by [sqlite3_prepare()] or its variants [sqlite3_prepare_v2()], ** [sqlite3_prepare16()] and [sqlite3_prepare16_v2()]. At various ** points during the compilation process, as logic is being created ** to perform various actions, the authorizer callback is invoked to ** see if those actions are allowed. The authorizer callback should ** return [SQLITE_OK] to allow the action, [SQLITE_IGNORE] to disallow the ** specific action but allow the SQL statement to continue to be ** compiled, or [SQLITE_DENY] to cause the entire SQL statement to be ** rejected with an error. If the authorizer callback returns ** any value other than [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY] ** then [sqlite3_prepare_v2()] or equivalent call that triggered ** the authorizer will fail with an error message. ** ** When the callback returns [SQLITE_OK], that means the operation ** requested is ok. When the callback returns [SQLITE_DENY], the ** [sqlite3_prepare_v2()] or equivalent call that triggered the ** authorizer will fail with an error message explaining that ** access is denied. If the authorizer code is [SQLITE_READ] ** and the callback returns [SQLITE_IGNORE] then the ** [prepared statement] statement is constructed to substitute ** a NULL value in place of the table column that would have ** been read if [SQLITE_OK] had been returned. The [SQLITE_IGNORE] ** return can be used to deny an untrusted user access to individual ** columns of a table. ** ** The first parameter to the authorizer callback is a copy of ** the third parameter to the sqlite3_set_authorizer() interface. ** The second parameter to the callback is an integer ** [SQLITE_COPY | action code] that specifies the particular action ** to be authorized. The third through sixth ** parameters to the callback are zero-terminated strings that contain ** additional details about the action to be authorized. ** ** An authorizer is used when [sqlite3_prepare | preparing] ** SQL statements from an untrusted ** source, to ensure that the SQL statements do not try to access data ** that they are not allowed to see, or that they do not try to ** execute malicious statements that damage the database. For ** example, an application may allow a user to enter arbitrary ** SQL queries for evaluation by a database. But the application does ** not want the user to be able to make arbitrary changes to the ** database. An authorizer could then be put in place while the ** user-entered SQL is being [sqlite3_prepare | prepared] that ** disallows everything except [SELECT] statements. ** ** Applications that need to process SQL from untrusted sources ** might also consider lowering resource limits using [sqlite3_limit()] ** and limiting database size using the [max_page_count] [PRAGMA] ** in addition to using an authorizer. ** ** Only a single authorizer can be in place on a database connection ** at a time. Each call to sqlite3_set_authorizer overrides the ** previous call. Disable the authorizer by installing a NULL callback. ** The authorizer is disabled by default. ** ** Note that the authorizer callback is invoked only during ** [sqlite3_prepare()] or its variants. Authorization is not ** performed during statement evaluation in [sqlite3_step()]. ** ** INVARIANTS: ** ** {F12501} The [sqlite3_set_authorizer(D,...)] interface registers a ** authorizer callback with database connection D. ** ** {F12502} The authorizer callback is invoked as SQL statements are ** being compiled ** ** {F12503} If the authorizer callback returns any value other than ** [SQLITE_IGNORE], [SQLITE_OK], or [SQLITE_DENY] then ** the [sqlite3_prepare_v2()] or equivalent call that caused ** the authorizer callback to run shall fail with an ** [SQLITE_ERROR] error code and an appropriate error message. ** ** {F12504} When the authorizer callback returns [SQLITE_OK], the operation ** described is coded normally. ** ** {F12505} When the authorizer callback returns [SQLITE_DENY], the ** [sqlite3_prepare_v2()] or equivalent call that caused the ** authorizer callback to run shall fail ** with an [SQLITE_ERROR] error code and an error message ** explaining that access is denied. ** ** {F12506} If the authorizer code (the 2nd parameter to the authorizer ** callback) is [SQLITE_READ] and the authorizer callback returns ** [SQLITE_IGNORE] then the prepared statement is constructed to ** insert a NULL value in place of the table column that would have ** been read if [SQLITE_OK] had been returned. ** ** {F12507} If the authorizer code (the 2nd parameter to the authorizer ** callback) is anything other than [SQLITE_READ], then ** a return of [SQLITE_IGNORE] has the same effect as [SQLITE_DENY]. ** ** {F12510} The first parameter to the authorizer callback is a copy of ** the third parameter to the [sqlite3_set_authorizer()] interface. ** ** {F12511} The second parameter to the callback is an integer ** [SQLITE_COPY | action code] that specifies the particular action ** to be authorized. ** ** {F12512} The third through sixth parameters to the callback are ** zero-terminated strings that contain ** additional details about the action to be authorized. ** ** {F12520} Each call to [sqlite3_set_authorizer()] overrides the ** any previously installed authorizer. ** ** {F12521} A NULL authorizer means that no authorization ** callback is invoked. ** ** {F12522} The default authorizer is NULL. *) type xAuth = function(pUserData: pointer; code: cint; s1, s2, s3, s4: pchar): cint; cdecl; {$IFDEF S}function{$ELSE}var{$ENDIF}sqlite3_set_authorizer{$IFDEF D}: function{$ENDIF}( db: psqlite3; cb: xAuth; pUserData: pointer ): cint; cdecl;{$IFDEF S}external Sqlite3Lib;{$ENDIF} (* ** CAPI3REF: Authorizer Return Codes {F12590} ** ** The [sqlite3_set_authorizer | authorizer callback function] must ** return either [SQLITE_OK] or one of these two constants in order ** to signal SQLite whether or not the action is permitted. See the ** [sqlite3_set_authorizer | authorizer documentation] for additional ** information. *) const SQLITE_DENY = 1; (* Abort the SQL statement with an error *) SQLITE_IGNORE = 2; (* Don't allow access, but don't generate an error *) (* ** CAPI3REF: Authorizer Action Codes {F12550} ** ** The [sqlite3_set_authorizer()] interface registers a callback function ** that is invoked to authorizer certain SQL statement actions. The ** second parameter to the callback is an integer code that specifies ** what action is being authorized. These are the integer action codes that ** the authorizer callback may be passed. ** ** These action code values signify what kind of operation is to be ** authorized. The 3rd and 4th parameters to the authorization ** callback function will be parameters or NULL depending on which of these ** codes is used as the second parameter. The 5th parameter to the ** authorizer callback is the name of the database ("main", "temp", ** etc.) if applicable. The 6th parameter to the authorizer callback ** is the name of the inner-most trigger or view that is responsible for ** the access attempt or NULL if this access attempt is directly from ** top-level SQL code. ** ** INVARIANTS: ** ** {F12551} The second parameter to an ** [sqlite3_set_authorizer | authorizer callback is always an integer ** [SQLITE_COPY | authorizer code] that specifies what action ** is being authorized. ** ** {F12552} The 3rd and 4th parameters to the ** [sqlite3_set_authorizer | authorization callback function] ** will be parameters or NULL depending on which ** [SQLITE_COPY | authorizer code] is used as the second parameter. ** ** {F12553} The 5th parameter to the ** [sqlite3_set_authorizer | authorizer callback] is the name ** of the database (example: "main", "temp", etc.) if applicable. ** ** {F12554} The 6th parameter to the ** [sqlite3_set_authorizer | authorizer callback] is the name ** of the inner-most trigger or view that is responsible for ** the access attempt or NULL if this access attempt is directly from ** top-level SQL code. *) (******************************************* 3rd ************ 4th ***********) const SQLITE_CREATE_INDEX = 1; (* Index Name Table Name *) SQLITE_CREATE_TABLE = 2; (* Table Name NULL *) SQLITE_CREATE_TEMP_INDEX = 3; (* Index Name Table Name *) SQLITE_CREATE_TEMP_TABLE = 4; (* Table Name NULL *) SQLITE_CREATE_TEMP_TRIGGER = 5; (* Trigger Name Table Name *) SQLITE_CREATE_TEMP_VIEW = 6; (* View Name NULL *) SQLITE_CREATE_TRIGGER = 7; (* Trigger Name Table Name *) SQLITE_CREATE_VIEW = 8; (* View Name NULL *) SQLITE_DELETE = 9; (* Table Name NULL *) SQLITE_DROP_INDEX = 10; (* Index Name Table Name *) SQLITE_DROP_TABLE = 11; (* Table Name NULL *) SQLITE_DROP_TEMP_INDEX = 12; (* Index Name Table Name *) SQLITE_DROP_TEMP_TABLE = 13; (* Table Name NULL *) SQLITE_DROP_TEMP_TRIGGER = 14; (* Trigger Name Table Name *) SQLITE_DROP_TEMP_VIEW = 15; (* View Name NULL *) SQLITE_DROP_TRIGGER = 16; (* Trigger Name Table Name *) SQLITE_DROP_VIEW = 17; (* View Name NULL *) SQLITE_INSERT = 18; (* Table Name NULL *) SQLITE_PRAGMA = 19; (* Pragma Name 1st arg or NULL *) SQLITE_READ = 20; (* Table Name Column Name *) SQLITE_SELECT = 21; (* NULL NULL *) SQLITE_TRANSACTION = 22; (* NULL NULL *) SQLITE_UPDATE = 23; (* Table Name Column Name *) SQLITE_ATTACH = 24; (* Filename NULL *) SQLITE_DETACH = 25; (* Database Name NULL *) SQLITE_ALTER_TABLE = 26; (* Database Name Table Name *) SQLITE_REINDEX = 27; (* Index Name NULL *) SQLITE_ANALYZE = 28; (* Table Name NULL *) SQLITE_CREATE_VTABLE = 29; (* Table Name Module Name *) SQLITE_DROP_VTABLE = 30; (* Table Name Module Name *) SQLITE_FUNCTION = 31; (* Function Name NULL *) SQLITE_COPY = 0; (* No longer used *) (* ** CAPI3REF: Tracing And Profiling Functions {F12280} ** ** These routines register callback functions that can be used for ** tracing and profiling the execution of SQL statements. ** ** The callback function registered by sqlite3_trace() is invoked at ** various times when an SQL statement is being run by [sqlite3_step()]. ** The callback returns a UTF-8 rendering of the SQL statement text ** as the statement first begins executing. Additional callbacks occur ** as each triggersubprogram is entered. The callbacks for triggers ** contain a UTF-8 SQL comment that identifies the trigger. ** ** The callback function registered by sqlite3_profile() is invoked ** as each SQL statement finishes. The profile callback contains ** the original statement text and an estimate of wall-clock time ** of how long that statement took to run. ** ** The sqlite3_profile() API is currently considered experimental and ** is subject to change or removal in a future release. ** ** The trigger reporting feature of the trace callback is considered ** experimental and is subject to change or removal in future releases. ** Future versions of SQLite might also add new trace callback ** invocations. ** ** INVARIANTS: ** ** {F12281} The callback function registered by [sqlite3_trace()] is ** whenever an SQL statement first begins to execute and ** whenever a trigger subprogram first begins to run. ** ** {F12282} Each call to [sqlite3_trace()] overrides the previously ** registered trace callback. ** ** {F12283} A NULL trace callback disables tracing. ** ** {F12284} The first argument to the trace callback is a copy of ** the pointer which was the 3rd argument to [sqlite3_trace()]. ** ** {F12285} The second argument to the trace callback is a ** zero-terminated UTF8 string containing the original text ** of the SQL statement as it was passed into [sqlite3_prepare_v2()] ** or the equivalent, or an SQL comment indicating the beginning ** of a trigger subprogram. ** ** {F12287} The callback function registered by [sqlite3_profile()] is invoked ** as each SQL statement finishes. ** ** {F12288} The first parameter to the profile callback is a copy of ** the 3rd parameter to [sqlite3_profile()]. ** ** {F12289} The second parameter to the profile callback is a ** zero-terminated UTF-8 string that contains the complete text of ** the SQL statement as it was processed by [sqlite3_prepare_v2()] ** or the equivalent. ** ** {F12290} The third parameter to the profile callback is an estimate ** of the number of nanoseconds of wall-clock time required to ** run the SQL statement from start to finish. *) type xTrace = procedure(user: pointer; s: pchar); cdecl; xProfile = procedure(user: pointer; s: char; i: sqlite3_uint64); cdecl; {$IFDEF S}function{$ELSE}var{$ENDIF}sqlite3_trace{$IFDEF D}: function{$ENDIF}(db: psqlite3; cb: xTrace; user: pointer): pointer; cdecl;{$IFDEF S}external Sqlite3Lib;{$ENDIF} {$IFDEF S}function{$ELSE}var{$ENDIF}sqlite3_profile{$IFDEF D}: function{$ENDIF}(db: psqlite3; cb: xProfile; user: pointer): pointer; cdecl;{$IFDEF S}external Sqlite3Lib;{$ENDIF} (* ** CAPI3REF: Query Progress Callbacks {F12910} ** ** This routine configures a callback function - the ** progress callback - that is invoked periodically during long ** running calls to [sqlite3_exec()], [sqlite3_step()] and ** [sqlite3_get_table()]. An example use for this ** interface is to keep a GUI updated during a large query. ** ** If the progress callback returns non-zero, the opertion is ** interrupted. This feature can be used to implement a ** "Cancel" button on a GUI dialog box. ** ** INVARIANTS: ** ** {F12911} The callback function registered by [sqlite3_progress_handler()] ** is invoked periodically during long running calls to ** [sqlite3_step()]. ** ** {F12912} The progress callback is invoked once for every N virtual ** machine opcodes, where N is the second argument to ** the [sqlite3_progress_handler()] call that registered ** the callback.
**** ** The table above makes reference to standard C library functions atoi() ** and atof(). SQLite does not really use these functions. It has its ** on equavalent cinternal routines. The atoi() and atof() names are ** used in the table for brevity and because they are familiar to most ** C programmers. ** ** Note that when type conversions occur, pointers returned by prior ** calls to sqlite3_column_blob(), sqlite3_column_text(), and/or ** sqlite3_column_text16() may be invalidated. ** Type conversions and pointer invalidations might occur ** in the following cases: ** ****
**cinternal
TypeRequested
TypeConversion ** ** NULL INTEGER Result is 0 ** NULL FLOAT Result is 0.0 ** NULL TEXT Result is NULL pointer ** NULL BLOB Result is NULL pointer ** INTEGER FLOAT Convert from INTEGER to float ** INTEGER TEXT ASCII rendering of the INTEGER ** INTEGER BLOB Same as for INTEGER->TEXT ** FLOAT INTEGER Convert from float to INTEGER ** FLOAT TEXT ASCII rendering of the float ** FLOAT BLOB Same as FLOAT->TEXT ** TEXT INTEGER Use atoi() ** TEXT FLOAT Use atof() ** TEXT BLOB No change ** BLOB INTEGER Convert to TEXT then use atoi() ** BLOB FLOAT Convert to TEXT then use atof() ** BLOB TEXT Add a zero terminator if needed **
The initial content is a BLOB and sqlite3_column_text() ** or sqlite3_column_text16() is called. A zero-terminator might ** need to be added to the string.
The initial content is UTF-8 text and sqlite3_column_bytes16() or ** sqlite3_column_text16() is called. The content must be converted ** to UTF-16.
The initial content is UTF-16 text and sqlite3_column_bytes() or ** sqlite3_column_text() is called. The content must be converted ** to UTF-8.
** Parameter Output Type Description ** ----------------------------------- ** ** 5th const char* Data type ** 6th const char* Name of the default collation sequence ** 7th cint True if the column has a NOT NULL constracint ** 8th cint True if the column is part of the PRIMARY KEY ** 9th cint True if the column is AUTOINCREMENT **** ** ** The memory pointed to by the character pointers returned for the ** declaration type and collation sequence is valid only until the next ** call to any sqlite API function. ** ** If the specified table is actually a view; then an error is returned. ** ** If the specified column is "rowid"; "oid" or "_rowid_" and an ** INTEGER PRIMARY KEY column has been explicitly declared; then the output ** parameters are set for the explicitly declared column. If there is no ** explicitly declared IPK column; then the output parameters are set as ** follows: ** **
** data type: "INTEGER" ** collation sequence: "BINARY" ** not null: 0 ** primary key: 1 ** auto increment: 0 **** ** This function may load one or more schemas from database files. If an ** error occurs during this process; or if the requested table or column ** cannot be found; an SQLITE error code is returned and an error message ** left in the database handle (to be retrieved using sqlite3_errmsg()). ** ** This API is only available if the library was compiled with the ** SQLITE_ENABLE_COLUMN_METADATA preprocessor symbol defined. *) {$IFDEF S}function{$ELSE}var{$ENDIF}sqlite3_table_column_metadata{$IFDEF D}: function{$ENDIF}( db: psqlite3; (* Connection handle *) zDbName: pchar; (* Database name or NULL *) zTableName: pchar; (* Table name *) zColumnName: pchar; (* Column name *) pzDataType: ppchar; (* OUTPUT: Declared data type *) pzCollSeq: ppchar; (* OUTPUT: Collation sequence name *) pNotNull: pcint; (* OUTPUT: True if NOT NULL constracint exists *) pPrimaryKey: pcint; (* OUTPUT: True if column part of PK *) pAutoinc: pcint (* OUTPUT: True if column is auto-increment *) ): cint; cdecl;{$IFDEF S}external Sqlite3Lib;{$ENDIF} (* ** CAPI3REF: Load An Extension {F12600} ** ** {F12601} The sqlite3_load_extension() interface ** attempts to load an SQLite extension library contained in the file ** zFile. {F12602} The entry point is zProc. {F12603} zProc may be 0 ** in which case the name of the entry point defaults ** to "sqlite3_extension_init". ** ** {F12604} The sqlite3_load_extension() interface shall ** return [SQLITE_OK] on success and [SQLITE_ERROR] if something goes wrong. ** ** {F12605} ** If an error occurs and pzErrMsg is not 0; then the ** sqlite3_load_extension() interface shall attempt to fill *pzErrMsg with ** error message text stored in memory obtained from [sqlite3_malloc()]. ** {END} The calling function should free this memory ** by calling [sqlite3_free()]. ** ** {F12606} ** Extension loading must be enabled using [sqlite3_enable_load_extension()] ** prior to calling this API or an error will be returned. *) {$IFDEF S}function{$ELSE}var{$ENDIF}sqlite3_load_extension{$IFDEF D}: function{$ENDIF}( db: psqlite3; (* Load the extension cinto this database connection *) zFile: pchar; (* Name of the shared library containing extension *) zProc: pchar; (* Entry point. Derived from zFile if 0 *) pzErrMsg: ppchar (* Put error message here if not 0 *) ): cint; cdecl;{$IFDEF S}external Sqlite3Lib;{$ENDIF} (* ** CAPI3REF: Enable Or Disable Extension Loading {F12620} ** ** So as not to open security holes in older applications that are ** unprepared to deal with extension loading; and as a means of disabling ** extension loading while evaluating user-entered SQL; the following ** API is provided to turn the [sqlite3_load_extension()] mechanism on and ** off. {F12622} It is off by default. {END} See ticket #1863. ** ** {F12621} Call the sqlite3_enable_load_extension() routine ** with onoff==1 to turn extension loading on ** and call it with onoff==0 to turn it back off again. {END} *) {$IFDEF S}function{$ELSE}var{$ENDIF}sqlite3_enable_load_extension{$IFDEF D}: function{$ENDIF}(db: psqlite3; onoff: cint): cint; cdecl;{$IFDEF S}external Sqlite3Lib;{$ENDIF} (* ** CAPI3REF: Make Arrangements To Automatically Load An Extension {F12640} ** ** {F12641} This function ** registers an extension entry point that is automatically invoked ** whenever a new database connection is opened using ** [sqlite3_open()]; [sqlite3_open16()]; or [sqlite3_open_v2()]. {END} ** ** This API can be invoked at program startup in order to register ** one or more statically linked extensions that will be available ** to all new database connections. ** ** {F12642} Duplicate extensions are detected so calling this routine multiple ** times with the same extension is harmless. ** ** {F12643} This routine stores a pointer to the extension in an array ** that is obtained from sqlite_malloc(). {END} If you run a memory leak ** checker on your program and it reports a leak because of this ** array; then invoke [sqlite3_reset_auto_extension()] prior ** to shutdown to free the memory. ** ** {F12644} Automatic extensions apply across all threads. {END} ** ** This interface is experimental and is subject to change or ** removal in future releases of SQLite. *) {$IFDEF S}function{$ELSE}var{$ENDIF}sqlite3_auto_extension{$IFDEF D}: function{$ENDIF}(xEntrypoint: pointer): cint; cdecl;{$IFDEF S}external Sqlite3Lib;{$ENDIF} (* ** CAPI3REF: Reset Automatic Extension Loading {F12660} ** ** {F12661} This function disables all previously registered ** automatic extensions. {END} This ** routine undoes the effect of all prior [sqlite3_auto_extension()] ** calls. ** ** {F12662} This call disabled automatic extensions in all threads. {END} ** ** This interface is experimental and is subject to change or ** removal in future releases of SQLite. *) {$IFDEF S}procedure{$ELSE}var{$ENDIF}sqlite3_reset_auto_extension{$IFDEF D}: procedure{$ENDIF}(); cdecl;{$IFDEF S}external Sqlite3Lib;{$ENDIF} (* ****** EXPERIMENTAL - subject to change without notice ************** ** ** The interface to the virtual-table mechanism is currently considered ** to be experimental. The interface might change in incompatible ways. ** If this is a problem for you; do not use the interface at this time. ** ** When the virtual-table mechanism stablizes; we will declare the ** interface fixed; support it indefinitely; and remove this comment. *) (* ** CAPI3REF: Virtual Table Object {F18000} ** KEYWORDS: sqlite3_module ** ** A module is a class of virtual tables. Each module is defined ** by an instance of the following structure. This structure consists ** mostly of methods for the module. *) type psqlite3_module = ^sqlite3_module; sqlite3_module = record{ iVersion : cint; // xCreate : function(db: psqlite3; pAux: pointer; argc: cint; ): cint; cdecl; cint (*xCreate)(db: psqlite3; void *pAux; cint argc; const char *const*argv; sqlite3_vtab **ppVTab; char**); cint (*xConnect)(db: psqlite3; void *pAux; cint argc; const char *const*argv; sqlite3_vtab **ppVTab; char**); cint (*xBestIndex)(sqlite3_vtab *pVTab; sqlite3_index_info*); cint (*xDisconnect)(sqlite3_vtab *pVTab); cint (*xDestroy)(sqlite3_vtab *pVTab); cint (*xOpen)(sqlite3_vtab *pVTab; sqlite3_vtab_cursor **ppCursor); cint (*xClose)(sqlite3_vtab_cursor*); cint (*xFilter)(sqlite3_vtab_cursor*; cint idxNum; const char *idxStr; cint argc; sqlite3_value **argv); xNext : function(pVCurs: sqlite3_vtab_cursor): cint; cdecl; xEof : function(pVCurs: sqlite3_vtab_cursor): cint; cdecl; xColumn : function(pVCurs: sqlite3_vtab_cursor; ctx: psqlite3_context; i: cint): cint; cdecl; xRowid : function(pVCurs: sqlite3_vtab_cursor; var pRowid: sqlite3_int64): cint; cdecl; xUpdate : function(pVtab: psqlite3_vtab; var v: psqlite3_value; var p: sqlite3_int64): cint; cdecl; xBegin : function(pVtab: psqlite3_vtab): cint; cdecl; xSync : function(pVtab: psqlite3_vtab): cint; cdecl; xCommit : function(pVtab: psqlite3_vtab): cint; cdecl; xRollback : function(pVtab: psqlite3_vtab): cint; cdecl; xFindFunction : function(pVtab: psqlite3_vtab; nArg: cint; zName: pchar; var pxFunc: xFunc; var ppArg: pointer): cint; cdecl; xRename : function(pVtab: psqlite3_vtab; zNew: pchar): cint; cdecl; }end; {.$WARNING TODO} (* ** CAPI3REF: Virtual Table Indexing Information {F18100} ** KEYWORDS: sqlite3_index_info ** ** The sqlite3_index_info structure and its substructures is used to ** pass information cinto and receive the reply from the xBestIndex ** method of an sqlite3_module. The fields under **Inputs** are the ** inputs to xBestIndex and are read-only. xBestIndex inserts its ** results cinto the **Outputs** fields. ** ** The aConstracint[] array records WHERE clause constracints of the ** form: ** ** column OP expr ** ** Where OP is =; <; <=; >; or >=. ** The particular operator is stored ** in aConstracint[].op. The index of the column is stored in ** aConstracint[].iColumn. aConstracint[].usable is TRUE if the ** expr on the right-hand side can be evaluated (and thus the constracint ** is usable) and false if it cannot. ** ** The optimizer automatically inverts terms of the form "expr OP column" ** and makes other simplifications to the WHERE clause in an attempt to ** get as many WHERE clause terms cinto the form shown above as possible. ** The aConstracint[] array only reports WHERE clause terms in the correct ** form that refer to the particular virtual table being queried. ** ** Information about the ORDER BY clause is stored in aOrderBy[]. ** Each term of aOrderBy records a column of the ORDER BY clause. ** ** The xBestIndex method must fill aConstracintUsage[] with information ** about what parameters to pass to xFilter. If argvIndex>0 then ** the right-hand side of the corresponding aConstracint[] is evaluated ** and becomes the argvIndex-th entry in argv. If aConstracintUsage[].omit ** is true; then the constracint is assumed to be fully handled by the ** virtual table and is not checked again by SQLite. ** ** The idxNum and idxPtr values are recorded and passed cinto xFilter. ** sqlite3_free() is used to free idxPtr if needToFreeIdxPtr is true. ** ** The orderByConsumed means that output from xFilter will occur in ** the correct order to satisfy the ORDER BY clause so that no separate ** sorting step is required. ** ** The estimatedCost value is an estimate of the cost of doing the ** particular lookup. A full scan of a table with N entries should have ** a cost of N. A binary search of a table of N entries should have a ** cost of approximately log(N). *) type psqlite3_index_constracint = ^sqlite3_index_constracint; sqlite3_index_constracint = record iColumn: cint; (* Column on left-hand side of constracint *) op: char; (* Constracint operator *) usable: char; (* True if this constracint is usable *) iTermOffset: cint; (* Used cinternally - xBestIndex should ignore *) end; psqlite3_index_orderby = ^sqlite3_index_orderby; sqlite3_index_orderby = record iColumn: cint; (* Column number *) desc: char; (* True for DESC. False for ASC. *) end; psqlite3_index_constracint_usage = ^sqlite3_index_constracint_usage; sqlite3_index_constracint_usage = record argvIndex: cint; (* if >0; constracint is part of argv to xFilter *) omit: char; (* Do not code a test for this constracint *) end; psqlite3_index_info = ^sqlite3_index_info; sqlite3_index_info = record (* Inputs *) nConstracint: cint; (* Number of entries in aConstracint *) aConstracint: psqlite3_index_constracint; nOrderBy: cint; (* Number of terms in the ORDER BY clause *) aOrderBy: psqlite3_index_orderby; (* Outputs *) aConstracintUsage: psqlite3_index_constracint_usage; idxNum: cint; (* Number used to identify the index *) idxStr: pchar; (* String; possibly obtained from sqlite3_malloc *) needToFreeIdxStr: cint; (* Free idxStr using sqlite3_free() if true *) orderByConsumed: cint; (* True if output is already ordered *) estimatedCost: cdouble; (* Estimated cost of using this index *) end; const SQLITE_INDEX_CONSTRAINT_EQ = 2; SQLITE_INDEX_CONSTRAINT_GT = 4; SQLITE_INDEX_CONSTRAINT_LE = 8; SQLITE_INDEX_CONSTRAINT_LT = 16; SQLITE_INDEX_CONSTRAINT_GE = 32; SQLITE_INDEX_CONSTRAINT_MATCH = 64; (* ** CAPI3REF: Register A Virtual Table Implementation {F18200} ** ** This routine is used to register a new module name with an SQLite ** connection. Module names must be registered before creating new ** virtual tables on the module; or before using preexisting virtual ** tables of the module. *) {$IFDEF S}function{$ELSE}var{$ENDIF}sqlite3_create_module{$IFDEF D}: function{$ENDIF}( db: psqlite3; (* SQLite connection to register module with *) zName: pchar; (* Name of the module *) module: psqlite3_module; (* Methods for the module *) user: pointer (* Client data for xCreate/xConnect *) ): cint; cdecl;{$IFDEF S}external Sqlite3Lib;{$ENDIF} (* ** CAPI3REF: Register A Virtual Table Implementation {F18210} ** ** This routine is identical to the sqlite3_create_module() method above; ** except that it allows a destructor function to be specified. It is ** even more experimental than the rest of the virtual tables API. *) {$IFDEF S}function{$ELSE}var{$ENDIF}sqlite3_create_module_v2{$IFDEF D}: function{$ENDIF}( db: psqlite3; (* SQLite connection to register module with *) zName: pchar; (* Name of the module *) module: psqlite3_module; (* Methods for the module *) user: pointer; (* Client data for xCreate/xConnect *) xdestroycb: xDestroy (* Module destructor function *) ): cint; cdecl;{$IFDEF S}external Sqlite3Lib;{$ENDIF} (* ** CAPI3REF: Virtual Table Instance Object {F18010} ** KEYWORDS: sqlite3_vtab ** ** Every module implementation uses a subclass of the following structure ** to describe a particular instance of the module. Each subclass will ** be tailored to the specific needs of the module implementation. The ** purpose of this superclass is to define certain fields that are common ** to all module implementations. ** ** Virtual tables methods can set an error message by assigning a ** string obtained from sqlite3_mprcintf() to zErrMsg. The method should ** take care that any prior string is freed by a call to sqlite3_free() ** prior to assigning a new string to zErrMsg. After the error message ** is delivered up to the client application; the string will be automatically ** freed by sqlite3_free() and the zErrMsg field will be zeroed. Note ** that sqlite3_mprcintf() and sqlite3_free() are used on the zErrMsg field ** since virtual tables are commonly implemented in loadable extensions which ** do not have access to sqlite3MPrcintf() or sqlite3Free(). *) type psqlite3_vtab = ^sqlite3_vtab; sqlite3_vtab = record pModule: psqlite3_module; (* The module for this virtual table *) nRef: cint; (* Used cinternally *) zErrMsg: pchar; (* Error message from sqlite3_mprcintf() *) (* Virtual table implementations will typically add additional fields *) end; (* ** CAPI3REF: Virtual Table Cursor Object {F18020} ** KEYWORDS: sqlite3_vtab_cursor ** ** Every module implementation uses a subclass of the following structure ** to describe cursors that point cinto the virtual table and are used ** to loop through the virtual table. Cursors are created using the ** xOpen method of the module. Each module implementation will define ** the content of a cursor structure to suit its own needs. ** ** This superclass exists in order to define fields of the cursor that ** are common to all implementations. *) type psqlite3_vtab_cursor = ^sqlite3_vtab_cursor; sqlite3_vtab_cursor = record pVtab: psqlite3_vtab; (* Virtual table of this cursor *) (* Virtual table implementations will typically add additional fields *) end; (* ** CAPI3REF: Declare The Schema Of A Virtual Table {F18280} ** ** The xCreate and xConnect methods of a module use the following API ** to declare the format (the names and datatypes of the columns) of ** the virtual tables they implement. *) {$IFDEF S}function{$ELSE}var{$ENDIF}sqlite3_declare_vtab{$IFDEF D}: function{$ENDIF}(db: psqlite3; zCreateTable: pchar): cint; cdecl;{$IFDEF S}external Sqlite3Lib;{$ENDIF} (* ** CAPI3REF: Overload A Function For A Virtual Table {F18300} ** ** Virtual tables can provide alternative implementations of functions ** using the xFindFunction method. But global versions of those functions ** must exist in order to be overloaded. ** ** This API makes sure a global version of a function with a particular ** name and number of parameters exists. If no such function exists ** before this API is called; a new function is created. The implementation ** of the new function always causes an exception to be thrown. So ** the new function is not good for anything by itself. Its only ** purpose is to be a place-holder function that can be overloaded ** by virtual tables. ** ** This API should be considered part of the virtual table interface; ** which is experimental and subject to change. *) {$IFDEF S}function{$ELSE}var{$ENDIF}sqlite3_overload_function{$IFDEF D}: function{$ENDIF}(db: psqlite3; zFuncName: pchar; nArg: cint): cint; cdecl;{$IFDEF S}external Sqlite3Lib;{$ENDIF} (* ** The interface to the virtual-table mechanism defined above (back up ** to a comment remarkably similar to this one) is currently considered ** to be experimental. The interface might change in incompatible ways. ** If this is a problem for you; do not use the interface at this time. ** ** When the virtual-table mechanism stabilizes; we will declare the ** interface fixed; support it indefinitely; and remove this comment. ** ****** EXPERIMENTAL - subject to change without notice ************** *) (* ** CAPI3REF: A Handle To An Open BLOB {F17800} ** ** An instance of this object represents an open BLOB on which ** incremental I/O can be preformed. ** Objects of this type are created by ** [sqlite3_blob_open()] and destroyed by [sqlite3_blob_close()]. ** The [sqlite3_blob_read()] and [sqlite3_blob_write()] interfaces ** can be used to read or write small subsections of the blob. ** The [sqlite3_blob_bytes()] interface returns the size of the ** blob in bytes. *) type ppsqlite3_blob = ^psqlite3_blob; psqlite3_blob = ^sqlite3_blob; sqlite3_blob = record end; (* ** CAPI3REF: Open A BLOB For Incremental I/O {F17810} ** ** This interfaces opens a handle to the blob located ** in row iRow; column zColumn; table zTable in database zDb; ** in other words; the same blob that would be selected by: ** **
** SELECT zColumn FROM zDb.zTable WHERE rowid = iRow; **{END} ** ** If the flags parameter is non-zero; the blob is opened for ** read and write access. If it is zero; the blob is opened for read ** access. ** ** Note that the database name is not the filename that contains ** the database but rather the symbolic name of the database that ** is assigned when the database is connected using [ATTACH]. ** For the main database file; the database name is "main". For ** TEMP tables; the database name is "temp". ** ** On success; [SQLITE_OK] is returned and the new ** [sqlite3_blob | blob handle] is written to *ppBlob. ** Otherwise an error code is returned and ** any value written to *ppBlob should not be used by the caller. ** This function sets the database-handle error code and message ** accessible via [sqlite3_errcode()] and [sqlite3_errmsg()]. ** ** INVARIANTS: ** ** {F17813} A successful invocation of the [sqlite3_blob_open(D;B;T;C;R;F;P)] ** interface opens an [sqlite3_blob] object P on the blob ** in column C of table T in database B on [database connection] D. ** ** {F17814} A successful invocation of [sqlite3_blob_open(D;...)] starts ** a new transaction on [database connection] D if that connection ** is not already in a transaction. ** ** {F17816} The [sqlite3_blob_open(D;B;T;C;R;F;P)] interface opens the blob ** for read and write access if and only if the F parameter ** is non-zero. ** ** {F17819} The [sqlite3_blob_open()] interface returns [SQLITE_OK] on ** success and an appropriate [error code] on failure. ** ** {F17821} If an error occurs during evaluation of [sqlite3_blob_open(D;...)] ** then subsequent calls to [sqlite3_errcode(D)]; ** [sqlite3_errmsg(D)]; and [sqlite3_errmsg16(D)] will return ** information approprate for that error. *) {$IFDEF S}function{$ELSE}var{$ENDIF}sqlite3_blob_open{$IFDEF D}: function{$ENDIF}( db: psqlite3; zDb: pchar; zTable: pchar; zColumn: pchar; iRow: sqlite3_int64; flags: cint; ppBlob: ppsqlite3_blob ): cint; cdecl;{$IFDEF S}external Sqlite3Lib;{$ENDIF} (* ** CAPI3REF: Close A BLOB Handle {F17830} ** ** Close an open [sqlite3_blob | blob handle]. ** ** Closing a BLOB shall cause the current transaction to commit ** if there are no other BLOBs; no pending prepared statements; and the ** database connection is in autocommit mode. ** If any writes were made to the BLOB; they might be held in cache ** until the close operation if they will fit. {END} ** Closing the BLOB often forces the changes ** out to disk and so if any I/O errors occur; they will likely occur ** at the time when the BLOB is closed. {F17833} Any errors that occur during ** closing are reported as a non-zero return value. ** ** The BLOB is closed unconditionally. Even if this routine returns ** an error code; the BLOB is still closed. ** ** INVARIANTS: ** ** {F17833} The [sqlite3_blob_close(P)] interface closes an ** [sqlite3_blob] object P previously opened using ** [sqlite3_blob_open()]. ** ** {F17836} Closing an [sqlite3_blob] object using ** [sqlite3_blob_close()] shall cause the current transaction to ** commit if there are no other open [sqlite3_blob] objects ** or [prepared statements] on the same [database connection] and ** the [database connection] is in ** [sqlite3_get_autocommit | autocommit mode]. ** ** {F17839} The [sqlite3_blob_close(P)] interfaces closes the ** [sqlite3_blob] object P unconditionally; even if ** [sqlite3_blob_close(P)] returns something other than [SQLITE_OK]. ** *) {$IFDEF S}function{$ELSE}var{$ENDIF}sqlite3_blob_close{$IFDEF D}: function{$ENDIF}(blob: psqlite3_blob): cint; cdecl;{$IFDEF S}external Sqlite3Lib;{$ENDIF} (* ** CAPI3REF: Return The Size Of An Open BLOB {F17840} ** ** Return the size in bytes of the blob accessible via the open ** [sqlite3_blob] object in its only argument. ** ** INVARIANTS: ** ** {F17843} The [sqlite3_blob_bytes(P)] interface returns the size ** in bytes of the BLOB that the [sqlite3_blob] object P ** refers to. *) {$IFDEF S}function{$ELSE}var{$ENDIF}sqlite3_blob_bytes{$IFDEF D}: function{$ENDIF}(blob: psqlite3_blob): cint; cdecl;{$IFDEF S}external Sqlite3Lib;{$ENDIF} (* ** CAPI3REF: Read Data From A BLOB Incrementally {F17850} ** ** This function is used to read data from an open ** [sqlite3_blob | blob-handle] cinto a caller supplied buffer. ** N bytes of data are copied cinto buffer ** Z from the open blob; starting at offset iOffset. ** ** If offset iOffset is less than N bytes from the end of the blob; ** [SQLITE_ERROR] is returned and no data is read. If N or iOffset is ** less than zero [SQLITE_ERROR] is returned and no data is read. ** ** On success; SQLITE_OK is returned. Otherwise; an ** [error code] or an [extended error code] is returned. ** ** INVARIANTS: ** ** {F17853} The [sqlite3_blob_read(P;Z;N;X)] interface reads N bytes ** beginning at offset X from ** the blob that [sqlite3_blob] object P refers to ** and writes those N bytes cinto buffer Z. ** ** {F17856} In [sqlite3_blob_read(P;Z;N;X)] if the size of the blob ** is less than N+X bytes; then the function returns [SQLITE_ERROR] ** and nothing is read from the blob. ** ** {F17859} In [sqlite3_blob_read(P;Z;N;X)] if X or N is less than zero ** then the function returns [SQLITE_ERROR] ** and nothing is read from the blob. ** ** {F17862} The [sqlite3_blob_read(P;Z;N;X)] interface returns [SQLITE_OK] ** if N bytes where successfully read cinto buffer Z. ** ** {F17865} If the requested read could not be completed; ** the [sqlite3_blob_read(P;Z;N;X)] interface returns an ** appropriate [error code] or [extended error code]. ** ** {F17868} If an error occurs during evaluation of [sqlite3_blob_read(P;...)] ** then subsequent calls to [sqlite3_errcode(D)]; ** [sqlite3_errmsg(D)]; and [sqlite3_errmsg16(D)] will return ** information approprate for that error; where D is the ** database handle that was used to open blob handle P. *) {$IFDEF S}function{$ELSE}var{$ENDIF}sqlite3_blob_read{$IFDEF D}: function{$ENDIF}(blob: psqlite3_blob; Z: pointer; N: cint; iOffset: cint): cint; cdecl;{$IFDEF S}external Sqlite3Lib;{$ENDIF} (* ** CAPI3REF: Write Data cinto A BLOB Incrementally {F17870} ** ** This function is used to write data cinto an open ** [sqlite3_blob | blob-handle] from a user supplied buffer. ** n bytes of data are copied from the buffer ** pointed to by z cinto the open blob; starting at offset iOffset. ** ** If the [sqlite3_blob | blob-handle] passed as the first argument ** was not opened for writing (the flags parameter to [sqlite3_blob_open()] *** was zero); this function returns [SQLITE_READONLY]. ** ** This function may only modify the contents of the blob; it is ** not possible to increase the size of a blob using this API. ** If offset iOffset is less than n bytes from the end of the blob; ** [SQLITE_ERROR] is returned and no data is written. If n is ** less than zero [SQLITE_ERROR] is returned and no data is written. ** ** On success; SQLITE_OK is returned. Otherwise; an ** [error code] or an [extended error code] is returned. ** ** INVARIANTS: ** ** {F17873} The [sqlite3_blob_write(P;Z;N;X)] interface writes N bytes ** from buffer Z cinto ** the blob that [sqlite3_blob] object P refers to ** beginning at an offset of X cinto the blob. ** ** {F17875} The [sqlite3_blob_write(P;Z;N;X)] interface returns ** [SQLITE_READONLY] if the [sqlite3_blob] object P was ** [sqlite3_blob_open | opened] for reading only. ** ** {F17876} In [sqlite3_blob_write(P;Z;N;X)] if the size of the blob ** is less than N+X bytes; then the function returns [SQLITE_ERROR] ** and nothing is written cinto the blob. ** ** {F17879} In [sqlite3_blob_write(P;Z;N;X)] if X or N is less than zero ** then the function returns [SQLITE_ERROR] ** and nothing is written cinto the blob. ** ** {F17882} The [sqlite3_blob_write(P;Z;N;X)] interface returns [SQLITE_OK] ** if N bytes where successfully written cinto blob. ** ** {F17885} If the requested write could not be completed; ** the [sqlite3_blob_write(P;Z;N;X)] interface returns an ** appropriate [error code] or [extended error code]. ** ** {F17888} If an error occurs during evaluation of [sqlite3_blob_write(D;...)] ** then subsequent calls to [sqlite3_errcode(D)]; ** [sqlite3_errmsg(D)]; and [sqlite3_errmsg16(D)] will return ** information approprate for that error. *) {$IFDEF S}function{$ELSE}var{$ENDIF}sqlite3_blob_write{$IFDEF D}: function{$ENDIF}(blob: psqlite3_blob; Z: pointer; N: cint; iOffset: cint): cint; cdecl;{$IFDEF S}external Sqlite3Lib;{$ENDIF} (* ** CAPI3REF: Virtual File System Objects {F11200} ** ** A virtual filesystem (VFS) is an [sqlite3_vfs] object ** that SQLite uses to cinteract ** with the underlying operating system. Most SQLite builds come with a ** single default VFS that is appropriate for the host computer. ** New VFSes can be registered and existing VFSes can be unregistered. ** The following interfaces are provided. ** ** The sqlite3_vfs_find() interface returns a pointer to ** a VFS given its name. Names are case sensitive. ** Names are zero-terminated UTF-8 strings. ** If there is no match; a NULL ** pointer is returned. If zVfsName is NULL then the default ** VFS is returned. ** ** New VFSes are registered with sqlite3_vfs_register(). ** Each new VFS becomes the default VFS if the makeDflt flag is set. ** The same VFS can be registered multiple times without injury. ** To make an existing VFS cinto the default VFS; register it again ** with the makeDflt flag set. If two different VFSes with the ** same name are registered; the behavior is undefined. If a ** VFS is registered with a name that is NULL or an empty string; ** then the behavior is undefined. ** ** Unregister a VFS with the sqlite3_vfs_unregister() interface. ** If the default VFS is unregistered; another VFS is chosen as ** the default. The choice for the new VFS is arbitrary. ** ** INVARIANTS: ** ** {F11203} The [sqlite3_vfs_find(N)] interface returns a pointer to the ** registered [sqlite3_vfs] object whose name exactly matches ** the zero-terminated UTF-8 string N; or it returns NULL if ** there is no match. ** ** {F11206} If the N parameter to [sqlite3_vfs_find(N)] is NULL then ** the function returns a pointer to the default [sqlite3_vfs] ** object if there is one; or NULL if there is no default ** [sqlite3_vfs] object. ** ** {F11209} The [sqlite3_vfs_register(P;F)] interface registers the ** well-formed [sqlite3_vfs] object P using the name given ** by the zName field of the object. ** ** {F11212} Using the [sqlite3_vfs_register(P;F)] interface to register ** the same [sqlite3_vfs] object multiple times is a harmless no-op. ** ** {F11215} The [sqlite3_vfs_register(P;F)] interface makes the ** the [sqlite3_vfs] object P the default [sqlite3_vfs] object ** if F is non-zero. ** ** {F11218} The [sqlite3_vfs_unregister(P)] interface unregisters the ** [sqlite3_vfs] object P so that it is no longer returned by ** subsequent calls to [sqlite3_vfs_find()]. *) {$IFDEF S}function{$ELSE}var{$ENDIF}sqlite3_vfs_find{$IFDEF D}: function{$ENDIF}(zVfsName: pchar): psqlite3_vfs; cdecl;{$IFDEF S}external Sqlite3Lib;{$ENDIF} {$IFDEF S}function{$ELSE}var{$ENDIF}sqlite3_vfs_register{$IFDEF D}: function{$ENDIF}(vfs: psqlite3_vfs; makeDflt: cint): cint; cdecl;{$IFDEF S}external Sqlite3Lib;{$ENDIF} {$IFDEF S}function{$ELSE}var{$ENDIF}sqlite3_vfs_unregister{$IFDEF D}: function{$ENDIF}(vfs: psqlite3_vfs): cint; cdecl;{$IFDEF S}external Sqlite3Lib;{$ENDIF} (* ** CAPI3REF: Mutexes {F17000} ** ** The SQLite core uses these routines for thread ** synchronization. Though they are cintended for cinternal ** use by SQLite; code that links against SQLite is ** permitted to use any of these routines. ** ** The SQLite source code contains multiple implementations ** of these mutex routines. An appropriate implementation ** is selected automatically at compile-time. The following ** implementations are available in the SQLite core: ** **