Collation Needed Callbacks

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

R-31579-59686:[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. ]

R-06920-11647:[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. ] R-24874-01721:[If sqlite3_collation_needed16() is used, the names are passed as UTF-16 in machine native byte order. ] R-28346-31823:[A call to either function replaces the existing collation-needed callback. ]

R-40355-56314:[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 lists of Objects, Constants, and Functions.