1.Dd March 11, 2017 2.Dt SQLITE3_COLLATION_NEEDED 3 3.Os 4.Sh NAME 5.Nm sqlite3_collation_needed , 6.Nm sqlite3_collation_needed16 7.Nd Collation Needed Callbacks 8.Sh SYNOPSIS 9.Ft int 10.Fo sqlite3_collation_needed 11.Fa "sqlite3*" 12.Fa "void*" 13.Fa "void(*)(void*,sqlite3*,int eTextRep,const char*) " 14.Fc 15.Ft int 16.Fo sqlite3_collation_needed16 17.Fa "sqlite3*" 18.Fa "void*" 19.Fa "void(*)(void*,sqlite3*,int eTextRep,const void*) " 20.Fc 21.Sh DESCRIPTION 22To avoid having to register all collation sequences before a database 23can be used, a single callback function may be registered with the 24database connection to be invoked whenever an undefined 25collation sequence is required. 26.Pp 27If the function is registered using the sqlite3_collation_needed() 28API, then it is passed the names of undefined collation sequences as 29strings encoded in UTF-8. 30If sqlite3_collation_needed16() is used, the names are passed as UTF-16 31in machine native byte order. 32A call to either function replaces the existing collation-needed callback. 33.Pp 34When the callback is invoked, the first argument passed is a copy of 35the second argument to sqlite3_collation_needed() or sqlite3_collation_needed16(). 36The second argument is the database connection. 37The third argument is one of SQLITE_UTF8, SQLITE_UTF16BE, 38or SQLITE_UTF16LE, indicating the most desirable form 39of the collation sequence function required. 40The fourth parameter is the name of the required collation sequence. 41.Pp 42The callback function should register the desired collation using sqlite3_create_collation(), 43sqlite3_create_collation16(), or sqlite3_create_collation_v2(). 44.Sh SEE ALSO 45.Xr sqlite3 3 , 46.Xr sqlite3_create_collation 3 , 47.Xr SQLITE_UTF8 3 48