Debian Codegraph @

www/capi3.html

raw
1 <!DOCTYPE html>
2 <html><head>
3 <meta name="viewport" content="width=device-width, initial-scale=1.0">
4 <meta http-equiv="content-type" content="text/html; charset=UTF-8">
5 <link href="sqlite.css" rel="stylesheet">
6 <title>C/C++ Interface For SQLite Version 3 (old)</title>
7 <!-- path= -->
8 </head>
9 <body>
10 <div class=nosearch>
11 <a href="index.html">
12 <img class="logo" src="images/sqlite370_banner.svg" alt="SQLite" border="0">
13 </a>
14 <div><!-- IE hack to prevent disappearing logo --></div>
15 <div class="tagline desktoponly">
16 Small. Fast. Reliable.<br>Choose any three.
17 </div>
18 <div class="menu mainmenu">
19 <ul>
20 <li><a href="index.html">Home</a>
21 <li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a>
22 <li class='wideonly'><a href='about.html'>About</a>
23 <li class='desktoponly'><a href="docs.html">Documentation</a>
24 <li class='desktoponly'><a href="download.html">Download</a>
25 <li class='wideonly'><a href='copyright.html'>License</a>
26 <li class='desktoponly'><a href="support.html">Support</a>
27 <li class='desktoponly'><a href="prosupport.html">Purchase</a>
28 <li class='search' id='search_menubutton'>
29 <a href="javascript:void(0)" onclick='toggle_search()'>Search</a>
30 </ul>
31 </div>
32 <div class="menu submenu" id="submenu">
33 <ul>
34 <li><a href='about.html'>About</a>
35 <li><a href='docs.html'>Documentation</a>
36 <li><a href='download.html'>Download</a>
37 <li><a href='support.html'>Support</a>
38 <li><a href='prosupport.html'>Purchase</a>
39 </ul>
40 </div>
41 <div class="searchmenu" id="searchmenu">
42 <form method="GET" action="search">
43 <select name="s" id="searchtype">
44 <option value="d">Search Documentation</option>
45 <option value="c">Search Changelog</option>
46 </select>
47 <input type="text" name="q" id="searchbox" value="">
48 <input type="submit" value="Go">
49 </form>
50 </div>
51 </div>
52 <script>
53 function toggle_div(nm) {
54 var w = document.getElementById(nm);
55 if( w.style.display=="block" ){
56 w.style.display = "none";
57 }else{
58 w.style.display = "block";
59 }
60 }
61 function toggle_search() {
62 var w = document.getElementById("searchmenu");
63 if( w.style.display=="block" ){
64 w.style.display = "none";
65 } else {
66 w.style.display = "block";
67 setTimeout(function(){
68 document.getElementById("searchbox").focus()
69 }, 30);
70 }
71 }
72 function div_off(nm){document.getElementById(nm).style.display="none";}
73 window.onbeforeunload = function(e){div_off("submenu");}
74 /* Disable the Search feature if we are not operating from CGI, since */
75 /* Search is accomplished using CGI and will not work without it. */
76 if( !location.origin || !location.origin.match || !location.origin.match(/http/) ){
77 document.getElementById("search_menubutton").style.display = "none";
78 }
79 /* Used by the Hide/Show button beside syntax diagrams, to toggle the */
80 function hideorshow(btn,obj){
81 var x = document.getElementById(obj);
82 var b = document.getElementById(btn);
83 if( x.style.display!='none' ){
84 x.style.display = 'none';
85 b.innerHTML='show';
86 }else{
87 x.style.display = '';
88 b.innerHTML='hide';
89 }
90 return false;
91 }
92 var antiRobot = 0;
93 function antiRobotGo(){
94 if( antiRobot!=3 ) return;
95 antiRobot = 7;
96 var j = document.getElementById("mtimelink");
97 if(j && j.hasAttribute("data-href")) j.href=j.getAttribute("data-href");
98 }
99 function antiRobotDefense(){
100 document.body.onmousedown=function(){
101 antiRobot |= 2;
102 antiRobotGo();
103 document.body.onmousedown=null;
104 }
105 document.body.onmousemove=function(){
106 antiRobot |= 2;
107 antiRobotGo();
108 document.body.onmousemove=null;
109 }
110 setTimeout(function(){
111 antiRobot |= 1;
112 antiRobotGo();
113 }, 100)
114 antiRobotGo();
115 }
116 antiRobotDefense();
117 </script>
118
119
120
121 <font color="#7f001f"><p>
122 <b>Note:</b>
123 This document was written in 2004 as a guide to helping programmers
124 move from using SQLite version 2 to SQLite version 3. The information
125 in this document is still essentially correct, however there have been
126 many changes and enhancements over the years. We recommend that the
127 following documents be used instead:
128 <ul>
129 <li><a href="cintro.html">An Introduction To The SQLite C/C++ Interface</a></li>
130 <li><a href="c3ref/intro.html">SQLite C/C++ Reference Guide</a></li>
131 </ul>
132 </p>
133 </font>
134
135 <h2>C/C++ Interface For SQLite Version 3</h2>
136
137 <h3>1.0 Overview</h3>
138
139 <p>
140 SQLite version 3.0 is a new version of SQLite, derived from
141 the SQLite 2.8.13 code base, but with an incompatible file format
142 and API.
143 SQLite version 3.0 was created to answer demand for the following features:
144 </p>
145
146 <ul>
147 <li>Support for UTF-16.</li>
148 <li>User-definable text collating sequences.</li>
149 <li>The ability to store BLOBs in indexed columns.</li>
150 </ul>
151
152 <p>
153 It was necessary to move to version 3.0 to implement these features because
154 each requires incompatible changes to the database file format. Other
155 incompatible changes, such as a cleanup of the API, were introduced at the
156 same time under the theory that it is best to get your incompatible changes
157 out of the way all at once.
158 </p>
159
160 <p>
161 The API for version 3.0 is similar to the version 2.X API,
162 but with some important changes. Most noticeably, the "<tt>sqlite_</tt>"
163 prefix that occurs on the beginning of all API functions and data
164 structures are changed to "<tt>sqlite3_</tt>".
165 This avoids confusion between the two APIs and allows linking against both
166 SQLite 2.X and SQLite 3.0 at the same time.
167 </p>
168
169 <p>
170 There is no agreement on what the C datatype for a UTF-16
171 string should be. Therefore, SQLite uses a generic type of void*
172 to refer to UTF-16 strings. Client software can cast the void*
173 to whatever datatype is appropriate for their system.
174 </p>
175
176 <h3>2.0 C/C++ Interface</h3>
177
178 <p>
179 The API for SQLite 3.0 includes 83 separate functions in addition
180 to several data structures and #defines. (A complete
181 <a href="c3ref/intro.html">API reference</a> is provided as a separate
182 document.)
183 Fortunately, the interface is not nearly as complex as its size implies.
184 Simple programs can still make do with only 3 functions:
185 <a href="c3ref/open.html">sqlite3_open()</a>, <a href="c3ref/exec.html">sqlite3_exec()</a>, and <a href="c3ref/close.html">sqlite3_close()</a>.
186 More control over the execution of the database engine is provided
187 using <a href="c3ref/prepare.html">sqlite3_prepare_v2()</a>
188 to compile an SQLite statement into byte code and
189 <a href="c3ref/step.html">sqlite3_step()</a> to execute that bytecode.
190 A family of routines with names beginning with
191 <a href="c3ref/column_blob.html">sqlite3_column_</a>
192 is used to extract information about the result set of a query.
193 Many interface functions come in pairs, with both a UTF-8 and
194 UTF-16 version. And there is a collection of routines
195 used to implement user-defined SQL functions and user-defined
196 text collating sequences.
197 </p>
198
199
200 <h4>2.1 Opening and closing a database</h4>
201
202 <blockquote><pre>
203 typedef struct sqlite3 sqlite3;
204 int sqlite3_open(const char*, sqlite3**);
205 int sqlite3_open16(const void*, sqlite3**);
206 int sqlite3_close(sqlite3*);
207 const char *sqlite3_errmsg(sqlite3*);
208 const void *sqlite3_errmsg16(sqlite3*);
209 int sqlite3_errcode(sqlite3*);
210 </pre></blockquote>
211
212 <p>
213 The sqlite3_open() routine returns an integer error code rather than
214 a pointer to the sqlite3 structure as the version 2 interface did.
215 The difference between sqlite3_open()
216 and sqlite3_open16() is that sqlite3_open16() takes UTF-16 (in host native
217 byte order) for the name of the database file. If a new database file
218 needs to be created, then sqlite3_open16() sets the internal text
219 representation to UTF-16 whereas sqlite3_open() sets the text
220 representation to UTF-8.
221 </p>
222
223 <p>
224 The opening and/or creating of the database file is deferred until the
225 file is actually needed. This allows options and parameters, such
226 as the native text representation and default page size, to be
227 set using PRAGMA statements.
228 </p>
229
230 <p>
231 The sqlite3_errcode() routine returns a result code for the most
232 recent major API call. sqlite3_errmsg() returns an English-language
233 text error message for the most recent error. The error message is
234 represented in UTF-8 and will be ephemeral - it could disappear on
235 the next call to any SQLite API function. sqlite3_errmsg16() works like
236 sqlite3_errmsg() except that it returns the error message represented
237 as UTF-16 in host native byte order.
238 </p>
239
240 <p>
241 The error codes for SQLite version 3 are unchanged from version 2.
242 They are as follows:
243 </p>
244
245 <blockquote><pre>
246 #define SQLITE_OK 0 /* Successful result */
247 #define SQLITE_ERROR 1 /* SQL error or missing database */
248 #define SQLITE_INTERNAL 2 /* An internal logic error in SQLite */
249 #define SQLITE_PERM 3 /* Access permission denied */
250 #define SQLITE_ABORT 4 /* Callback routine requested an abort */
251 #define SQLITE_BUSY 5 /* The database file is locked */
252 #define SQLITE_LOCKED 6 /* A table in the database is locked */
253 #define SQLITE_NOMEM 7 /* A malloc() failed */
254 #define SQLITE_READONLY 8 /* Attempt to write a readonly database */
255 #define SQLITE_INTERRUPT 9 /* Operation terminated by sqlite_interrupt() */
256 #define SQLITE_IOERR 10 /* Some kind of disk I/O error occurred */
257 #define SQLITE_CORRUPT 11 /* The database disk image is malformed */
258 #define SQLITE_NOTFOUND 12 /* (Internal Only) Table or record not found */
259 #define SQLITE_FULL 13 /* Insertion failed because database is full */
260 #define SQLITE_CANTOPEN 14 /* Unable to open the database file */
261 #define SQLITE_PROTOCOL 15 /* Database lock protocol error */
262 #define SQLITE_EMPTY 16 /* (Internal Only) Database table is empty */
263 #define SQLITE_SCHEMA 17 /* The database schema changed */
264 #define SQLITE_TOOBIG 18 /* Too much data for one row of a table */
265 #define SQLITE_CONSTRAINT 19 /* Abort due to contraint violation */
266 #define SQLITE_MISMATCH 20 /* Data type mismatch */
267 #define SQLITE_MISUSE 21 /* Library used incorrectly */
268 #define SQLITE_NOLFS 22 /* Uses OS features not supported on host */
269 #define SQLITE_AUTH 23 /* Authorization denied */
270 #define SQLITE_ROW 100 /* sqlite_step() has another row ready */
271 #define SQLITE_DONE 101 /* sqlite_step() has finished executing */
272 </pre></blockquote>
273
274 <h4>2.2 Executing SQL statements</h4>
275
276 <blockquote><pre>
277 typedef int (*sqlite_callback)(void*,int,char**, char**);
278 int sqlite3_exec(sqlite3*, const char *sql, sqlite_callback, void*, char**);
279 </pre></blockquote>
280
281 <p>
282 The <a href="c3ref/exec.html">sqlite3_exec()</a> function works much as it did in SQLite version 2.
283 Zero or more SQL statements specified in the second parameter are compiled
284 and executed. Query results are returned to a callback routine.
285 </p>
286
287 <p>
288 In SQLite version 3, the sqlite3_exec routine is just a wrapper around
289 calls to the prepared statement interface.
290 </p>
291
292 <blockquote><pre>
293 typedef struct sqlite3_stmt sqlite3_stmt;
294 int sqlite3_prepare(sqlite3*, const char*, int, sqlite3_stmt**, const char**);
295 int sqlite3_prepare16(sqlite3*, const void*, int, sqlite3_stmt**, const void**);
296 int sqlite3_finalize(sqlite3_stmt*);
297 int sqlite3_reset(sqlite3_stmt*);
298 </pre></blockquote>
299
300 <p>
301 The sqlite3_prepare interface compiles a single SQL statement into byte code
302 for later execution. This interface is now the preferred way of accessing
303 the database.
304 </p>
305
306 <p>
307 The SQL statement is a UTF-8 string for sqlite3_prepare().
308 The sqlite3_prepare16() works the same way except
309 that it expects a UTF-16 string as SQL input.
310 Only the first SQL statement in the input string is compiled.
311 The fifth parameter is filled in with a pointer to the next (uncompiled)
312 SQLite statement in the input string, if any.
313 The sqlite3_finalize() routine deallocates a prepared SQL statement.
314 All prepared statements must be finalized before the database can be
315 closed.
316 The sqlite3_reset() routine resets a prepared SQL statement so that it
317 can be executed again.
318 </p>
319
320 <p>
321 The SQL statement may contain tokens of the form "?" or "?nnn" or ":aaa"
322 where "nnn" is an integer and "aaa" is an identifier.
323 Such tokens represent unspecified literal values (or "wildcards")
324 to be filled in later by the
325 <a href="c3ref/bind_blob.html">sqlite3_bind</a> interface.
326 Each wildcard has an associated number which is its sequence in the
327 statement or the "nnn" in the case of a "?nnn" form.
328 It is allowed for the same wildcard
329 to occur more than once in the same SQL statement, in which case
330 all instance of that wildcard will be filled in with the same value.
331 Unbound wildcards have a value of NULL.
332 </p>
333
334 <blockquote><pre>
335 int sqlite3_bind_blob(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
336 int sqlite3_bind_double(sqlite3_stmt*, int, double);
337 int sqlite3_bind_int(sqlite3_stmt*, int, int);
338 int sqlite3_bind_int64(sqlite3_stmt*, int, long long int);
339 int sqlite3_bind_null(sqlite3_stmt*, int);
340 int sqlite3_bind_text(sqlite3_stmt*, int, const char*, int n, void(*)(void*));
341 int sqlite3_bind_text16(sqlite3_stmt*, int, const void*, int n, void(*)(void*));
342 int sqlite3_bind_value(sqlite3_stmt*, int, const sqlite3_value*);
343 </pre></blockquote>
344
345 <p>
346 There is an assortment of sqlite3_bind routines used to assign values
347 to wildcards in a prepared SQL statement. Unbound wildcards
348 are interpreted as NULLs. Bindings are not reset by sqlite3_reset().
349 But wildcards can be rebound to new values after an sqlite3_reset().
350 </p>
351
352 <p>
353 After an SQL statement has been prepared (and optionally bound), it
354 is executed using:
355 </p>
356
357 <blockquote><pre>
358 int sqlite3_step(sqlite3_stmt*);
359 </pre></blockquote>
360
361 <p>
362 The sqlite3_step() routine returns SQLITE_ROW if it is returning a single
363 row of the result set, or SQLITE_DONE if execution has completed, either
364 normally or due to an error. It might also return SQLITE_BUSY if it is
365 unable to open the database file. If the return value is SQLITE_ROW, then
366 the following routines can be used to extract information about that row
367 of the result set:
368 </p>
369
370 <blockquote><pre>
371 const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
372 int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
373 int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
374 int sqlite3_column_count(sqlite3_stmt*);
375 const char *sqlite3_column_decltype(sqlite3_stmt *, int iCol);
376 const void *sqlite3_column_decltype16(sqlite3_stmt *, int iCol);
377 double sqlite3_column_double(sqlite3_stmt*, int iCol);
378 int sqlite3_column_int(sqlite3_stmt*, int iCol);
379 long long int sqlite3_column_int64(sqlite3_stmt*, int iCol);
380 const char *sqlite3_column_name(sqlite3_stmt*, int iCol);
381 const void *sqlite3_column_name16(sqlite3_stmt*, int iCol);
382 const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);
383 const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);
384 int sqlite3_column_type(sqlite3_stmt*, int iCol);
385 </pre></blockquote>
386
387 <p>
388 The <a href="c3ref/column_count.html">sqlite3_column_count()</a>
389 function returns the number of columns in
390 the results set. sqlite3_column_count() can be called at any time after
391 <a href="c3ref/prepare.html">sqlite3_prepare_v2()</a>. <a href="c3ref/data_count.html">sqlite3_data_count()</a> works similarly to
392 <a href="c3ref/column_count.html">sqlite3_column_count()</a> except that it only works following <a href="c3ref/step.html">sqlite3_step()</a>.
393 If the previous call to <a href="c3ref/step.html">sqlite3_step()</a> returned SQLITE_DONE or an error code,
394 then <a href="c3ref/data_count.html">sqlite3_data_count()</a> will return 0 whereas <a href="c3ref/column_count.html">sqlite3_column_count()</a> will
395 continue to return the number of columns in the result set.
396 </p>
397
398 <p>Returned data is examined using the other
399 <a href="c3ref/column_blob.html">sqlite3_column_***()</a> functions,
400 all of which take a column number as their second parameter. Columns are
401 zero-indexed from left to right. Note that this is different to parameters,
402 which are indexed starting at one.
403 </p>
404
405 <p>
406 The <a href="c3ref/column_blob.html">sqlite3_column_type()</a> function returns the
407 datatype for the value in the Nth column. The return value is one
408 of these:
409 </p>
410
411 <blockquote><pre>
412 #define SQLITE_INTEGER 1
413 #define SQLITE_FLOAT 2
414 #define SQLITE_TEXT 3
415 #define SQLITE_BLOB 4
416 #define SQLITE_NULL 5
417 </pre></blockquote>
418
419 <p>
420 The sqlite3_column_decltype() routine returns text which is the
421 declared type of the column in the CREATE TABLE statement. For an
422 expression, the return type is an empty string. sqlite3_column_name()
423 returns the name of the Nth column. sqlite3_column_bytes() returns
424 the number of bytes in a column that has type BLOB or the number of bytes
425 in a TEXT string with UTF-8 encoding. sqlite3_column_bytes16() returns
426 the same value for BLOBs but for TEXT strings returns the number of bytes
427 in a UTF-16 encoding.
428 <ul>
429 <li>sqlite3_column_blob() return BLOB data.
430 <li>sqlite3_column_text() return TEXT data as UTF-8.
431 <li>sqlite3_column_text16() return TEXT data as UTF-16.
432 <li>sqlite3_column_int() return INTEGER data in the host machines native
433 integer format.
434 <li>sqlite3_column_int64() returns 64-bit INTEGER data.
435 <li>Finally, sqlite3_column_double() return floating point data.
436 </ul>
437 </p>
438
439 <p>
440 It is not necessary to retrieve data in the format specified by
441 sqlite3_column_type(). If a different format is requested, the data
442 is converted automatically.
443 </p>
444
445 <p>
446 Data format conversions can invalidate the pointer returned by
447 prior calls to sqlite3_column_blob(), sqlite3_column_text(), and/or
448 sqlite3_column_text16(). Pointers might be invalided in the following
449 cases:
450 </p>
451 <ul>
452 <li><p>
453 The initial content is a BLOB and sqlite3_column_text()
454 or sqlite3_column_text16()
455 is called. A zero-terminator might need to be added to the string.
456 </p></li>
457 <li><p>
458 The initial content is UTF-8 text and sqlite3_column_bytes16() or
459 sqlite3_column_text16() is called. The content must be converted to UTF-16.
460 </p></li>
461 <li><p>
462 The initial content is UTF-16 text and sqlite3_column_bytes() or
463 sqlite3_column_text() is called. The content must be converted to UTF-8.
464 </p></li>
465 </ul>
466 <p>
467 Note that conversions between UTF-16be and UTF-16le
468 are always done in place and do
469 not invalidate a prior pointer, though of course the content of the buffer
470 that the prior pointer points to will have been modified. Other kinds
471 of conversion are done in place when it is possible, but sometime it is
472 not possible and in those cases prior pointers are invalidated.
473 </p>
474
475 <p>
476 The safest and easiest to remember policy is this: assume that any
477 result from
478 <ul>
479 <li>sqlite3_column_blob(),</li>
480 <li>sqlite3_column_text(), or</li>
481 <li>sqlite3_column_text16()</li>
482 </ul>
483 is invalided by subsequent calls to
484 <ul>
485 <li>sqlite3_column_bytes(),</li>
486 <li>sqlite3_column_bytes16(),</li>
487 <li>sqlite3_column_text(), or</li>
488 <li>sqlite3_column_text16().</li>
489 </ul>
490 This means that you should always call sqlite3_column_bytes() or
491 sqlite3_column_bytes16() <u>before</u> calling sqlite3_column_blob(),
492 sqlite3_column_text(), or sqlite3_column_text16().
493 </p>
494
495 <h4>2.3 User-defined functions</h4>
496
497 <p>
498 User defined functions can be created using the following routine:
499 </p>
500
501 <blockquote><pre>
502 typedef struct sqlite3_value sqlite3_value;
503 int sqlite3_create_function(
504 sqlite3 *,
505 const char *zFunctionName,
506 int nArg,
507 int eTextRep,
508 void*,
509 void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
510 void (*xStep)(sqlite3_context*,int,sqlite3_value**),
511 void (*xFinal)(sqlite3_context*)
512 );
513 int sqlite3_create_function16(
514 sqlite3*,
515 const void *zFunctionName,
516 int nArg,
517 int eTextRep,
518 void*,
519 void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
520 void (*xStep)(sqlite3_context*,int,sqlite3_value**),
521 void (*xFinal)(sqlite3_context*)
522 );
523 #define SQLITE_UTF8 1
524 #define SQLITE_UTF16 2
525 #define SQLITE_UTF16BE 3
526 #define SQLITE_UTF16LE 4
527 #define SQLITE_ANY 5
528 </pre></blockquote>
529
530 <p>
531 The nArg parameter specifies the number of arguments to the function.
532 A value of 0 indicates that any number of arguments is allowed. The
533 eTextRep parameter specifies what representation text values are expected
534 to be in for arguments to this function. The value of this parameter should
535 be one of the parameters defined above. SQLite version 3 allows multiple
536 implementations of the same function using different text representations.
537 The database engine chooses the function that minimizes the number
538 of text conversions required.
539 </p>
540
541 <p>
542 Normal functions specify only xFunc and leave xStep and xFinal set to NULL.
543 Aggregate functions specify xStep and xFinal and leave xFunc set to NULL.
544 There is no separate sqlite3_create_aggregate() API.
545 </p>
546
547 <p>
548 The function name is specified in UTF-8. A separate sqlite3_create_function16()
549 API works the same as sqlite_create_function()
550 except that the function name is specified in UTF-16 host byte order.
551 </p>
552
553 <p>
554 Notice that the parameters to functions are now pointers to sqlite3_value
555 structures instead of pointers to strings as in SQLite version 2.X.
556 The following routines are used to extract useful information from these
557 "values":
558 </p>
559
560 <blockquote><pre>
561 const void *sqlite3_value_blob(sqlite3_value*);
562 int sqlite3_value_bytes(sqlite3_value*);
563 int sqlite3_value_bytes16(sqlite3_value*);
564 double sqlite3_value_double(sqlite3_value*);
565 int sqlite3_value_int(sqlite3_value*);
566 long long int sqlite3_value_int64(sqlite3_value*);
567 const unsigned char *sqlite3_value_text(sqlite3_value*);
568 const void *sqlite3_value_text16(sqlite3_value*);
569 int sqlite3_value_type(sqlite3_value*);
570 </pre></blockquote>
571
572 <p>
573 Function implementations use the following APIs to acquire context and
574 to report results:
575 </p>
576
577 <blockquote><pre>
578 void *sqlite3_aggregate_context(sqlite3_context*, int nbyte);
579 void *sqlite3_user_data(sqlite3_context*);
580 void sqlite3_result_blob(sqlite3_context*, const void*, int n, void(*)(void*));
581 void sqlite3_result_double(sqlite3_context*, double);
582 void sqlite3_result_error(sqlite3_context*, const char*, int);
583 void sqlite3_result_error16(sqlite3_context*, const void*, int);
584 void sqlite3_result_int(sqlite3_context*, int);
585 void sqlite3_result_int64(sqlite3_context*, long long int);
586 void sqlite3_result_null(sqlite3_context*);
587 void sqlite3_result_text(sqlite3_context*, const char*, int n, void(*)(void*));
588 void sqlite3_result_text16(sqlite3_context*, const void*, int n, void(*)(void*));
589 void sqlite3_result_value(sqlite3_context*, sqlite3_value*);
590 void *sqlite3_get_auxdata(sqlite3_context*, int);
591 void sqlite3_set_auxdata(sqlite3_context*, int, void*, void (*)(void*));
592 </pre></blockquote>
593
594 <h4>2.4 User-defined collating sequences</h4>
595
596 <p>
597 The following routines are used to implement user-defined
598 collating sequences:
599 </p>
600
601 <blockquote><pre>
602 sqlite3_create_collation(sqlite3*, const char *zName, int eTextRep, void*,
603 int(*xCompare)(void*,int,const void*,int,const void*));
604 sqlite3_create_collation16(sqlite3*, const void *zName, int eTextRep, void*,
605 int(*xCompare)(void*,int,const void*,int,const void*));
606 sqlite3_collation_needed(sqlite3*, void*,
607 void(*)(void*,sqlite3*,int eTextRep,const char*));
608 sqlite3_collation_needed16(sqlite3*, void*,
609 void(*)(void*,sqlite3*,int eTextRep,const void*));
610 </pre></blockquote>
611
612 <p>
613 The sqlite3_create_collation() function specifies a collating sequence name
614 and a comparison function to implement that collating sequence. The
615 comparison function is only used for comparing text values. The eTextRep
616 parameter is one of SQLITE_UTF8, SQLITE_UTF16LE, SQLITE_UTF16BE, or
617 SQLITE_ANY to specify which text representation the comparison function works
618 with. Separate comparison functions can exist for the same collating
619 sequence for each of the UTF-8, UTF-16LE and UTF-16BE text representations.
620 The sqlite3_create_collation16() works like sqlite3_create_collation() except
621 that the collation name is specified in UTF-16 host byte order instead of
622 in UTF-8.
623 </p>
624
625 <p>
626 The sqlite3_collation_needed() routine registers a callback which the
627 database engine will invoke if it encounters an unknown collating sequence.
628 The callback can lookup an appropriate comparison function and invoke
629 sqlite_3_create_collation() as needed. The fourth parameter to the callback
630 is the name of the collating sequence in UTF-8. For sqlite3_collation_need16()
631 the callback sends the collating sequence name in UTF-16 host byte order.
632 </p>
633 <p align="center"><small><i>This page was last updated on 2025-07-12 15:11:36Z </small></i></p>
634