SQLITE3_COLLATION_NEEDED(3)

SQLITE3_COLLATION_NEEDED(3) | Library Functions Manual | SQLITE3_COLLATION_NEEDED(3)

# NAME

`sqlite3_collation_needed`, `sqlite3_collation_needed16` —
Collation Needed Callbacks

# SYNOPSIS

int
`sqlite3_collation_needed`(sqlite3*, void*, void(*)(void*,sqlite3*,int eTextRep,const char*) );

int
`sqlite3_collation_needed16`(sqlite3*, void*, void(*)(void*,sqlite3*,int eTextRep,const void*) );

# 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.

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.

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.

The callback function should register the desired collation using sqlite3_create_collation(), sqlite3_create_collation16(), or sqlite3_create_collation_v2().

# SEE ALSO

sqlite3(3), sqlite3_create_collation(3), SQLITE_UTF8(3)

December 19, 2018 | NetBSD 9.0