SQLITE3_COLLATION_NEEDED(3)

NAME
sqlite3_collation_needed, sqlite3_collation_needed16 - Collation Needed Callbacks

SYNOPSIS
#include <sqlite3.h>
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().

IMPLEMENTATION NOTES
These declarations were extracted from the interface documentation at line 6141.

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

SEE ALSO
sqlite3(3), sqlite3_create_collation(3), SQLITE_UTF8(3)