1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
|
.Dd January 24, 2024
.Dt SQLITE3_URI_PARAMETER 3
.Os
.Sh NAME
.Nm sqlite3_uri_parameter ,
.Nm sqlite3_uri_boolean ,
.Nm sqlite3_uri_int64 ,
.Nm sqlite3_uri_key
.Nd obtain values for URI parameters
.Sh SYNOPSIS
.In sqlite3.h
.Ft const char *
.Fo sqlite3_uri_parameter
.Fa "sqlite3_filename z"
.Fa "const char *zParam"
.Fc
.Ft int
.Fo sqlite3_uri_boolean
.Fa "sqlite3_filename z"
.Fa "const char *zParam"
.Fa "int bDefault"
.Fc
.Ft sqlite3_int64
.Fo sqlite3_uri_int64
.Fa "sqlite3_filename"
.Fa "const char*"
.Fa "sqlite3_int64"
.Fc
.Ft const char *
.Fo sqlite3_uri_key
.Fa "sqlite3_filename z"
.Fa "int N"
.Fc
.Sh DESCRIPTION
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.
.Pp
The first parameter to these interfaces (hereafter referred to as F)
must be one of:
.Bl -bullet
.It
A database filename pointer created by the SQLite core and passed into
the xOpen() method of a VFS implementation, or
.It
A filename obtained from
.Fn sqlite3_db_filename ,
or
.It
A new filename constructed using
.Fn sqlite3_create_filename .
.El
.Pp
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.
.Pp
If F is a suitable filename (as described in the previous paragraph)
and if P is the name of the query parameter, then sqlite3_uri_parameter(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 sqlite3_uri_parameter(F,P)
returns a pointer to an empty string.
.Pp
The sqlite3_uri_boolean(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 sqlite3_uri_boolean(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 sqlite3_uri_boolean(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 sqlite3_uri_boolean(F,P,B) returns (B!=0).
.Pp
The sqlite3_uri_int64(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.
.Pp
The sqlite3_uri_key(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.
.Pp
If F is a NULL pointer, then sqlite3_uri_parameter(F,P) returns NULL
and sqlite3_uri_boolean(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.
.Pp
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.
.Pp
See the URI filename documentation for additional information.
.Sh IMPLEMENTATION NOTES
These declarations were extracted from the
interface documentation at line 3755.
.Bd -literal
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);
.Ed
.Sh SEE ALSO
.Xr sqlite3_create_filename 3 ,
.Xr sqlite3_db_filename 3
|
