Small. Fast. Reliable.
Choose any three.

SQLite C Interface

Collation Needed Callbacks

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*)
);

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 called 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 any existing 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().

Invariants:

H16702 A successful call to sqlite3_collation_needed(D,P,F) or sqlite3_collation_needed16(D,P,F) causes the database connection D to invoke callback F with first parameter P whenever it needs a comparison function for a collating sequence that it does not know about.
H16704 Each successful call to sqlite3_collation_needed() or sqlite3_collation_needed16() overrides the callback registered on the same database connection by prior calls to either interface.
H16706 The name of the requested collating function passed in the 4th parameter to the callback is in UTF-8 if the callback was registered using sqlite3_collation_needed() and is in UTF-16 native byte order if the callback was registered using sqlite3_collation_needed16().

See also lists of Objects, Constants, and Functions.


This page last modified 2008/12/09 18:44:04 UTC