Sq3Lite_Config_C_API

Sq3Lite PACKAGE - configure the applicatione … More...

Collaboration diagram for Sq3Lite_Config_C_API:

Macros
#define	Sq3Fupu_Sq3LiteProgressHandler_X_ret   MK_I32
#define	Sq3Fupu_Sq3LiteProgressHandler_X_args   MK_PTR P
#define	Sq3Fupu_Sq3LiteSetAuthorizer_xAuth_ret   MK_I32
#define	Sq3Fupu_Sq3LiteSetAuthorizer_xAuth_args   MK_PTR pUserData, MK_I32 auth_action_code, MK_STRN arg2, MK_STRN arg3, MK_STRN arg4, MK_STRN arg5

Typedefs
typedef Sq3Fupu_Sq3LiteProgressHandler_X_ret(*	libsq3lite::Sq3Fupu_Sq3LiteProgressHandler_X) (Sq3Fupu_Sq3LiteProgressHandler_X_args)
typedef Sq3Fupu_Sq3LiteSetAuthorizer_xAuth_ret(*	libsq3lite::Sq3Fupu_Sq3LiteSetAuthorizer_xAuth) (Sq3Fupu_Sq3LiteSetAuthorizer_xAuth_args)

Functions
static MK_STRN	libsq3lite::Sq3CompileOptionGet (MK_I32 N)
	Run-Time Library Compilation Options Diagnostics …
static MK_BOOL	libsq3lite::Sq3CompileOptionUsed (MK_STRN zOptName)
	Run-Time Library Compilation Options Diagnostics …
static void	libsq3lite::Sq3LiteProgressHandler (SQ3_LITE sq3lite, MK_I32 N, Sq3Fupu_Sq3LiteProgressHandler_X X, MK_PTR P)
	Query Progress Callbacks …
static enum Sq3AuthReturnE	libsq3lite::Sq3LiteSetAuthorizer (SQ3_LITE sq3lite, Sq3Fupu_Sq3LiteSetAuthorizer_xAuth xAuth, MK_PTR pUserData)
	Compile-Time Authorization Callbacks …
static MK_I64	libsq3lite::Sq3MemoryHighwater (MK_I32 resetFlag)
	Memory Allocator Statistics …
static MK_I64	libsq3lite::Sq3MemoryUsed (void)
	Memory Allocator Statistics …
static void	libsq3lite::Sq3Randomness (MK_I32 N, MK_PTR P)
	Pseudo-Random Number Generator …
static enum MkErrorE	libsq3lite::Sq3Threadsafe (void)
	Test To See If The Library Is Threadsafe …

Sq3Lite - Sq3Lite_Config_C_API - overload
#define	Sq3Randomness_1(N)
#define	Sq3Threadsafe_E(...)
#define	Sq3Threadsafe_C(...)

Detailed Description

Sq3Lite PACKAGE - configure the applicatione …

end Sq3Lite_Enum_C_API

Macro Definition Documentation

Sq3Fupu_Sq3LiteProgressHandler_X_args

#define Sq3Fupu_Sq3LiteProgressHandler_X_args   MK_PTR P

Definition at line 641 of file LibSq3Lite_sq3.h.

Sq3Fupu_Sq3LiteProgressHandler_X_ret

#define Sq3Fupu_Sq3LiteProgressHandler_X_ret   MK_I32

Definition at line 640 of file LibSq3Lite_sq3.h.

Sq3Fupu_Sq3LiteSetAuthorizer_xAuth_args

#define Sq3Fupu_Sq3LiteSetAuthorizer_xAuth_args   MK_PTR pUserData, MK_I32 auth_action_code, MK_STRN arg2, MK_STRN arg3, MK_STRN arg4, MK_STRN arg5

Definition at line 648 of file LibSq3Lite_sq3.h.

Sq3Fupu_Sq3LiteSetAuthorizer_xAuth_ret

#define Sq3Fupu_Sq3LiteSetAuthorizer_xAuth_ret   MK_I32

Definition at line 647 of file LibSq3Lite_sq3.h.

Sq3Randomness_1

#define Sq3Randomness_1

(

N

)

Value:

Sq3Randomness(N,NULL)

Definition at line 121 of file sqlite3_overload_sq3.h.

Sq3Threadsafe_C

#define Sq3Threadsafe_C

(

...

)

Value:

if (MkErrorCheckI(Sq3Threadsafe(__VA_ARGS__)))

Definition at line 123 of file sqlite3_overload_sq3.h.

Sq3Threadsafe_E

#define Sq3Threadsafe_E

(

...

)

Value:

MkErrorCheck(Sq3Threadsafe(__VA_ARGS__))

Definition at line 122 of file sqlite3_overload_sq3.h.

Typedef Documentation

Sq3Fupu_Sq3LiteProgressHandler_X

typedef Sq3Fupu_Sq3LiteProgressHandler_X_ret(* libsq3lite::Sq3Fupu_Sq3LiteProgressHandler_X) (Sq3Fupu_Sq3LiteProgressHandler_X_args)

Definition at line 642 of file LibSq3Lite_sq3.h.

Sq3Fupu_Sq3LiteSetAuthorizer_xAuth

typedef Sq3Fupu_Sq3LiteSetAuthorizer_xAuth_ret(* libsq3lite::Sq3Fupu_Sq3LiteSetAuthorizer_xAuth) (Sq3Fupu_Sq3LiteSetAuthorizer_xAuth_args)

Definition at line 649 of file LibSq3Lite_sq3.h.

Function Documentation

Sq3CompileOptionGet()

static MK_STRN libsq3lite::Sq3CompileOptionGet ( MK_I32 N )

inlinestatic

Run-Time Library Compilation Options Diagnostics …

The Sq3CompileOptionUsed() function returns 0 or 1 indicating whether the specified option was defined at compile time. The SQLITE_ prefix may be omitted from the option name passed to Sq3CompileOptionUsed().

The Sq3CompileOptionGet() function allows iterating over the list of options that were defined at compile time by returning the N-th compile time option string. If N is out of range, Sq3CompileOptionGet() returns a NULL pointer. The SQLITE_ prefix is omitted from any strings returned by Sq3CompileOptionGet().

Support for the diagnostic functions Sq3CompileOptionUsed() and Sq3CompileOptionGet() may be omitted by specifying the SQLITE_OMIT_COMPILEOPTION_DIAGS option at compile time.

See also: SQL functions sqlite_compileoption_used () and sqlite_compileoption_get () and the compile_options pragma.

Reference code from sqlite3:

#ifndef SQLITE_OMIT_COMPILEOPTION_DIAGS
SQLITE_API int sqlite3_compileoption_used(const char *zOptName);
SQLITE_API const char *sqlite3_compileoption_get(int N);
#else
# define sqlite3_compileoption_used(X) 0
# define sqlite3_compileoption_get(X)  ((void*)0)
#endif

Definition at line 663 of file LibSq3Lite_sq3.h.

                                                                                                                                    {

Here is the caller graph for this function:

Sq3CompileOptionUsed()

static MK_BOOL libsq3lite::Sq3CompileOptionUsed ( MK_STRN zOptName )

inlinestatic

Run-Time Library Compilation Options Diagnostics …

read more at 'Sq3CompileOptionGet'

Definition at line 669 of file LibSq3Lite_sq3.h.

Here is the caller graph for this function:

Sq3LiteProgressHandler()

static void libsq3lite::Sq3LiteProgressHandler ( SQ3_LITE sq3lite, MK_I32 N, Sq3Fupu_Sq3LiteProgressHandler_X X, MK_PTR P )

inlinestatic

Query Progress Callbacks …

The Sq3LiteProgressHandler(D,N,X,P) interface causes the callback function X to be invoked periodically during long running calls to Sq3StmtStep () and sqlite3_prepare () and similar for database connection D. An example use for this interface is to keep a GUI updated during a large query.

The parameter P is passed through as the only parameter to the callback function X. The parameter N is the approximate number of virtual machine instructions that are evaluated between successive invocations of the callback X. If N is less than one then the progress handler is disabled.

Only a single progress handler may be defined at one time per database connection; setting a new progress handler cancels the old one. Setting parameter X to NULL disables the progress handler. The progress handler is also disabled by setting N to a value less than 1.

If the progress callback returns non-zero, the operation is interrupted. This feature can be used to implement a "Cancel" button on a GUI progress dialog box.

The progress handler callback must not do anything that will modify the database connection that invoked the progress handler. Note that Sq3StmtPrepareV2 () and Sq3StmtStep () both modify their database connections for the meaning of "modify" in this paragraph.

The progress handler callback would originally only be invoked from the bytecode engine. It still might be invoked during sqlite3_prepare () and similar because those routines might force a reparse of the schema which involves running the bytecode engine. However, beginning with SQLite version 3.41.0, the progress handler callback might also be invoked directly from sqlite3_prepare () while analyzing and generating code for complex queries.

Reference code from sqlite3:

SQLITE_API void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);

Definition at line 674 of file LibSq3Lite_sq3.h.

                                        {

Sq3LiteSetAuthorizer()

static enum Sq3AuthReturnE libsq3lite::Sq3LiteSetAuthorizer ( SQ3_LITE sq3lite, Sq3Fupu_Sq3LiteSetAuthorizer_xAuth xAuth, MK_PTR pUserData )

inlinestatic

Compile-Time Authorization Callbacks …

This routine registers an 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 Sq3StmtPrepareV2 (), Sq3StmtPrepareV3 (), sqlite3_prepare16 (), sqlite3_prepare16_v2 (), and sqlite3_prepare16_v3 (). 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 SQ3_RESULT_OK to allow the action, SQ3_AUTHRETURN_IGNORE to disallow the specific action but allow the SQL statement to continue to be compiled, or SQ3_AUTHRETURN_DENY to cause the entire SQL statement to be rejected with an error. If the authorizer callback returns any value other than SQ3_AUTHRETURN_IGNORE, SQ3_RESULT_OK, or SQ3_AUTHRETURN_DENY then the Sq3StmtPrepareV2 () or equivalent call that triggered the authorizer will fail with an error message.

When the callback returns SQ3_RESULT_OK, that means the operation requested is ok. When the callback returns SQ3_AUTHRETURN_DENY, the Sq3StmtPrepareV2 () or equivalent call that triggered the authorizer will fail with an error message explaining that access is denied.

The first parameter to the authorizer callback is a copy of the third parameter to the Sq3LiteSetAuthorizer() interface. The second parameter to the callback is an integer action code that specifies the particular action to be authorized. The third through sixth parameters to the callback are either NULL pointers or zero-terminated strings that contain additional details about the action to be authorized. Applications must always be prepared to encounter a NULL pointer in any of the third through the sixth parameters of the authorization callback.

If the action code is SQ3_AUTHACTION_READ and the callback returns SQ3_AUTHRETURN_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 SQ3_RESULT_OK had been returned. The SQ3_AUTHRETURN_IGNORE return can be used to deny an untrusted user access to individual columns of a table. When a table is referenced by a SELECT but no column values are extracted from that table (for example in a query like "SELECT count(*) FROM tab") then the SQ3_AUTHACTION_READ authorizer callback is invoked once for that table with a column name that is an empty string. If the action code is SQ3_AUTHACTION_DELETE and the callback returns SQ3_AUTHRETURN_IGNORE then the DELETE operation proceeds but the truncate optimization is disabled and all rows are deleted individually.

An authorizer is used when preparing SQL statements from an untrusted source, to ensure that the SQL statements do not try to access data 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 prepared that disallows everything except SELECT statements.

Applications that need to process SQL from untrusted sources might also consider lowering resource limits using Sq3LiteLimit () 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 Sq3LiteSetAuthorizer overrides the previous call. Disable the authorizer by installing a NULL callback. The authorizer is disabled by default.

The authorizer callback must not do anything that will modify the database connection that invoked the authorizer callback. Note that Sq3StmtPrepareV2 () and Sq3StmtStep () both modify their database connections for the meaning of "modify" in this paragraph.

When Sq3StmtPrepareV2 () is used to prepare a statement, the statement might be re-prepared during Sq3StmtStep () due to a schema change. Hence, the application should ensure that the correct authorizer callback remains in place during the Sq3StmtStep ().

Note that the authorizer callback is invoked only during sqlite3_prepare () or its variants. Authorization is not performed during statement evaluation in Sq3StmtStep (), unless as stated in the previous paragraph, Sq3StmtStep() invokes Sq3StmtPrepareV2() to reprepare a statement after a schema change.

Reference code from sqlite3:

SQLITE_API int sqlite3_set_authorizer(
  sqlite3*,
  int (*xAuth)(void*,int,const char*,const char*,const char*,const char*),
  void *pUserData
);

Definition at line 680 of file LibSq3Lite_sq3.h.

                                                    {
    sqlite3_randomness(N, (MK_PTR)(P));

Sq3MemoryHighwater()

static MK_I64 libsq3lite::Sq3MemoryHighwater ( MK_I32 resetFlag )

inlinestatic

Memory Allocator Statistics …

SQLite provides these two interfaces for reporting on the status of the Sq3Malloc (), Sq3Free (), and Sq3Realloc () routines, which form the built-in memory allocation subsystem.

The Sq3MemoryUsed () routine returns the number of bytes of memory currently outstanding (malloced but not freed). The Sq3MemoryHighwater () routine returns the maximum value of Sq3MemoryUsed () since the high-water mark was last reset. The values returned by Sq3MemoryUsed () and Sq3MemoryHighwater () include any overhead added by SQLite in its implementation of Sq3Malloc (), but not overhead added by the any underlying system library routines that Sq3Malloc () may call.

The memory high-water mark is reset to the current value of Sq3MemoryUsed () if and only if the parameter to Sq3MemoryHighwater () is true. The value returned by Sq3MemoryHighwater (1) is the high-water mark prior to the reset.

Reference code from sqlite3:

SQLITE_API sqlite3_int64 sqlite3_memory_used(void);
SQLITE_API sqlite3_int64 sqlite3_memory_highwater(int resetFlag);

Definition at line 686 of file LibSq3Lite_sq3.h.

                                               {
    enum Sq3ErrorE errVal = (enum Sq3ErrorE)sqlite3_threadsafe();

Here is the caller graph for this function:

Sq3MemoryUsed()

static MK_I64 libsq3lite::Sq3MemoryUsed ( void )

inlinestatic

Memory Allocator Statistics …

read more at 'Sq3MemoryHighwater'

Definition at line 691 of file LibSq3Lite_sq3.h.

       :
    return MK_ERROR;
  }

Here is the caller graph for this function:

Sq3Randomness()

static void libsq3lite::Sq3Randomness ( MK_I32 N, MK_PTR P )

inlinestatic

Pseudo-Random Number Generator …

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 built-in random() and randomblob() SQL functions. This interface allows applications to access the same PRNG for other purposes.

A call to this routine stores N bytes of randomness into buffer P. The P parameter can be a NULL pointer.

If this routine has not been previously called or if the previous call had N less than one or a NULL pointer for P, then the PRNG is seeded using randomness obtained from the xRandomness method of the default sqlite3_vfs object. If the previous call to this routine had an N of 1 or more and a non-NULL P then the pseudo-randomness is generated internally and without recourse to the sqlite3_vfs xRandomness method.

Reference code from sqlite3:

SQLITE_API void sqlite3_randomness(int N, void *P);

Definition at line 696 of file LibSq3Lite_sq3.h.

Here is the caller graph for this function:

Sq3Threadsafe()

static enum MkErrorE libsq3lite::Sq3Threadsafe ( void )

inlinestatic

Test To See If The Library Is Threadsafe …

The Sq3Threadsafe() function returns zero if and only if SQLite was compiled with mutexing code omitted due to the SQLITE_THREADSAFE compile-time option being set to 0.

SQLite can be compiled with or without mutexes. When the SQLITE_THREADSAFE C preprocessor macro is 1 or 2, mutexes are enabled and SQLite is threadsafe. When the SQLITE_THREADSAFE macro is 0, the mutexes are omitted. Without the mutexes, it is not safe to use SQLite concurrently from more than one thread.

Enabling mutexes incurs a measurable performance penalty. So if speed is of utmost importance, it makes sense to disable the mutexes. But for maximum safety, mutexes should be enabled. The default behavior is for mutexes to be enabled.

This interface can be used by an application to make sure that the version of SQLite that it is linking against was compiled with the desired setting of the SQLITE_THREADSAFE macro.

This interface only reports on the compile-time mutex setting of the SQLITE_THREADSAFE flag. If SQLite is compiled with SQLITE_THREADSAFE=1 or =2 then mutexes are enabled by default but can be fully or partially disabled using a call to sqlite3_config () with the verbs SQ3_CONFIG_SINGLETHREAD, SQ3_CONFIG_MULTITHREAD, or SQ3_CONFIG_SERIALIZED. The return value of the Sq3Threadsafe() function shows only the compile-time setting of thread safety, not any run-time changes to that setting made by sqlite3_config(). In other words, the return value from Sq3Threadsafe() is unchanged by calls to sqlite3_config().

See the threading mode documentation for additional information.

Reference code from sqlite3:

SQLITE_API int sqlite3_threadsafe(void);

Definition at line 701 of file LibSq3Lite_sq3.h.

                                                    {
    enum Sq3ErrorE errVal = (enum Sq3ErrorE)sqlite3_complete(sql);
    Sq3ErrorE_Check_Package(errVal);
    return MK_OK;
  error:
    return MK_ERROR;
  }

Here is the caller graph for this function: