Sq3LiteC_TOR_C_API

Sq3LiteC - various functions to create, initialize and destroy … More...

Collaboration diagram for Sq3LiteC_TOR_C_API:

Functions
static enum MkErrorE	Sq3LiteOpenV2 (MK_STRN filename, SQ3_LITE *ppDb, enum Sq3OpenEF flags, MK_STRN zVfs)
	Opening A New Database Connection …
static enum MkErrorE	Sq3LiteCloseV2 (SQ3_LITE sq3lite)
	Closing A Database Connection …

Sq3LiteC - Sq3LiteC_TOR_C_API - function
enum MkErrorE	Sq3LiteOpenV2P (MK_STRN filename, SQ3_LITE *ppDb, enum Sq3OpenEF flags, MK_STRN zVfs)
	Non-inline replacement for Sq3LiteOpenV2 …
enum MkErrorE	Sq3LitePrepareV2P (SQ3_LITE db, MkStringR zSql, SQ3_STMT *ppStmt)
	Non-inline replacement for Sq3LitePrepareV2 …
enum MkErrorE	Sq3LiteCloseV2P (SQ3_LITE sq3lite)
	Non-inline replacement for Sq3LiteCloseV2 …

Sq3LiteC - Sq3LiteC_TOR_C_API - overload
#define	Sq3LiteOpenV2_3(filename, ppDb, flags)
#define	Sq3LiteOpenV2_2(filename, ppDb)
#define	Sq3LiteOpenV2_E(...)
#define	Sq3LiteOpenV2_C(...)
#define	Sq3LitePrepareV2_E(...)
#define	Sq3LitePrepareV2_C(...)
#define	Sq3LitePrepareV2_e(...)
#define	Sq3LiteCloseV2_E(...)
#define	Sq3LiteCloseV2_C(...)

Detailed Description

Sq3LiteC - various functions to create, initialize and destroy …

Macro Definition Documentation

Sq3LiteCloseV2_C

#define Sq3LiteCloseV2_C

(

...

)

Value:

if (MkErrorCheckI(Sq3LiteCloseV2(__VA_ARGS__)))

Definition at line 510 of file sqlite3_overload_sq3.h.

Sq3LiteCloseV2_E

#define Sq3LiteCloseV2_E

(

...

)

Value:

MkErrorCheck(Sq3LiteCloseV2(__VA_ARGS__))

Definition at line 509 of file sqlite3_overload_sq3.h.

Sq3LiteOpenV2_2

#define Sq3LiteOpenV2_2	(		filename,
			ppDb )

Value:

Sq3LiteOpenV2(filename,ppDb,SQ3_OPEN_READWRITE|SQ3_OPEN_CREATE,NULL)

Definition at line 499 of file sqlite3_overload_sq3.h.

Sq3LiteOpenV2_3

#define Sq3LiteOpenV2_3	(		filename,
			ppDb,
			flags )

Value:

Sq3LiteOpenV2(filename,ppDb,flags,NULL)

Definition at line 498 of file sqlite3_overload_sq3.h.

Sq3LiteOpenV2_C

#define Sq3LiteOpenV2_C

(

...

)

Value:

if (MkErrorCheckI(Sq3LiteOpenV2(__VA_ARGS__)))

Definition at line 501 of file sqlite3_overload_sq3.h.

Sq3LiteOpenV2_E

#define Sq3LiteOpenV2_E

(

...

)

Value:

MkErrorCheck(Sq3LiteOpenV2(__VA_ARGS__))

Definition at line 500 of file sqlite3_overload_sq3.h.

Sq3LitePrepareV2_C

#define Sq3LitePrepareV2_C

(

...

)

Value:

if (MkErrorCheckI(Sq3LitePrepareV2(__VA_ARGS__)))

Definition at line 505 of file sqlite3_overload_sq3.h.

Sq3LitePrepareV2_E

#define Sq3LitePrepareV2_E

(

...

)

Value:

MkErrorCheck(Sq3LitePrepareV2(__VA_ARGS__))

Definition at line 504 of file sqlite3_overload_sq3.h.

Sq3LitePrepareV2_e

#define Sq3LitePrepareV2_e

(

...

)

Value:

MK_EMBEDDED(SQ3_STMT,Sq3LitePrepareV2,__VA_ARGS__)

Definition at line 506 of file sqlite3_overload_sq3.h.

Function Documentation

Sq3LiteCloseV2()

static enum MkErrorE Sq3LiteCloseV2 ( SQ3_LITE sq3lite )

inlinestatic

Closing A Database Connection …

The sqlite3_close() and Sq3LiteCloseV2() routines are destructors for the Sq3LiteC object. Calls to sqlite3_close() and Sq3LiteCloseV2() return SQ3_RESULT_OK if the Sq3LiteC object is successfully destroyed and all associated resources are deallocated.

Ideally, applications should finalize all prepared statements, close all BLOB handles, and finish all sqlite3_backup objects associated with the Sq3LiteC object prior to attempting to close the object. If the database connection is associated with unfinalized prepared statements, BLOB handlers, and/or unfinished sqlite3_backup objects then sqlite3_close() will leave the database connection open and return SQ3_RESULT_BUSY. If Sq3LiteCloseV2() is called with unfinalized prepared statements, unclosed BLOB handlers, and/or unfinished Sq3Backup's, it returns SQ3_RESULT_OK regardless, but instead of deallocating the database connection immediately, it marks the database connection as an unusable "zombie" and makes arrangements to automatically deallocate the database connection after all prepared statements are finalized, all BLOB handles are closed, and all backups have finished. The Sq3LiteCloseV2() interface is intended for use with host languages that are garbage collected, and where the order in which destructors are called is arbitrary.

If an Sq3LiteC object is destroyed while a transaction is open, the transaction is automatically rolled back.

The C parameter to sqlite3_close (C) and Sq3LiteCloseV2 (C) must be either a NULL pointer or an Sq3LiteC object pointer obtained from sqlite3_open (), sqlite3_open16 (), or Sq3LiteOpenV2 (), and not previously closed. Calling sqlite3_close() or Sq3LiteCloseV2() with a NULL pointer argument is a harmless no-op.

Reference code from sqlite3:

SQLITE_API int sqlite3_close(sqlite3*);
SQLITE_API int sqlite3_close_v2(sqlite3*);

Definition at line 552 of file Sq3LiteC_sq3.h.

                                                            {
    enum Sq3ErrorE errVal = (enum Sq3ErrorE)sqlite3_close_v2(sq3lite->nat);
    Sq3ErrorE_Check(sq3lite, errVal);
    return MK_OK;
  error:
    return MK_ERROR;
  }

Here is the caller graph for this function:

Sq3LiteCloseV2P()

enum MkErrorE Sq3LiteCloseV2P

(

SQ3_LITE

sq3lite

)

Non-inline replacement for Sq3LiteCloseV2 …

Sq3LiteOpenV2()

static enum MkErrorE Sq3LiteOpenV2 ( MK_STRN filename, SQ3_LITE * ppDb, enum Sq3OpenEF flags, MK_STRN zVfs )

inlinestatic

Opening A New Database Connection …

These routines open an SQLite database file as specified by the filename argument. The filename argument is interpreted as UTF-8 for sqlite3_open() and Sq3LiteOpenV2() and as UTF-16 in the native byte order for sqlite3_open16(). A database connection handle is usually returned in *ppDb, even if an error occurs. The only exception is that if SQLite is unable to allocate memory to hold the Sq3LiteC object, a NULL will be written into *ppDb instead of a pointer to the Sq3LiteC object. If the database is opened (and/or created) successfully, then SQ3_RESULT_OK is returned. Otherwise an error code is returned. The Sq3LiteErrMsg () or sqlite3_errmsg16 () routines can be used to obtain an English language description of the error following a failure of any of the sqlite3_open() routines.

The default encoding will be UTF-8 for databases created using sqlite3_open() or Sq3LiteOpenV2(). The default encoding for databases created using sqlite3_open16() will be UTF-16 in the native byte order.

Whether or not an error occurs when it is opened, resources associated with the database connection handle should be released by passing it to sqlite3_close () when it is no longer required.

The Sq3LiteOpenV2() interface works like sqlite3_open() except that it accepts two additional parameters for additional control over the new database connection. The flags parameter to Sq3LiteOpenV2() must include, at a minimum, one of the following three flag combinations:

SQ3_OPEN_READONLY

The database is opened in read-only mode. If the database does not already exist, an error is returned.

SQ3_OPEN_READWRITE

The database is opened for reading and writing if possible, or reading only if the file is write protected by the operating system. In either case the database must already exist, otherwise an error is returned. For historical reasons, if opening in read-write mode fails due to OS-level permissions, an attempt is made to open it in read-only mode. Sq3LiteDbReadonly () can be used to determine whether the database is actually read-write.

SQ3_OPEN_READWRITE | SQ3_OPEN_CREATE

The database is opened for reading and writing, and is created if it does not already exist. This is the behavior that is always used for sqlite3_open() and sqlite3_open16().

In addition to the required flags, the following optional flags are also supported:

SQ3_OPEN_URI

The filename can be interpreted as a URI if this flag is set.

SQ3_OPEN_MEMORY

The database will be opened as an in-memory database. The database is named by the "filename" argument for the purposes of cache-sharing, if shared cache mode is enabled, but the "filename" is otherwise ignored.

SQ3_OPEN_NOMUTEX

The new database connection will use the "multi-thread" threading mode. This means that separate threads are allowed to use SQLite at the same time, as long as each thread is using a different database connection.

SQ3_OPEN_FULLMUTEX

The new database connection will use the "serialized" threading mode. This means the multiple threads can safely attempt to use the same database connection at the same time. (Mutexes will block any actual concurrency, but in this mode there is no harm in trying.)

SQ3_OPEN_SHAREDCACHE

The database is opened shared cache enabled, overriding the default shared cache setting provided by sqlite3_enable_shared_cache (). The use of shared cache mode is discouraged and hence shared cache capabilities may be omitted from many builds of SQLite. In such cases, this option is a no-op.

SQ3_OPEN_PRIVATECACHE

The database is opened shared cache disabled, overriding the default shared cache setting provided by sqlite3_enable_shared_cache ().

SQ3_OPEN_EXRESCODE

The database connection comes up in "extended result code mode". In other words, the database behaves has if Sq3LiteExtendedResultCodes (db,1) where called on the database connection as soon as the connection is created. In addition to setting the extended result code mode, this flag also causes Sq3LiteOpenV2 () to return an extended result code.

SQ3_OPEN_NOFOLLOW

The database filename is not allowed to contain a symbolic link

If the 3rd parameter to Sq3LiteOpenV2() is not one of the required combinations shown above optionally combined with other SQ3_OPEN_* bits then the behavior is undefined. Historic versions of SQLite have silently ignored surplus bits in the flags parameter to Sq3LiteOpenV2(), however that behavior might not be carried through into future versions of SQLite and so applications should not rely upon it. Note in particular that the SQ3_OPEN_EXCLUSIVE flag is a no-op for Sq3LiteOpenV2(). The SQ3_OPEN_EXCLUSIVE does not cause the open to fail if the database already exists. The SQ3_OPEN_EXCLUSIVE flag is intended for use by the VFS interface only, and not by Sq3LiteOpenV2().

The fourth parameter to Sq3LiteOpenV2() is the name of the sqlite3_vfs object that defines the operating system interface that the new database connection should use. If the fourth parameter is a NULL pointer then the default sqlite3_vfs object is used.

If the filename is ":memory:", then a private, temporary in-memory database is created for the connection. This in-memory database will vanish when the database connection is closed. Future versions of SQLite might make use of additional special filenames that begin with the ":" character. It is recommended that when a database filename actually does begin with a ":" character you should prefix the filename with a pathname such as "./" to avoid ambiguity.

If the filename is an empty string, then a private, temporary on-disk database will be created. This private database will be automatically deleted as soon as the database connection is closed.

URI Filenames

If URI filename interpretation is enabled, and the filename argument begins with "file:", then the filename is interpreted as a URI. URI filename interpretation is enabled if the SQ3_OPEN_URI flag is set in the third argument to Sq3LiteOpenV2(), or if it has been enabled globally using the SQ3_CONFIG_URI option with the sqlite3_config () method or by the SQLITE_USE_URI compile-time option. URI filename interpretation is turned off by default, but future releases of SQLite might enable URI filename interpretation by default. See "<a href="https://www.sqlite.org/uri.html">URI filenames</a>" for additional information.

URI filenames are parsed according to RFC 3986. If the URI contains an authority, then it must be either an empty string or the string "localhost". If the authority is not an empty string or "localhost", an error is returned to the caller. The fragment component of a URI, if present, is ignored.

SQLite uses the path component of the URI as the name of the disk file which contains the database. If the path begins with a '/' character, then it is interpreted as an absolute path. If the path does not begin with a '/' (meaning that the authority section is omitted from the URI) then the path is interpreted as a relative path. On windows, the first component of an absolute path is a drive specification (e.g. "C:").

The query component of a URI may contain parameters that are interpreted either by SQLite itself, or by a custom VFS implementation. SQLite and its built-in VFSes interpret the following query parameters:

• vfs: The "vfs" parameter may be used to specify the name of a VFS object that provides the operating system interface that should be used to access the database file on disk. If this option is set to an empty string the default VFS object is used. Specifying an unknown VFS is an error. If Sq3LiteOpenV2() is used and the vfs option is present, then the VFS specified by the option takes precedence over the value passed as the fourth parameter to Sq3LiteOpenV2().

• mode: The mode parameter may be set to either "ro", "rw", "rwc", or "memory". Attempting to set it to any other value is an error. If "ro" is specified, then the database is opened for read-only access, just as if the SQ3_OPEN_READONLY flag had been set in the third argument to Sq3LiteOpenV2(). If the mode option is set to "rw", then the database is opened for read-write (but not create) access, as if SQ3_OPEN_READWRITE (but not SQ3_OPEN_CREATE) had been set. Value "rwc" is equivalent to setting both SQ3_OPEN_READWRITE and SQ3_OPEN_CREATE. If the mode option is set to "memory" then a pure in-memory database that never reads or writes from disk is used. It is an error to specify a value for the mode parameter that is less restrictive than that specified by the flags passed in the third parameter to Sq3LiteOpenV2().

• cache: The cache parameter may be set to either "shared" or "private". Setting it to "shared" is equivalent to setting the SQ3_OPEN_SHAREDCACHE bit in the flags argument passed to Sq3LiteOpenV2(). Setting the cache parameter to "private" is equivalent to setting the SQ3_OPEN_PRIVATECACHE bit. If Sq3LiteOpenV2() is used and the "cache" parameter is present in a URI filename, its value overrides any behavior requested by setting SQ3_OPEN_PRIVATECACHE or SQ3_OPEN_SHAREDCACHE flag.

• psow: The psow parameter indicates whether or not the powersafe overwrite property does or does not apply to the storage media on which the database file resides.

• nolock: The nolock parameter is a boolean query parameter which if set disables file locking in rollback journal modes. This is useful for accessing a database on a filesystem that does not support locking. Caution: Database corruption might result if two or more processes write to the same database and any one of those processes uses nolock=1.

• immutable: The immutable parameter is a boolean query parameter that indicates that the database file is stored on read-only media. When immutable is set, SQLite assumes that the database file cannot be changed, even by a process with higher privilege, and so the database is opened read-only and all locking and change detection is disabled. Caution: Setting the immutable property on a database file that does in fact change can result in incorrect query results and/or SQ3_RESULT_CORRUPT errors. See also: SQ3_IOCAP_IMMUTABLE.

Specifying an unknown parameter in the query component of a URI is not an error. Future versions of SQLite might understand additional query parameters. See "<a href="https://www.sqlite.org/uri.html#coreqp">query parameters with special meaning to SQLite</a>" for additional information.

URI filename examples

URI filenames	Results
file:data.db	Open the file "data.db" in the current directory.
file:/home/fred/data.db file:///home/fred/data.db file://localhost/home/fred/data.db	Open the database file "/home/fred/data.db".
file://darkstar/home/fred/data.db	An error. "darkstar" is not a recognized authority.
file:///C:/Documents%20and%20Settings/fred/Desktop/data.db	Windows only: Open the file "data.db" on fred's desktop on drive C:. Note that the %20 escaping in this example is not strictly necessary - space characters can be used literally in URI filenames.
file:data.db?mode=ro&cache=private	Open file "data.db" in the current directory for read-only access. Regardless of whether or not shared-cache mode is enabled by default, use a private cache.
file:/home/fred/data.db?vfs=unix-dotfile	Open file "/home/fred/data.db". Use the special VFS "unix-dotfile" that uses dot-files in place of posix advisory locking.
file:data.db?mode=readonly	An error. "readonly" is not a valid option for the "mode" parameter. Use "ro" instead: "file:data.db?mode=ro".

URI hexadecimal escape sequences (HH) are supported within the path and query components of a URI. A hexadecimal escape sequence consists of a percent sign - "%" - followed by exactly two hexadecimal digits specifying an octet value. Before the path or query components of a URI filename are interpreted, they are encoded using UTF-8 and all hexadecimal escape sequences replaced by a single byte containing the corresponding octet. If this process generates an invalid UTF-8 encoding, the results are undefined.

Note to Windows users: The encoding used for the filename argument of sqlite3_open() and Sq3LiteOpenV2() must be UTF-8, not whatever codepage is currently defined. Filenames containing international characters must be converted to UTF-8 prior to passing them into sqlite3_open() or Sq3LiteOpenV2().

Note to Windows Runtime users: The temporary directory must be set prior to calling sqlite3_open() or Sq3LiteOpenV2(). Otherwise, various features that require the use of temporary files may fail.

See also: sqlite3_temp_directory

Reference code from sqlite3:

SQLITE_API int sqlite3_open(
  const char *filename,   // Database filename (UTF-8) 
  sqlite3 **ppDb          // OUT: SQLite db handle 
);
SQLITE_API int sqlite3_open16(
  const void *filename,   // Database filename (UTF-16) 
  sqlite3 **ppDb          // OUT: SQLite db handle 
);
SQLITE_API int sqlite3_open_v2(
  const char *filename,   // Database filename (UTF-8) 
  sqlite3 **ppDb,         // OUT: SQLite db handle 
  int flags,              // Flags 
  const char *zVfs        // Name of VFS module to use 
);

Definition at line 537 of file Sq3LiteC_sq3.h.

                                                                                                               {
    *ppDb = NULL;
    sqlite3* ppDb_val = NULL;
    if (MK_NULL_STR_CHECK_1(zVfs)) zVfs = NULL;
    enum Sq3ErrorE errVal = (enum Sq3ErrorE)sqlite3_open_v2(filename, &ppDb_val, flags, zVfs);
    *ppDb = Sq3LiteC_ObjCreate(ppDb_val);
    Sq3ErrorE_Check_Static(Sq3LiteC_TT,errVal);
    return MK_OK;
  error:
    return MK_ERROR;
  }

Here is the caller graph for this function:

Sq3LiteOpenV2P()

enum MkErrorE Sq3LiteOpenV2P	(	MK_STRN	filename,
		SQ3_LITE *	ppDb,
		enum Sq3OpenEF	flags,
		MK_STRN	zVfs )

Non-inline replacement for Sq3LiteOpenV2 …

Sq3LitePrepareV2P()

enum MkErrorE Sq3LitePrepareV2P	(	SQ3_LITE	db,
		MkStringR	zSql,
		SQ3_STMT *	ppStmt )

Non-inline replacement for Sq3LitePrepareV2 …