Sq3Lite_Vfs_C_API

Sq3Lite PACKAGE - work with the virtual-file-system … More...

Collaboration diagram for Sq3Lite_Vfs_C_API:

Functions
static SQ3_FILENAME	libsq3lite::Sq3CreateFilename (MK_STRN zDatabase, MK_STRN zJournal, MK_STRN zWal, MK_I32 azParam_num, MK_STRN *azParam)
	Create and Destroy VFS Filenames …
static MK_STRN	libsq3lite::Sq3FilenameDatabase (SQ3_FILENAME F)
	Translate filenames …
static MK_STRN	libsq3lite::Sq3FilenameJournal (SQ3_FILENAME F)
	Translate filenames …
static MK_STRN	libsq3lite::Sq3FilenameWal (SQ3_FILENAME F)
	Translate filenames …
static void	libsq3lite::Sq3FreeFilename (SQ3_FILENAME arg0)
	Create and Destroy VFS Filenames …
static enum MkErrorE	libsq3lite::Sq3UriBoolean (SQ3_FILENAME z, MK_STRN zParam, MK_I32 bDefault)
	Obtain Values For URI Parameters …
static MK_I64	libsq3lite::Sq3UriInt64 (SQ3_FILENAME arg0, MK_STRN arg1, MK_I64 arg2)
	Obtain Values For URI Parameters …
static MK_STRN	libsq3lite::Sq3UriKey (SQ3_FILENAME z, MK_I32 N)
	Obtain Values For URI Parameters …
static MK_STRN	libsq3lite::Sq3UriParameter (SQ3_FILENAME z, MK_STRN zParam)
	Obtain Values For URI Parameters …

Sq3Lite - Sq3Lite_Vfs_C_API - overload
#define	Sq3CreateFilename_3(zDatabase, zJournal, zWal)
#define	Sq3UriBoolean_E(...)
#define	Sq3UriBoolean_C(...)

Detailed Description

Sq3Lite PACKAGE - work with the virtual-file-system …

Macro Definition Documentation

Sq3CreateFilename_3

#define Sq3CreateFilename_3	(		zDatabase,
			zJournal,
			zWal )

Value:

Sq3CreateFilename(zDatabase,zJournal,zWal,NULL)

Definition at line 316 of file sqlite3_overload_sq3.h.

Sq3UriBoolean_C

#define Sq3UriBoolean_C

(

...

)

Value:

if (MkErrorCheckI(Sq3UriBoolean(__VA_ARGS__)))

Definition at line 318 of file sqlite3_overload_sq3.h.

Sq3UriBoolean_E

#define Sq3UriBoolean_E

(

...

)

Value:

MkErrorCheck(Sq3UriBoolean(__VA_ARGS__))

Definition at line 317 of file sqlite3_overload_sq3.h.

Function Documentation

Sq3CreateFilename()

static SQ3_FILENAME libsq3lite::Sq3CreateFilename ( MK_STRN zDatabase, MK_STRN zJournal, MK_STRN zWal, MK_I32 azParam_num, MK_STRN * azParam )

inlinestatic

Create and Destroy VFS Filenames …

These interfaces are provided for use by VFS shim implementations and are not useful outside of that context.

The Sq3CreateFilename(D,J,W,N,P) allocates memory to hold a version of database filename D with corresponding journal file J and WAL file W and with N URI parameters key/values pairs in the array P. The result from Sq3CreateFilename(D,J,W,N,P) is a pointer to a database filename that is safe to pass to routines like:

• Sq3UriParameter (),
• Sq3UriBoolean (),
• Sq3UriInt64 (),
• Sq3UriKey (),
• Sq3FilenameDatabase (),
• Sq3FilenameJournal (), or
• Sq3FilenameWal ().

If a memory allocation error occurs, Sq3CreateFilename() might return a NULL pointer. The memory obtained from Sq3CreateFilename(X) must be released by a corresponding call to Sq3FreeFilename(Y).

The P parameter in Sq3CreateFilename(D,J,W,N,P) should be an array of 2*N pointers to strings. Each pair of pointers in this array corresponds to a key and value for a query parameter. The P parameter may be a NULL pointer if N is zero. None of the 2*N pointers in the P array may be NULL pointers and key pointers should not be empty strings. None of the D, J, or W parameters to Sq3CreateFilename(D,J,W,N,P) may be NULL pointers, though they can be empty strings.

The Sq3FreeFilename(Y) routine releases a memory allocation previously obtained from Sq3CreateFilename(). Invoking Sq3FreeFilename(Y) where Y is a NULL pointer is a harmless no-op.

If the Y parameter to Sq3FreeFilename(Y) is anything other than a NULL pointer or a pointer previously acquired from Sq3CreateFilename(), then bad things such as heap corruption or segfaults may occur. The value Y should not be used again after Sq3FreeFilename(Y) has been called. This means that if the sqlite3_vfs.xOpen() method of a VFS has been called using Y, then the corresponding sqlite3_module.xClose() method should also be invoked prior to calling Sq3FreeFilename(Y).

Reference code from sqlite3:

SQLITE_API sqlite3_filename sqlite3_create_filename(
  const char *zDatabase,
  const char *zJournal,
  const char *zWal,
  int nParam,
  const char **azParam
);
SQLITE_API void sqlite3_free_filename(sqlite3_filename);

Definition at line 927 of file LibSq3Lite_sq3.h.

Here is the caller graph for this function:

Sq3FilenameDatabase()

static MK_STRN libsq3lite::Sq3FilenameDatabase ( SQ3_FILENAME F )

inlinestatic

Translate filenames …

These routines are available to custom VFS implementations for translating filenames between the main database file, the journal file, and the WAL file.

If F is the name of an sqlite database file, journal file, or WAL file passed by the SQLite core into the VFS, then Sq3FilenameDatabase(F) returns the name of the corresponding database file.

If F is the name of an sqlite database file, journal file, or WAL file passed by the SQLite core into the VFS, or if F is a database filename obtained from Sq3LiteDbFilename (), then Sq3FilenameJournal(F) returns the name of the corresponding rollback journal file.

If F is the name of an sqlite database file, journal file, or WAL file that was passed by the SQLite core into the VFS, or if F is a database filename obtained from Sq3LiteDbFilename (), then Sq3FilenameWal(F) returns the name of the corresponding WAL file.

In all of the above, if F is not the name of a database, journal or WAL filename passed into the VFS from the SQLite core and F is not the return value from Sq3LiteDbFilename (), then the result is undefined and is likely a memory access violation.

Reference code from sqlite3:

SQLITE_API const char *sqlite3_filename_database(sqlite3_filename);
SQLITE_API const char *sqlite3_filename_journal(sqlite3_filename);
SQLITE_API const char *sqlite3_filename_wal(sqlite3_filename);

Definition at line 933 of file LibSq3Lite_sq3.h.

Here is the caller graph for this function:

Sq3FilenameJournal()

static MK_STRN libsq3lite::Sq3FilenameJournal ( SQ3_FILENAME F )

inlinestatic

Translate filenames …

read more at 'Sq3FilenameDatabase'

Definition at line 939 of file LibSq3Lite_sq3.h.

                                                                                          {

Here is the caller graph for this function:

Sq3FilenameWal()

static MK_STRN libsq3lite::Sq3FilenameWal ( SQ3_FILENAME F )

inlinestatic

Translate filenames …

read more at 'Sq3FilenameDatabase'

Definition at line 945 of file LibSq3Lite_sq3.h.

       :
    return MK_ERROR;
  }

Here is the caller graph for this function:

Sq3FreeFilename()

static void libsq3lite::Sq3FreeFilename ( SQ3_FILENAME arg0 )

inlinestatic

Create and Destroy VFS Filenames …

read more at 'Sq3CreateFilename'

Definition at line 951 of file LibSq3Lite_sq3.h.

                                                                              {
    return sqlite3_uri_int64(arg0, arg1, arg2);
  }

Here is the caller graph for this function:

Sq3UriBoolean()

static enum MkErrorE libsq3lite::Sq3UriBoolean ( SQ3_FILENAME z, MK_STRN zParam, MK_I32 bDefault )

inlinestatic

Obtain Values For URI Parameters …

These are utility routines, useful to custom VFS implementations, that check if a database file was a URI that contained a specific query parameter, and if so obtains the value of that query parameter.

The first parameter to these interfaces (hereafter referred to as F) must be one of:

• A database filename pointer created by the SQLite core and passed into the xOpen() method of a VFS implementation, or
• A filename obtained from Sq3LiteDbFilename (), or
• A new filename constructed using Sq3CreateFilename ().

If the F parameter is not one of the above, then the behavior is undefined and probably undesirable. Older versions of SQLite were more tolerant of invalid F parameters than newer versions.

If F is a suitable filename (as described in the previous paragraph) and if P is the name of the query parameter, then Sq3UriParameter(F,P) returns the value of the P parameter if it exists or a NULL pointer if P does not appear as a query parameter on F. If P is a query parameter of F and it has no explicit value, then Sq3UriParameter(F,P) returns a pointer to an empty string.

The Sq3UriBoolean(F,P,B) routine assumes that P is a boolean parameter and returns true (1) or false (0) according to the value of P. The Sq3UriBoolean(F,P,B) routine returns true (1) if the value of query parameter P is one of "yes", "true", or "on" in any case or if the value begins with a non-zero number. The Sq3UriBoolean(F,P,B) routines returns false (0) if the value of query parameter P is one of "no", "false", or "off" in any case or if the value begins with a numeric zero. If P is not a query parameter on F or if the value of P does not match any of the above, then Sq3UriBoolean(F,P,B) returns (B!=0).

The Sq3UriInt64(F,P,D) routine converts the value of P into a 64-bit signed integer and returns that integer, or D if P does not exist. If the value of P is something other than an integer, then zero is returned.

The Sq3UriKey(F,N) returns a pointer to the name (not the value) of the N-th query parameter for filename F, or a NULL pointer if N is less than zero or greater than the number of query parameters minus 1. The N value is zero-based so N should be 0 to obtain the name of the first query parameter, 1 for the second parameter, and so forth.

If F is a NULL pointer, then Sq3UriParameter(F,P) returns NULL and Sq3UriBoolean(F,P,B) returns B. If F is not a NULL pointer and is not a database file pathname pointer that the SQLite core passed into the xOpen VFS method, then the behavior of this routine is undefined and probably undesirable.

Beginning with SQLite version 3.31.0 (dateof:3.31.0) the input F parameter can also be the name of a rollback journal file or WAL file in addition to the main database file. Prior to version 3.31.0, these routines would only work if F was the name of the main database file. When the F parameter is the name of the rollback journal or WAL file, it has access to all the same query parameters as were found on the main database file.

See the URI filename documentation for additional information.

Reference code from sqlite3:

SQLITE_API const char *sqlite3_uri_parameter(sqlite3_filename z, const char *zParam);
SQLITE_API int sqlite3_uri_boolean(sqlite3_filename z, const char *zParam, int bDefault);
SQLITE_API sqlite3_int64 sqlite3_uri_int64(sqlite3_filename, const char*, sqlite3_int64);
SQLITE_API const char *sqlite3_uri_key(sqlite3_filename z, int N);

Definition at line 956 of file LibSq3Lite_sq3.h.

                                                         {
    MK_STRN __retVal__L = sqlite3_uri_key(z, N);
    return __retVal__L;
  }
 
  mk_inline MK_STRN Sq3UriParameter (SQ3_FILENAME z, MK_STRN zParam) {

Here is the caller graph for this function:

Sq3UriInt64()

static MK_I64 libsq3lite::Sq3UriInt64 ( SQ3_FILENAME arg0, MK_STRN arg1, MK_I64 arg2 )

inlinestatic

Obtain Values For URI Parameters …

read more at 'Sq3UriBoolean'

Definition at line 965 of file LibSq3Lite_sq3.h.

Here is the caller graph for this function:

Sq3UriKey()

static MK_STRN libsq3lite::Sq3UriKey ( SQ3_FILENAME z, MK_I32 N )

inlinestatic

Obtain Values For URI Parameters …

read more at 'Sq3UriBoolean'

Definition at line 970 of file LibSq3Lite_sq3.h.

Here is the caller graph for this function:

Sq3UriParameter()

static MK_STRN libsq3lite::Sq3UriParameter ( SQ3_FILENAME z, MK_STRN zParam )

inlinestatic

Obtain Values For URI Parameters …

read more at 'Sq3UriBoolean'

Definition at line 976 of file LibSq3Lite_sq3.h.

                                      {    \
    OT_ERROR_SQ3_2_MQ(hdl);                \
    OT_ERROR_META_2_LNG(hdl);                 \

Here is the caller graph for this function: