48 lines
1.6 KiB
Groff
48 lines
1.6 KiB
Groff
.Dd March 11, 2017
|
|
.Dt SQLITE3_COLLATION_NEEDED 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm sqlite3_collation_needed ,
|
|
.Nm sqlite3_collation_needed16
|
|
.Nd Collation Needed Callbacks
|
|
.Sh SYNOPSIS
|
|
.Ft int
|
|
.Fo sqlite3_collation_needed
|
|
.Fa "sqlite3*"
|
|
.Fa "void*"
|
|
.Fa "void(*)(void*,sqlite3*,int eTextRep,const char*) "
|
|
.Fc
|
|
.Ft int
|
|
.Fo sqlite3_collation_needed16
|
|
.Fa "sqlite3*"
|
|
.Fa "void*"
|
|
.Fa "void(*)(void*,sqlite3*,int eTextRep,const void*) "
|
|
.Fc
|
|
.Sh DESCRIPTION
|
|
To avoid having to register all collation sequences before a database
|
|
can be used, a single callback function may be registered with the
|
|
database connection to be invoked whenever an undefined
|
|
collation sequence is required.
|
|
.Pp
|
|
If the function is registered using the sqlite3_collation_needed()
|
|
API, then it is passed the names of undefined collation sequences as
|
|
strings encoded in UTF-8.
|
|
If sqlite3_collation_needed16() is used, the names are passed as UTF-16
|
|
in machine native byte order.
|
|
A call to either function replaces the existing collation-needed callback.
|
|
.Pp
|
|
When the callback is invoked, the first argument passed is a copy of
|
|
the second argument to sqlite3_collation_needed() or sqlite3_collation_needed16().
|
|
The second argument is the database connection.
|
|
The third argument is one of SQLITE_UTF8, SQLITE_UTF16BE,
|
|
or SQLITE_UTF16LE, indicating the most desirable form
|
|
of the collation sequence function required.
|
|
The fourth parameter is the name of the required collation sequence.
|
|
.Pp
|
|
The callback function should register the desired collation using sqlite3_create_collation(),
|
|
sqlite3_create_collation16(), or sqlite3_create_collation_v2().
|
|
.Sh SEE ALSO
|
|
.Xr sqlite3 3 ,
|
|
.Xr sqlite3_create_collation 3 ,
|
|
.Xr SQLITE_UTF8 3
|