.Dd December 19, 2018
.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