Using SQLite

Name

sqlite3_collation_needed() — Register a collation loader

Definition

int sqlite3_collation_needed(   sqlite3* db, void* udp, col_callback   );
int sqlite3_collation_needed16( sqlite3* db, void* udp, col_callback16 );

void col_callback(   void* udp, sqlite3* db, int text_rep, const char* name );
void col_callback16( void* udp, sqlite3* db, int text_rep, const void* name );

db

A database connection.

udp

An application-defined user-data pointer. This value is made available to the collation loader callback.

col_callback, col_callback16

Function pointer to an application-defined collation loader function.

text_rep

The desired text representation for the requested collation. This value can be one of SQLITE_UTF8, SQLITE_UTF16BE, or SQLITE_UTF16LE.

name

The collation name in UTF-8 or UTF-16 (native order).

Returns (sqlite3_collation_needed[16]())

An SQLite result code.

Description

These functions register a collation loader callback function. Any time SQLite is processing an SQL statement that requires an unknown collation, the collation loader callback is called. This provides the application with an opportunity to register the required collation. If the callback is unable to register the requested collation, it should simply return.

Although the callback is given a desired text representation for the requested collation, the callback is under no obligation to provide a collation that uses that specific representation. As long as a collation with the proper name is provided, SQLite will perform ...