sqlite3.h.svn-base
上传用户:sunhongbo
上传日期:2022-01-25
资源大小:3010k
文件大小:251k
源码类别:

数据库系统

开发平台:

C/C++

  1. **          or until [sqlite3_finalize(S)] is called.
  2. **
  3. ** {F13727} When a result column of a [SELECT] statement contains
  4. **          an AS clause, the name of that column is the indentifier
  5. **          to the right of the AS keyword.
  6. */
  7. const char *sqlite3_column_name(sqlite3_stmt*, int N);
  8. const void *sqlite3_column_name16(sqlite3_stmt*, int N);
  9. /*
  10. ** CAPI3REF: Source Of Data In A Query Result {F13740}
  11. **
  12. ** These routines provide a means to determine what column of what
  13. ** table in which database a result of a SELECT statement comes from.
  14. ** The name of the database or table or column can be returned as
  15. ** either a UTF8 or UTF16 string.  The _database_ routines return
  16. ** the database name, the _table_ routines return the table name, and
  17. ** the origin_ routines return the column name.
  18. ** The returned string is valid until
  19. ** the [prepared statement] is destroyed using
  20. ** [sqlite3_finalize()] or until the same information is requested
  21. ** again in a different encoding.
  22. **
  23. ** The names returned are the original un-aliased names of the
  24. ** database, table, and column.
  25. **
  26. ** The first argument to the following calls is a [prepared statement].
  27. ** These functions return information about the Nth column returned by 
  28. ** the statement, where N is the second function argument.
  29. **
  30. ** If the Nth column returned by the statement is an expression
  31. ** or subquery and is not a column value, then all of these functions
  32. ** return NULL.  These routine might also return NULL if a memory
  33. ** allocation error occurs.  Otherwise, they return the 
  34. ** name of the attached database, table and column that query result
  35. ** column was extracted from.
  36. **
  37. ** As with all other SQLite APIs, those postfixed with "16" return
  38. ** UTF-16 encoded strings, the other functions return UTF-8. {END}
  39. **
  40. ** These APIs are only available if the library was compiled with the 
  41. ** SQLITE_ENABLE_COLUMN_METADATA preprocessor symbol defined.
  42. **
  43. ** {U13751}
  44. ** If two or more threads call one or more of these routines against the same
  45. ** prepared statement and column at the same time then the results are
  46. ** undefined.
  47. **
  48. ** INVARIANTS:
  49. **
  50. ** {F13741} The [sqlite3_column_database_name(S,N)] interface returns either
  51. **          the UTF-8 zero-terminated name of the database from which the 
  52. **          Nth result column of [prepared statement] S 
  53. **          is extracted, or NULL if the the Nth column of S is a
  54. **          general expression or if unable to allocate memory
  55. **          to store the name.
  56. **          
  57. ** {F13742} The [sqlite3_column_database_name16(S,N)] interface returns either
  58. **          the UTF-16 native byte order
  59. **          zero-terminated name of the database from which the 
  60. **          Nth result column of [prepared statement] S 
  61. **          is extracted, or NULL if the the Nth column of S is a
  62. **          general expression or if unable to allocate memory
  63. **          to store the name.
  64. **          
  65. ** {F13743} The [sqlite3_column_table_name(S,N)] interface returns either
  66. **          the UTF-8 zero-terminated name of the table from which the 
  67. **          Nth result column of [prepared statement] S 
  68. **          is extracted, or NULL if the the Nth column of S is a
  69. **          general expression or if unable to allocate memory
  70. **          to store the name.
  71. **          
  72. ** {F13744} The [sqlite3_column_table_name16(S,N)] interface returns either
  73. **          the UTF-16 native byte order
  74. **          zero-terminated name of the table from which the 
  75. **          Nth result column of [prepared statement] S 
  76. **          is extracted, or NULL if the the Nth column of S is a
  77. **          general expression or if unable to allocate memory
  78. **          to store the name.
  79. **          
  80. ** {F13745} The [sqlite3_column_origin_name(S,N)] interface returns either
  81. **          the UTF-8 zero-terminated name of the table column from which the 
  82. **          Nth result column of [prepared statement] S 
  83. **          is extracted, or NULL if the the Nth column of S is a
  84. **          general expression or if unable to allocate memory
  85. **          to store the name.
  86. **          
  87. ** {F13746} The [sqlite3_column_origin_name16(S,N)] interface returns either
  88. **          the UTF-16 native byte order
  89. **          zero-terminated name of the table column from which the 
  90. **          Nth result column of [prepared statement] S 
  91. **          is extracted, or NULL if the the Nth column of S is a
  92. **          general expression or if unable to allocate memory
  93. **          to store the name.
  94. **          
  95. ** {F13748} The return values from
  96. **          [sqlite3_column_database_name|column metadata interfaces]
  97. **          are valid
  98. **          for the lifetime of the [prepared statement]
  99. **          or until the encoding is changed by another metadata
  100. **          interface call for the same prepared statement and column.
  101. **
  102. ** LIMITATIONS:
  103. **
  104. ** {U13751} If two or more threads call one or more
  105. **          [sqlite3_column_database_name|column metadata interfaces]
  106. **          the same [prepared statement] and result column
  107. **          at the same time then the results are undefined.
  108. */
  109. const char *sqlite3_column_database_name(sqlite3_stmt*,int);
  110. const void *sqlite3_column_database_name16(sqlite3_stmt*,int);
  111. const char *sqlite3_column_table_name(sqlite3_stmt*,int);
  112. const void *sqlite3_column_table_name16(sqlite3_stmt*,int);
  113. const char *sqlite3_column_origin_name(sqlite3_stmt*,int);
  114. const void *sqlite3_column_origin_name16(sqlite3_stmt*,int);
  115. /*
  116. ** CAPI3REF: Declared Datatype Of A Query Result {F13760}
  117. **
  118. ** The first parameter is a [prepared statement]. 
  119. ** If this statement is a SELECT statement and the Nth column of the 
  120. ** returned result set of that SELECT is a table column (not an
  121. ** expression or subquery) then the declared type of the table
  122. ** column is returned.  If the Nth column of the result set is an
  123. ** expression or subquery, then a NULL pointer is returned.
  124. ** The returned string is always UTF-8 encoded.  {END} 
  125. ** For example, in the database schema:
  126. **
  127. ** CREATE TABLE t1(c1 VARIANT);
  128. **
  129. ** And the following statement compiled:
  130. **
  131. ** SELECT c1 + 1, c1 FROM t1;
  132. **
  133. ** Then this routine would return the string "VARIANT" for the second
  134. ** result column (i==1), and a NULL pointer for the first result column
  135. ** (i==0).
  136. **
  137. ** SQLite uses dynamic run-time typing.  So just because a column
  138. ** is declared to contain a particular type does not mean that the
  139. ** data stored in that column is of the declared type.  SQLite is
  140. ** strongly typed, but the typing is dynamic not static.  Type
  141. ** is associated with individual values, not with the containers
  142. ** used to hold those values.
  143. **
  144. ** INVARIANTS:
  145. **
  146. ** {F13761}  A successful call to [sqlite3_column_decltype(S,N)]
  147. **           returns a zero-terminated UTF-8 string containing the
  148. **           the declared datatype of the table column that appears
  149. **           as the Nth column (numbered from 0) of the result set to the
  150. **           [prepared statement] S.
  151. **
  152. ** {F13762}  A successful call to [sqlite3_column_decltype16(S,N)]
  153. **           returns a zero-terminated UTF-16 native byte order string
  154. **           containing the declared datatype of the table column that appears
  155. **           as the Nth column (numbered from 0) of the result set to the
  156. **           [prepared statement] S.
  157. **
  158. ** {F13763}  If N is less than 0 or N is greater than or equal to
  159. **           the number of columns in [prepared statement] S
  160. **           or if the Nth column of S is an expression or subquery rather
  161. **           than a table column or if a memory allocation failure
  162. **           occurs during encoding conversions, then
  163. **           calls to [sqlite3_column_decltype(S,N)] or
  164. **           [sqlite3_column_decltype16(S,N)] return NULL.
  165. */
  166. const char *sqlite3_column_decltype(sqlite3_stmt*,int);
  167. const void *sqlite3_column_decltype16(sqlite3_stmt*,int);
  168. /* 
  169. ** CAPI3REF:  Evaluate An SQL Statement {F13200}
  170. **
  171. ** After an [prepared statement] has been prepared with a call
  172. ** to either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] or to one of
  173. ** the legacy interfaces [sqlite3_prepare()] or [sqlite3_prepare16()],
  174. ** then this function must be called one or more times to evaluate the 
  175. ** statement.
  176. **
  177. ** The details of the behavior of this sqlite3_step() interface depend
  178. ** on whether the statement was prepared using the newer "v2" interface
  179. ** [sqlite3_prepare_v2()] and [sqlite3_prepare16_v2()] or the older legacy
  180. ** interface [sqlite3_prepare()] and [sqlite3_prepare16()].  The use of the
  181. ** new "v2" interface is recommended for new applications but the legacy
  182. ** interface will continue to be supported.
  183. **
  184. ** In the lagacy interface, the return value will be either [SQLITE_BUSY], 
  185. ** [SQLITE_DONE], [SQLITE_ROW], [SQLITE_ERROR], or [SQLITE_MISUSE].
  186. ** With the "v2" interface, any of the other [SQLITE_OK | result code]
  187. ** or [SQLITE_IOERR_READ | extended result code] might be returned as
  188. ** well.
  189. **
  190. ** [SQLITE_BUSY] means that the database engine was unable to acquire the
  191. ** database locks it needs to do its job.  If the statement is a COMMIT
  192. ** or occurs outside of an explicit transaction, then you can retry the
  193. ** statement.  If the statement is not a COMMIT and occurs within a
  194. ** explicit transaction then you should rollback the transaction before
  195. ** continuing.
  196. **
  197. ** [SQLITE_DONE] means that the statement has finished executing
  198. ** successfully.  sqlite3_step() should not be called again on this virtual
  199. ** machine without first calling [sqlite3_reset()] to reset the virtual
  200. ** machine back to its initial state.
  201. **
  202. ** If the SQL statement being executed returns any data, then 
  203. ** [SQLITE_ROW] is returned each time a new row of data is ready
  204. ** for processing by the caller. The values may be accessed using
  205. ** the [sqlite3_column_int | column access functions].
  206. ** sqlite3_step() is called again to retrieve the next row of data.
  207. ** 
  208. ** [SQLITE_ERROR] means that a run-time error (such as a constraint
  209. ** violation) has occurred.  sqlite3_step() should not be called again on
  210. ** the VM. More information may be found by calling [sqlite3_errmsg()].
  211. ** With the legacy interface, a more specific error code (example:
  212. ** [SQLITE_INTERRUPT], [SQLITE_SCHEMA], [SQLITE_CORRUPT], and so forth)
  213. ** can be obtained by calling [sqlite3_reset()] on the
  214. ** [prepared statement].  In the "v2" interface,
  215. ** the more specific error code is returned directly by sqlite3_step().
  216. **
  217. ** [SQLITE_MISUSE] means that the this routine was called inappropriately.
  218. ** Perhaps it was called on a [prepared statement] that has
  219. ** already been [sqlite3_finalize | finalized] or on one that had 
  220. ** previously returned [SQLITE_ERROR] or [SQLITE_DONE].  Or it could
  221. ** be the case that the same database connection is being used by two or
  222. ** more threads at the same moment in time.
  223. **
  224. ** <b>Goofy Interface Alert:</b>
  225. ** In the legacy interface, 
  226. ** the sqlite3_step() API always returns a generic error code,
  227. ** [SQLITE_ERROR], following any error other than [SQLITE_BUSY]
  228. ** and [SQLITE_MISUSE].  You must call [sqlite3_reset()] or
  229. ** [sqlite3_finalize()] in order to find one of the specific
  230. ** [error codes] that better describes the error.
  231. ** We admit that this is a goofy design.  The problem has been fixed
  232. ** with the "v2" interface.  If you prepare all of your SQL statements
  233. ** using either [sqlite3_prepare_v2()] or [sqlite3_prepare16_v2()] instead
  234. ** of the legacy [sqlite3_prepare()] and [sqlite3_prepare16()], then the 
  235. ** more specific [error codes] are returned directly
  236. ** by sqlite3_step().  The use of the "v2" interface is recommended.
  237. **
  238. ** INVARIANTS:
  239. **
  240. ** {F13202}  If [prepared statement] S is ready to be
  241. **           run, then [sqlite3_step(S)] advances that prepared statement
  242. **           until to completion or until it is ready to return another
  243. **           row of the result set or an interrupt or run-time error occurs.
  244. **
  245. ** {F15304}  When a call to [sqlite3_step(S)] causes the 
  246. **           [prepared statement] S to run to completion,
  247. **           the function returns [SQLITE_DONE].
  248. **
  249. ** {F15306}  When a call to [sqlite3_step(S)] stops because it is ready
  250. **           to return another row of the result set, it returns
  251. **           [SQLITE_ROW].
  252. **
  253. ** {F15308}  If a call to [sqlite3_step(S)] encounters an
  254. **           [sqlite3_interrupt|interrupt] or a run-time error,
  255. **           it returns an appropraite error code that is not one of
  256. **           [SQLITE_OK], [SQLITE_ROW], or [SQLITE_DONE].
  257. **
  258. ** {F15310}  If an [sqlite3_interrupt|interrupt] or run-time error
  259. **           occurs during a call to [sqlite3_step(S)]
  260. **           for a [prepared statement] S created using
  261. **           legacy interfaces [sqlite3_prepare()] or
  262. **           [sqlite3_prepare16()] then the function returns either
  263. **           [SQLITE_ERROR], [SQLITE_BUSY], or [SQLITE_MISUSE].
  264. */
  265. int sqlite3_step(sqlite3_stmt*);
  266. /*
  267. ** CAPI3REF: Number of columns in a result set {F13770}
  268. **
  269. ** Return the number of values in the current row of the result set.
  270. **
  271. ** INVARIANTS:
  272. **
  273. ** {F13771}  After a call to [sqlite3_step(S)] that returns
  274. **           [SQLITE_ROW], the [sqlite3_data_count(S)] routine
  275. **           will return the same value as the
  276. **           [sqlite3_column_count(S)] function.
  277. **
  278. ** {F13772}  After [sqlite3_step(S)] has returned any value other than
  279. **           [SQLITE_ROW] or before [sqlite3_step(S)] has been 
  280. **           called on the [prepared statement] for
  281. **           the first time since it was [sqlite3_prepare|prepared]
  282. **           or [sqlite3_reset|reset], the [sqlite3_data_count(S)]
  283. **           routine returns zero.
  284. */
  285. int sqlite3_data_count(sqlite3_stmt *pStmt);
  286. /*
  287. ** CAPI3REF: Fundamental Datatypes {F10265}
  288. ** KEYWORDS: SQLITE_TEXT
  289. **
  290. ** {F10266}Every value in SQLite has one of five fundamental datatypes:
  291. **
  292. ** <ul>
  293. ** <li> 64-bit signed integer
  294. ** <li> 64-bit IEEE floating point number
  295. ** <li> string
  296. ** <li> BLOB
  297. ** <li> NULL
  298. ** </ul> {END}
  299. **
  300. ** These constants are codes for each of those types.
  301. **
  302. ** Note that the SQLITE_TEXT constant was also used in SQLite version 2
  303. ** for a completely different meaning.  Software that links against both
  304. ** SQLite version 2 and SQLite version 3 should use SQLITE3_TEXT not
  305. ** SQLITE_TEXT.
  306. */
  307. #define SQLITE_INTEGER  1
  308. #define SQLITE_FLOAT    2
  309. #define SQLITE_BLOB     4
  310. #define SQLITE_NULL     5
  311. #ifdef SQLITE_TEXT
  312. # undef SQLITE_TEXT
  313. #else
  314. # define SQLITE_TEXT     3
  315. #endif
  316. #define SQLITE3_TEXT     3
  317. /*
  318. ** CAPI3REF: Results Values From A Query {F13800}
  319. **
  320. ** These routines form the "result set query" interface.
  321. **
  322. ** These routines return information about
  323. ** a single column of the current result row of a query.  In every
  324. ** case the first argument is a pointer to the 
  325. ** [prepared statement] that is being
  326. ** evaluated (the [sqlite3_stmt*] that was returned from 
  327. ** [sqlite3_prepare_v2()] or one of its variants) and
  328. ** the second argument is the index of the column for which information 
  329. ** should be returned.  The left-most column of the result set
  330. ** has an index of 0.
  331. **
  332. ** If the SQL statement is not currently point to a valid row, or if the
  333. ** the column index is out of range, the result is undefined. 
  334. ** These routines may only be called when the most recent call to
  335. ** [sqlite3_step()] has returned [SQLITE_ROW] and neither
  336. ** [sqlite3_reset()] nor [sqlite3_finalize()] has been call subsequently.
  337. ** If any of these routines are called after [sqlite3_reset()] or
  338. ** [sqlite3_finalize()] or after [sqlite3_step()] has returned
  339. ** something other than [SQLITE_ROW], the results are undefined.
  340. ** If [sqlite3_step()] or [sqlite3_reset()] or [sqlite3_finalize()]
  341. ** are called from a different thread while any of these routines
  342. ** are pending, then the results are undefined.  
  343. **
  344. ** The sqlite3_column_type() routine returns 
  345. ** [SQLITE_INTEGER | datatype code] for the initial data type
  346. ** of the result column.  The returned value is one of [SQLITE_INTEGER],
  347. ** [SQLITE_FLOAT], [SQLITE_TEXT], [SQLITE_BLOB], or [SQLITE_NULL].  The value
  348. ** returned by sqlite3_column_type() is only meaningful if no type
  349. ** conversions have occurred as described below.  After a type conversion,
  350. ** the value returned by sqlite3_column_type() is undefined.  Future
  351. ** versions of SQLite may change the behavior of sqlite3_column_type()
  352. ** following a type conversion.
  353. **
  354. ** If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes() 
  355. ** routine returns the number of bytes in that BLOB or string.
  356. ** If the result is a UTF-16 string, then sqlite3_column_bytes() converts
  357. ** the string to UTF-8 and then returns the number of bytes.
  358. ** If the result is a numeric value then sqlite3_column_bytes() uses
  359. ** [sqlite3_snprintf()] to convert that value to a UTF-8 string and returns
  360. ** the number of bytes in that string.
  361. ** The value returned does not include the zero terminator at the end
  362. ** of the string.  For clarity: the value returned is the number of
  363. ** bytes in the string, not the number of characters.
  364. **
  365. ** Strings returned by sqlite3_column_text() and sqlite3_column_text16(),
  366. ** even empty strings, are always zero terminated.  The return
  367. ** value from sqlite3_column_blob() for a zero-length blob is an arbitrary
  368. ** pointer, possibly even a NULL pointer.
  369. **
  370. ** The sqlite3_column_bytes16() routine is similar to sqlite3_column_bytes()
  371. ** but leaves the result in UTF-16 in native byte order instead of UTF-8.  
  372. ** The zero terminator is not included in this count.
  373. **
  374. ** The object returned by [sqlite3_column_value()] is an
  375. ** [unprotected sqlite3_value] object.  An unprotected sqlite3_value object
  376. ** may only be used with [sqlite3_bind_value()] and [sqlite3_result_value()].
  377. ** If the [unprotected sqlite3_value] object returned by
  378. ** [sqlite3_column_value()] is used in any other way, including calls
  379. ** to routines like 
  380. ** [sqlite3_value_int()], [sqlite3_value_text()], or [sqlite3_value_bytes()],
  381. ** then the behavior is undefined.
  382. **
  383. ** These routines attempt to convert the value where appropriate.  For
  384. ** example, if the internal representation is FLOAT and a text result
  385. ** is requested, [sqlite3_snprintf()] is used internally to do the conversion
  386. ** automatically.  The following table details the conversions that
  387. ** are applied:
  388. **
  389. ** <blockquote>
  390. ** <table border="1">
  391. ** <tr><th> Internal<br>Type <th> Requested<br>Type <th>  Conversion
  392. **
  393. ** <tr><td>  NULL    <td> INTEGER   <td> Result is 0
  394. ** <tr><td>  NULL    <td>  FLOAT    <td> Result is 0.0
  395. ** <tr><td>  NULL    <td>   TEXT    <td> Result is NULL pointer
  396. ** <tr><td>  NULL    <td>   BLOB    <td> Result is NULL pointer
  397. ** <tr><td> INTEGER  <td>  FLOAT    <td> Convert from integer to float
  398. ** <tr><td> INTEGER  <td>   TEXT    <td> ASCII rendering of the integer
  399. ** <tr><td> INTEGER  <td>   BLOB    <td> Same as for INTEGER->TEXT
  400. ** <tr><td>  FLOAT   <td> INTEGER   <td> Convert from float to integer
  401. ** <tr><td>  FLOAT   <td>   TEXT    <td> ASCII rendering of the float
  402. ** <tr><td>  FLOAT   <td>   BLOB    <td> Same as FLOAT->TEXT
  403. ** <tr><td>  TEXT    <td> INTEGER   <td> Use atoi()
  404. ** <tr><td>  TEXT    <td>  FLOAT    <td> Use atof()
  405. ** <tr><td>  TEXT    <td>   BLOB    <td> No change
  406. ** <tr><td>  BLOB    <td> INTEGER   <td> Convert to TEXT then use atoi()
  407. ** <tr><td>  BLOB    <td>  FLOAT    <td> Convert to TEXT then use atof()
  408. ** <tr><td>  BLOB    <td>   TEXT    <td> Add a zero terminator if needed
  409. ** </table>
  410. ** </blockquote>
  411. **
  412. ** The table above makes reference to standard C library functions atoi()
  413. ** and atof().  SQLite does not really use these functions.  It has its
  414. ** on equavalent internal routines.  The atoi() and atof() names are
  415. ** used in the table for brevity and because they are familiar to most
  416. ** C programmers.
  417. **
  418. ** Note that when type conversions occur, pointers returned by prior
  419. ** calls to sqlite3_column_blob(), sqlite3_column_text(), and/or
  420. ** sqlite3_column_text16() may be invalidated. 
  421. ** Type conversions and pointer invalidations might occur
  422. ** in the following cases:
  423. **
  424. ** <ul>
  425. ** <li><p>  The initial content is a BLOB and sqlite3_column_text() 
  426. **          or sqlite3_column_text16() is called.  A zero-terminator might
  427. **          need to be added to the string.</p></li>
  428. **
  429. ** <li><p>  The initial content is UTF-8 text and sqlite3_column_bytes16() or
  430. **          sqlite3_column_text16() is called.  The content must be converted
  431. **          to UTF-16.</p></li>
  432. **
  433. ** <li><p>  The initial content is UTF-16 text and sqlite3_column_bytes() or
  434. **          sqlite3_column_text() is called.  The content must be converted
  435. **          to UTF-8.</p></li>
  436. ** </ul>
  437. **
  438. ** Conversions between UTF-16be and UTF-16le are always done in place and do
  439. ** not invalidate a prior pointer, though of course the content of the buffer
  440. ** that the prior pointer points to will have been modified.  Other kinds
  441. ** of conversion are done in place when it is possible, but sometime it is
  442. ** not possible and in those cases prior pointers are invalidated.  
  443. **
  444. ** The safest and easiest to remember policy is to invoke these routines
  445. ** in one of the following ways:
  446. **
  447. **  <ul>
  448. **  <li>sqlite3_column_text() followed by sqlite3_column_bytes()</li>
  449. **  <li>sqlite3_column_blob() followed by sqlite3_column_bytes()</li>
  450. **  <li>sqlite3_column_text16() followed by sqlite3_column_bytes16()</li>
  451. **  </ul>
  452. **
  453. ** In other words, you should call sqlite3_column_text(), sqlite3_column_blob(),
  454. ** or sqlite3_column_text16() first to force the result into the desired
  455. ** format, then invoke sqlite3_column_bytes() or sqlite3_column_bytes16() to
  456. ** find the size of the result.  Do not mix call to sqlite3_column_text() or
  457. ** sqlite3_column_blob() with calls to sqlite3_column_bytes16().  And do not
  458. ** mix calls to sqlite3_column_text16() with calls to sqlite3_column_bytes().
  459. **
  460. ** The pointers returned are valid until a type conversion occurs as
  461. ** described above, or until [sqlite3_step()] or [sqlite3_reset()] or
  462. ** [sqlite3_finalize()] is called.  The memory space used to hold strings
  463. ** and blobs is freed automatically.  Do <b>not</b> pass the pointers returned
  464. ** [sqlite3_column_blob()], [sqlite3_column_text()], etc. into 
  465. ** [sqlite3_free()].
  466. **
  467. ** If a memory allocation error occurs during the evaluation of any
  468. ** of these routines, a default value is returned.  The default value
  469. ** is either the integer 0, the floating point number 0.0, or a NULL
  470. ** pointer.  Subsequent calls to [sqlite3_errcode()] will return
  471. ** [SQLITE_NOMEM].
  472. **
  473. ** INVARIANTS:
  474. **
  475. ** {F13803} The [sqlite3_column_blob(S,N)] interface converts the
  476. **          Nth column in the current row of the result set for
  477. **          [prepared statement] S into a blob and then returns a
  478. **          pointer to the converted value.
  479. **
  480. ** {F13806} The [sqlite3_column_bytes(S,N)] interface returns the
  481. **          number of bytes in the blob or string (exclusive of the
  482. **          zero terminator on the string) that was returned by the
  483. **          most recent call to [sqlite3_column_blob(S,N)] or
  484. **          [sqlite3_column_text(S,N)].
  485. **
  486. ** {F13809} The [sqlite3_column_bytes16(S,N)] interface returns the
  487. **          number of bytes in the string (exclusive of the
  488. **          zero terminator on the string) that was returned by the
  489. **          most recent call to [sqlite3_column_text16(S,N)].
  490. **
  491. ** {F13812} The [sqlite3_column_double(S,N)] interface converts the
  492. **          Nth column in the current row of the result set for
  493. **          [prepared statement] S into a floating point value and
  494. **          returns a copy of that value.
  495. **
  496. ** {F13815} The [sqlite3_column_int(S,N)] interface converts the
  497. **          Nth column in the current row of the result set for
  498. **          [prepared statement] S into a 64-bit signed integer and
  499. **          returns the lower 32 bits of that integer.
  500. **
  501. ** {F13818} The [sqlite3_column_int64(S,N)] interface converts the
  502. **          Nth column in the current row of the result set for
  503. **          [prepared statement] S into a 64-bit signed integer and
  504. **          returns a copy of that integer.
  505. **
  506. ** {F13821} The [sqlite3_column_text(S,N)] interface converts the
  507. **          Nth column in the current row of the result set for
  508. **          [prepared statement] S into a zero-terminated UTF-8 
  509. **          string and returns a pointer to that string.
  510. **
  511. ** {F13824} The [sqlite3_column_text16(S,N)] interface converts the
  512. **          Nth column in the current row of the result set for
  513. **          [prepared statement] S into a zero-terminated 2-byte
  514. **          aligned UTF-16 native byte order
  515. **          string and returns a pointer to that string.
  516. **
  517. ** {F13827} The [sqlite3_column_type(S,N)] interface returns
  518. **          one of [SQLITE_NULL], [SQLITE_INTEGER], [SQLITE_FLOAT],
  519. **          [SQLITE_TEXT], or [SQLITE_BLOB] as appropriate for
  520. **          the Nth column in the current row of the result set for
  521. **          [prepared statement] S.
  522. **
  523. ** {F13830} The [sqlite3_column_value(S,N)] interface returns a
  524. **          pointer to an [unprotected sqlite3_value] object for the
  525. **          Nth column in the current row of the result set for
  526. **          [prepared statement] S.
  527. */
  528. const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);
  529. int sqlite3_column_bytes(sqlite3_stmt*, int iCol);
  530. int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);
  531. double sqlite3_column_double(sqlite3_stmt*, int iCol);
  532. int sqlite3_column_int(sqlite3_stmt*, int iCol);
  533. sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol);
  534. const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);
  535. const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);
  536. int sqlite3_column_type(sqlite3_stmt*, int iCol);
  537. sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);
  538. /*
  539. ** CAPI3REF: Destroy A Prepared Statement Object {F13300}
  540. **
  541. ** The sqlite3_finalize() function is called to delete a 
  542. ** [prepared statement]. If the statement was
  543. ** executed successfully, or not executed at all, then SQLITE_OK is returned.
  544. ** If execution of the statement failed then an 
  545. ** [error code] or [extended error code]
  546. ** is returned. 
  547. **
  548. ** This routine can be called at any point during the execution of the
  549. ** [prepared statement].  If the virtual machine has not 
  550. ** completed execution when this routine is called, that is like
  551. ** encountering an error or an interrupt.  (See [sqlite3_interrupt()].) 
  552. ** Incomplete updates may be rolled back and transactions cancelled,  
  553. ** depending on the circumstances, and the 
  554. ** [error code] returned will be [SQLITE_ABORT].
  555. **
  556. ** INVARIANTS:
  557. **
  558. ** {F11302} The [sqlite3_finalize(S)] interface destroys the
  559. **          [prepared statement] S and releases all
  560. **          memory and file resources held by that object.
  561. **
  562. ** {F11304} If the most recent call to [sqlite3_step(S)] for the
  563. **          [prepared statement] S returned an error,
  564. **          then [sqlite3_finalize(S)] returns that same error.
  565. */
  566. int sqlite3_finalize(sqlite3_stmt *pStmt);
  567. /*
  568. ** CAPI3REF: Reset A Prepared Statement Object {F13330}
  569. **
  570. ** The sqlite3_reset() function is called to reset a 
  571. ** [prepared statement] object.
  572. ** back to its initial state, ready to be re-executed.
  573. ** Any SQL statement variables that had values bound to them using
  574. ** the [sqlite3_bind_blob | sqlite3_bind_*() API] retain their values.
  575. ** Use [sqlite3_clear_bindings()] to reset the bindings.
  576. **
  577. ** {F11332} The [sqlite3_reset(S)] interface resets the [prepared statement] S
  578. **          back to the beginning of its program.
  579. **
  580. ** {F11334} If the most recent call to [sqlite3_step(S)] for 
  581. **          [prepared statement] S returned [SQLITE_ROW] or [SQLITE_DONE],
  582. **          or if [sqlite3_step(S)] has never before been called on S,
  583. **          then [sqlite3_reset(S)] returns [SQLITE_OK].
  584. **
  585. ** {F11336} If the most recent call to [sqlite3_step(S)] for
  586. **          [prepared statement] S indicated an error, then
  587. **          [sqlite3_reset(S)] returns an appropriate [error code].
  588. **
  589. ** {F11338} The [sqlite3_reset(S)] interface does not change the values
  590. **          of any [sqlite3_bind_blob|bindings] on [prepared statement] S.
  591. */
  592. int sqlite3_reset(sqlite3_stmt *pStmt);
  593. /*
  594. ** CAPI3REF: Create Or Redefine SQL Functions {F16100}
  595. ** KEYWORDS: {function creation routines} 
  596. **
  597. ** These two functions (collectively known as
  598. ** "function creation routines") are used to add SQL functions or aggregates
  599. ** or to redefine the behavior of existing SQL functions or aggregates.  The
  600. ** difference only between the two is that the second parameter, the
  601. ** name of the (scalar) function or aggregate, is encoded in UTF-8 for
  602. ** sqlite3_create_function() and UTF-16 for sqlite3_create_function16().
  603. **
  604. ** The first parameter is the [database connection] to which the SQL
  605. ** function is to be added.  If a single
  606. ** program uses more than one [database connection] internally, then SQL
  607. ** functions must be added individually to each [database connection].
  608. **
  609. ** The second parameter is the name of the SQL function to be created
  610. ** or redefined.
  611. ** The length of the name is limited to 255 bytes, exclusive of the 
  612. ** zero-terminator.  Note that the name length limit is in bytes, not
  613. ** characters.  Any attempt to create a function with a longer name
  614. ** will result in an SQLITE_ERROR error.
  615. **
  616. ** The third parameter is the number of arguments that the SQL function or
  617. ** aggregate takes. If this parameter is negative, then the SQL function or
  618. ** aggregate may take any number of arguments.
  619. **
  620. ** The fourth parameter, eTextRep, specifies what 
  621. ** [SQLITE_UTF8 | text encoding] this SQL function prefers for
  622. ** its parameters.  Any SQL function implementation should be able to work
  623. ** work with UTF-8, UTF-16le, or UTF-16be.  But some implementations may be
  624. ** more efficient with one encoding than another.  It is allowed to
  625. ** invoke sqlite3_create_function() or sqlite3_create_function16() multiple
  626. ** times with the same function but with different values of eTextRep.
  627. ** When multiple implementations of the same function are available, SQLite
  628. ** will pick the one that involves the least amount of data conversion.
  629. ** If there is only a single implementation which does not care what
  630. ** text encoding is used, then the fourth argument should be
  631. ** [SQLITE_ANY].
  632. **
  633. ** The fifth parameter is an arbitrary pointer.  The implementation
  634. ** of the function can gain access to this pointer using
  635. ** [sqlite3_user_data()].
  636. **
  637. ** The seventh, eighth and ninth parameters, xFunc, xStep and xFinal, are
  638. ** pointers to C-language functions that implement the SQL
  639. ** function or aggregate. A scalar SQL function requires an implementation of
  640. ** the xFunc callback only, NULL pointers should be passed as the xStep
  641. ** and xFinal parameters. An aggregate SQL function requires an implementation
  642. ** of xStep and xFinal and NULL should be passed for xFunc. To delete an
  643. ** existing SQL function or aggregate, pass NULL for all three function
  644. ** callback.
  645. **
  646. ** It is permitted to register multiple implementations of the same
  647. ** functions with the same name but with either differing numbers of
  648. ** arguments or differing perferred text encodings.  SQLite will use
  649. ** the implementation most closely matches the way in which the
  650. ** SQL function is used.
  651. **
  652. ** INVARIANTS:
  653. **
  654. ** {F16103} The [sqlite3_create_function16()] interface behaves exactly
  655. **          like [sqlite3_create_function()] in every way except that it
  656. **          interprets the zFunctionName argument as
  657. **          zero-terminated UTF-16 native byte order instead of as a
  658. **          zero-terminated UTF-8.
  659. **
  660. ** {F16106} A successful invocation of
  661. **          the [sqlite3_create_function(D,X,N,E,...)] interface registers
  662. **          or replaces callback functions in [database connection] D
  663. **          used to implement the SQL function named X with N parameters
  664. **          and having a perferred text encoding of E.
  665. **
  666. ** {F16109} A successful call to [sqlite3_create_function(D,X,N,E,P,F,S,L)]
  667. **          replaces the P, F, S, and L values from any prior calls with
  668. **          the same D, X, N, and E values.
  669. **
  670. ** {F16112} The [sqlite3_create_function(D,X,...)] interface fails with
  671. **          a return code of [SQLITE_ERROR] if the SQL function name X is
  672. **          longer than 255 bytes exclusive of the zero terminator.
  673. **
  674. ** {F16118} Either F must be NULL and S and L are non-NULL or else F
  675. **          is non-NULL and S and L are NULL, otherwise
  676. **          [sqlite3_create_function(D,X,N,E,P,F,S,L)] returns [SQLITE_ERROR].
  677. **
  678. ** {F16121} The [sqlite3_create_function(D,...)] interface fails with an
  679. **          error code of [SQLITE_BUSY] if there exist [prepared statements]
  680. **          associated with the [database connection] D.
  681. **
  682. ** {F16124} The [sqlite3_create_function(D,X,N,...)] interface fails with an
  683. **          error code of [SQLITE_ERROR] if parameter N (specifying the number
  684. **          of arguments to the SQL function being registered) is less
  685. **          than -1 or greater than 127.
  686. **
  687. ** {F16127} When N is non-negative, the [sqlite3_create_function(D,X,N,...)]
  688. **          interface causes callbacks to be invoked for the SQL function
  689. **          named X when the number of arguments to the SQL function is
  690. **          exactly N.
  691. **
  692. ** {F16130} When N is -1, the [sqlite3_create_function(D,X,N,...)]
  693. **          interface causes callbacks to be invoked for the SQL function
  694. **          named X with any number of arguments.
  695. **
  696. ** {F16133} When calls to [sqlite3_create_function(D,X,N,...)]
  697. **          specify multiple implementations of the same function X
  698. **          and when one implementation has N>=0 and the other has N=(-1)
  699. **          the implementation with a non-zero N is preferred.
  700. **
  701. ** {F16136} When calls to [sqlite3_create_function(D,X,N,E,...)]
  702. **          specify multiple implementations of the same function X with
  703. **          the same number of arguments N but with different
  704. **          encodings E, then the implementation where E matches the
  705. **          database encoding is preferred.
  706. **
  707. ** {F16139} For an aggregate SQL function created using
  708. **          [sqlite3_create_function(D,X,N,E,P,0,S,L)] the finializer
  709. **          function L will always be invoked exactly once if the
  710. **          step function S is called one or more times.
  711. **
  712. ** {F16142} When SQLite invokes either the xFunc or xStep function of
  713. **          an application-defined SQL function or aggregate created
  714. **          by [sqlite3_create_function()] or [sqlite3_create_function16()],
  715. **          then the array of [sqlite3_value] objects passed as the
  716. **          third parameter are always [protected sqlite3_value] objects.
  717. */
  718. int sqlite3_create_function(
  719.   sqlite3 *db,
  720.   const char *zFunctionName,
  721.   int nArg,
  722.   int eTextRep,
  723.   void *pApp,
  724.   void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
  725.   void (*xStep)(sqlite3_context*,int,sqlite3_value**),
  726.   void (*xFinal)(sqlite3_context*)
  727. );
  728. int sqlite3_create_function16(
  729.   sqlite3 *db,
  730.   const void *zFunctionName,
  731.   int nArg,
  732.   int eTextRep,
  733.   void *pApp,
  734.   void (*xFunc)(sqlite3_context*,int,sqlite3_value**),
  735.   void (*xStep)(sqlite3_context*,int,sqlite3_value**),
  736.   void (*xFinal)(sqlite3_context*)
  737. );
  738. /*
  739. ** CAPI3REF: Text Encodings {F10267}
  740. **
  741. ** These constant define integer codes that represent the various
  742. ** text encodings supported by SQLite.
  743. */
  744. #define SQLITE_UTF8           1
  745. #define SQLITE_UTF16LE        2
  746. #define SQLITE_UTF16BE        3
  747. #define SQLITE_UTF16          4    /* Use native byte order */
  748. #define SQLITE_ANY            5    /* sqlite3_create_function only */
  749. #define SQLITE_UTF16_ALIGNED  8    /* sqlite3_create_collation only */
  750. /*
  751. ** CAPI3REF: Obsolete Functions
  752. **
  753. ** These functions are all now obsolete.  In order to maintain
  754. ** backwards compatibility with older code, we continue to support
  755. ** these functions.  However, new development projects should avoid
  756. ** the use of these functions.  To help encourage people to avoid
  757. ** using these functions, we are not going to tell you want they do.
  758. */
  759. int sqlite3_aggregate_count(sqlite3_context*);
  760. int sqlite3_expired(sqlite3_stmt*);
  761. int sqlite3_transfer_bindings(sqlite3_stmt*, sqlite3_stmt*);
  762. int sqlite3_global_recover(void);
  763. void sqlite3_thread_cleanup(void);
  764. int sqlite3_memory_alarm(void(*)(void*,sqlite3_int64,int),void*,sqlite3_int64);
  765. /*
  766. ** CAPI3REF: Obtaining SQL Function Parameter Values {F15100}
  767. **
  768. ** The C-language implementation of SQL functions and aggregates uses
  769. ** this set of interface routines to access the parameter values on
  770. ** the function or aggregate.
  771. **
  772. ** The xFunc (for scalar functions) or xStep (for aggregates) parameters
  773. ** to [sqlite3_create_function()] and [sqlite3_create_function16()]
  774. ** define callbacks that implement the SQL functions and aggregates.
  775. ** The 4th parameter to these callbacks is an array of pointers to
  776. ** [protected sqlite3_value] objects.  There is one [sqlite3_value] object for
  777. ** each parameter to the SQL function.  These routines are used to
  778. ** extract values from the [sqlite3_value] objects.
  779. **
  780. ** These routines work only with [protected sqlite3_value] objects.
  781. ** Any attempt to use these routines on an [unprotected sqlite3_value]
  782. ** object results in undefined behavior.
  783. **
  784. ** These routines work just like the corresponding 
  785. ** [sqlite3_column_blob | sqlite3_column_* routines] except that 
  786. ** these routines take a single [protected sqlite3_value] object pointer
  787. ** instead of an [sqlite3_stmt*] pointer and an integer column number.
  788. **
  789. ** The sqlite3_value_text16() interface extracts a UTF16 string
  790. ** in the native byte-order of the host machine.  The
  791. ** sqlite3_value_text16be() and sqlite3_value_text16le() interfaces
  792. ** extract UTF16 strings as big-endian and little-endian respectively.
  793. **
  794. ** The sqlite3_value_numeric_type() interface attempts to apply
  795. ** numeric affinity to the value.  This means that an attempt is
  796. ** made to convert the value to an integer or floating point.  If
  797. ** such a conversion is possible without loss of information (in other
  798. ** words if the value is a string that looks like a number)
  799. ** then the conversion is done.  Otherwise no conversion occurs.  The 
  800. ** [SQLITE_INTEGER | datatype] after conversion is returned.
  801. **
  802. ** Please pay particular attention to the fact that the pointer that
  803. ** is returned from [sqlite3_value_blob()], [sqlite3_value_text()], or
  804. ** [sqlite3_value_text16()] can be invalidated by a subsequent call to
  805. ** [sqlite3_value_bytes()], [sqlite3_value_bytes16()], [sqlite3_value_text()],
  806. ** or [sqlite3_value_text16()].  
  807. **
  808. ** These routines must be called from the same thread as
  809. ** the SQL function that supplied the [sqlite3_value*] parameters.
  810. **
  811. **
  812. ** INVARIANTS:
  813. **
  814. ** {F15103} The [sqlite3_value_blob(V)] interface converts the
  815. **          [protected sqlite3_value] object V into a blob and then returns a
  816. **          pointer to the converted value.
  817. **
  818. ** {F15106} The [sqlite3_value_bytes(V)] interface returns the
  819. **          number of bytes in the blob or string (exclusive of the
  820. **          zero terminator on the string) that was returned by the
  821. **          most recent call to [sqlite3_value_blob(V)] or
  822. **          [sqlite3_value_text(V)].
  823. **
  824. ** {F15109} The [sqlite3_value_bytes16(V)] interface returns the
  825. **          number of bytes in the string (exclusive of the
  826. **          zero terminator on the string) that was returned by the
  827. **          most recent call to [sqlite3_value_text16(V)],
  828. **          [sqlite3_value_text16be(V)], or [sqlite3_value_text16le(V)].
  829. **
  830. ** {F15112} The [sqlite3_value_double(V)] interface converts the
  831. **          [protected sqlite3_value] object V into a floating point value and
  832. **          returns a copy of that value.
  833. **
  834. ** {F15115} The [sqlite3_value_int(V)] interface converts the
  835. **          [protected sqlite3_value] object V into a 64-bit signed integer and
  836. **          returns the lower 32 bits of that integer.
  837. **
  838. ** {F15118} The [sqlite3_value_int64(V)] interface converts the
  839. **          [protected sqlite3_value] object V into a 64-bit signed integer and
  840. **          returns a copy of that integer.
  841. **
  842. ** {F15121} The [sqlite3_value_text(V)] interface converts the
  843. **          [protected sqlite3_value] object V into a zero-terminated UTF-8 
  844. **          string and returns a pointer to that string.
  845. **
  846. ** {F15124} The [sqlite3_value_text16(V)] interface converts the
  847. **          [protected sqlite3_value] object V into a zero-terminated 2-byte
  848. **          aligned UTF-16 native byte order
  849. **          string and returns a pointer to that string.
  850. **
  851. ** {F15127} The [sqlite3_value_text16be(V)] interface converts the
  852. **          [protected sqlite3_value] object V into a zero-terminated 2-byte
  853. **          aligned UTF-16 big-endian
  854. **          string and returns a pointer to that string.
  855. **
  856. ** {F15130} The [sqlite3_value_text16le(V)] interface converts the
  857. **          [protected sqlite3_value] object V into a zero-terminated 2-byte
  858. **          aligned UTF-16 little-endian
  859. **          string and returns a pointer to that string.
  860. **
  861. ** {F15133} The [sqlite3_value_type(V)] interface returns
  862. **          one of [SQLITE_NULL], [SQLITE_INTEGER], [SQLITE_FLOAT],
  863. **          [SQLITE_TEXT], or [SQLITE_BLOB] as appropriate for
  864. **          the [sqlite3_value] object V.
  865. **
  866. ** {F15136} The [sqlite3_value_numeric_type(V)] interface converts
  867. **          the [protected sqlite3_value] object V into either an integer or
  868. **          a floating point value if it can do so without loss of
  869. **          information, and returns one of [SQLITE_NULL],
  870. **          [SQLITE_INTEGER], [SQLITE_FLOAT], [SQLITE_TEXT], or
  871. **          [SQLITE_BLOB] as appropriate for
  872. **          the [protected sqlite3_value] object V after the conversion attempt.
  873. */
  874. const void *sqlite3_value_blob(sqlite3_value*);
  875. int sqlite3_value_bytes(sqlite3_value*);
  876. int sqlite3_value_bytes16(sqlite3_value*);
  877. double sqlite3_value_double(sqlite3_value*);
  878. int sqlite3_value_int(sqlite3_value*);
  879. sqlite3_int64 sqlite3_value_int64(sqlite3_value*);
  880. const unsigned char *sqlite3_value_text(sqlite3_value*);
  881. const void *sqlite3_value_text16(sqlite3_value*);
  882. const void *sqlite3_value_text16le(sqlite3_value*);
  883. const void *sqlite3_value_text16be(sqlite3_value*);
  884. int sqlite3_value_type(sqlite3_value*);
  885. int sqlite3_value_numeric_type(sqlite3_value*);
  886. /*
  887. ** CAPI3REF: Obtain Aggregate Function Context {F16210}
  888. **
  889. ** The implementation of aggregate SQL functions use this routine to allocate
  890. ** a structure for storing their state.  
  891. ** The first time the sqlite3_aggregate_context() routine is
  892. ** is called for a particular aggregate, SQLite allocates nBytes of memory
  893. ** zeros that memory, and returns a pointer to it.
  894. ** On second and subsequent calls to sqlite3_aggregate_context()
  895. ** for the same aggregate function index, the same buffer is returned.
  896. ** The implementation
  897. ** of the aggregate can use the returned buffer to accumulate data.
  898. **
  899. ** SQLite automatically frees the allocated buffer when the aggregate
  900. ** query concludes.
  901. **
  902. ** The first parameter should be a copy of the 
  903. ** [sqlite3_context | SQL function context] that is the first
  904. ** parameter to the callback routine that implements the aggregate
  905. ** function.
  906. **
  907. ** This routine must be called from the same thread in which
  908. ** the aggregate SQL function is running.
  909. **
  910. ** INVARIANTS:
  911. **
  912. ** {F16211} The first invocation of [sqlite3_aggregate_context(C,N)] for
  913. **          a particular instance of an aggregate function (for a particular
  914. **          context C) causes SQLite to allocation N bytes of memory,
  915. **          zero that memory, and return a pointer to the allocationed
  916. **          memory.
  917. **
  918. ** {F16213} If a memory allocation error occurs during
  919. **          [sqlite3_aggregate_context(C,N)] then the function returns 0.
  920. **
  921. ** {F16215} Second and subsequent invocations of
  922. **          [sqlite3_aggregate_context(C,N)] for the same context pointer C
  923. **          ignore the N parameter and return a pointer to the same
  924. **          block of memory returned by the first invocation.
  925. **
  926. ** {F16217} The memory allocated by [sqlite3_aggregate_context(C,N)] is
  927. **          automatically freed on the next call to [sqlite3_reset()]
  928. **          or [sqlite3_finalize()] for the [prepared statement] containing
  929. **          the aggregate function associated with context C.
  930. */
  931. void *sqlite3_aggregate_context(sqlite3_context*, int nBytes);
  932. /*
  933. ** CAPI3REF: User Data For Functions {F16240}
  934. **
  935. ** The sqlite3_user_data() interface returns a copy of
  936. ** the pointer that was the pUserData parameter (the 5th parameter)
  937. ** of the the [sqlite3_create_function()]
  938. ** and [sqlite3_create_function16()] routines that originally
  939. ** registered the application defined function. {END}
  940. **
  941. ** This routine must be called from the same thread in which
  942. ** the application-defined function is running.
  943. **
  944. ** INVARIANTS:
  945. **
  946. ** {F16243} The [sqlite3_user_data(C)] interface returns a copy of the
  947. **          P pointer from the [sqlite3_create_function(D,X,N,E,P,F,S,L)]
  948. **          or [sqlite3_create_function16(D,X,N,E,P,F,S,L)] call that
  949. **          registered the SQL function associated with 
  950. **          [sqlite3_context] C.
  951. */
  952. void *sqlite3_user_data(sqlite3_context*);
  953. /*
  954. ** CAPI3REF: Database Connection For Functions {F16250}
  955. **
  956. ** The sqlite3_context_db_handle() interface returns a copy of
  957. ** the pointer to the [database connection] (the 1st parameter)
  958. ** of the the [sqlite3_create_function()]
  959. ** and [sqlite3_create_function16()] routines that originally
  960. ** registered the application defined function.
  961. **
  962. ** INVARIANTS:
  963. **
  964. ** {F16253} The [sqlite3_context_db_handle(C)] interface returns a copy of the
  965. **          D pointer from the [sqlite3_create_function(D,X,N,E,P,F,S,L)]
  966. **          or [sqlite3_create_function16(D,X,N,E,P,F,S,L)] call that
  967. **          registered the SQL function associated with 
  968. **          [sqlite3_context] C.
  969. */
  970. sqlite3 *sqlite3_context_db_handle(sqlite3_context*);
  971. /*
  972. ** CAPI3REF: Function Auxiliary Data {F16270}
  973. **
  974. ** The following two functions may be used by scalar SQL functions to
  975. ** associate meta-data with argument values. If the same value is passed to
  976. ** multiple invocations of the same SQL function during query execution, under
  977. ** some circumstances the associated meta-data may be preserved. This may
  978. ** be used, for example, to add a regular-expression matching scalar
  979. ** function. The compiled version of the regular expression is stored as
  980. ** meta-data associated with the SQL value passed as the regular expression
  981. ** pattern.  The compiled regular expression can be reused on multiple
  982. ** invocations of the same function so that the original pattern string
  983. ** does not need to be recompiled on each invocation.
  984. **
  985. ** The sqlite3_get_auxdata() interface returns a pointer to the meta-data
  986. ** associated by the sqlite3_set_auxdata() function with the Nth argument
  987. ** value to the application-defined function.
  988. ** If no meta-data has been ever been set for the Nth
  989. ** argument of the function, or if the cooresponding function parameter
  990. ** has changed since the meta-data was set, then sqlite3_get_auxdata()
  991. ** returns a NULL pointer.
  992. **
  993. ** The sqlite3_set_auxdata() interface saves the meta-data
  994. ** pointed to by its 3rd parameter as the meta-data for the N-th
  995. ** argument of the application-defined function.  Subsequent
  996. ** calls to sqlite3_get_auxdata() might return this data, if it has
  997. ** not been destroyed. 
  998. ** If it is not NULL, SQLite will invoke the destructor 
  999. ** function given by the 4th parameter to sqlite3_set_auxdata() on
  1000. ** the meta-data when the corresponding function parameter changes
  1001. ** or when the SQL statement completes, whichever comes first.
  1002. **
  1003. ** SQLite is free to call the destructor and drop meta-data on
  1004. ** any parameter of any function at any time.  The only guarantee
  1005. ** is that the destructor will be called before the metadata is
  1006. ** dropped.
  1007. **
  1008. ** In practice, meta-data is preserved between function calls for
  1009. ** expressions that are constant at compile time. This includes literal
  1010. ** values and SQL variables.
  1011. **
  1012. ** These routines must be called from the same thread in which
  1013. ** the SQL function is running.
  1014. **
  1015. ** INVARIANTS:
  1016. **
  1017. ** {F16272} The [sqlite3_get_auxdata(C,N)] interface returns a pointer
  1018. **          to metadata associated with the Nth parameter of the SQL function
  1019. **          whose context is C, or NULL if there is no metadata associated
  1020. **          with that parameter.
  1021. **
  1022. ** {F16274} The [sqlite3_set_auxdata(C,N,P,D)] interface assigns a metadata
  1023. **          pointer P to the Nth parameter of the SQL function with context
  1024. **          C.
  1025. **
  1026. ** {F16276} SQLite will invoke the destructor D with a single argument
  1027. **          which is the metadata pointer P following a call to
  1028. **          [sqlite3_set_auxdata(C,N,P,D)] when SQLite ceases to hold
  1029. **          the metadata.
  1030. **
  1031. ** {F16277} SQLite ceases to hold metadata for an SQL function parameter
  1032. **          when the value of that parameter changes.
  1033. **
  1034. ** {F16278} When [sqlite3_set_auxdata(C,N,P,D)] is invoked, the destructor
  1035. **          is called for any prior metadata associated with the same function
  1036. **          context C and parameter N.
  1037. **
  1038. ** {F16279} SQLite will call destructors for any metadata it is holding
  1039. **          in a particular [prepared statement] S when either
  1040. **          [sqlite3_reset(S)] or [sqlite3_finalize(S)] is called.
  1041. */
  1042. void *sqlite3_get_auxdata(sqlite3_context*, int N);
  1043. void sqlite3_set_auxdata(sqlite3_context*, int N, void*, void (*)(void*));
  1044. /*
  1045. ** CAPI3REF: Constants Defining Special Destructor Behavior {F10280}
  1046. **
  1047. ** These are special value for the destructor that is passed in as the
  1048. ** final argument to routines like [sqlite3_result_blob()].  If the destructor
  1049. ** argument is SQLITE_STATIC, it means that the content pointer is constant
  1050. ** and will never change.  It does not need to be destroyed.  The 
  1051. ** SQLITE_TRANSIENT value means that the content will likely change in
  1052. ** the near future and that SQLite should make its own private copy of
  1053. ** the content before returning.
  1054. **
  1055. ** The typedef is necessary to work around problems in certain
  1056. ** C++ compilers.  See ticket #2191.
  1057. */
  1058. typedef void (*sqlite3_destructor_type)(void*);
  1059. #define SQLITE_STATIC      ((sqlite3_destructor_type)0)
  1060. #define SQLITE_TRANSIENT   ((sqlite3_destructor_type)-1)
  1061. /*
  1062. ** CAPI3REF: Setting The Result Of An SQL Function {F16400}
  1063. **
  1064. ** These routines are used by the xFunc or xFinal callbacks that
  1065. ** implement SQL functions and aggregates.  See
  1066. ** [sqlite3_create_function()] and [sqlite3_create_function16()]
  1067. ** for additional information.
  1068. **
  1069. ** These functions work very much like the 
  1070. ** [sqlite3_bind_blob | sqlite3_bind_*] family of functions used
  1071. ** to bind values to host parameters in prepared statements.
  1072. ** Refer to the
  1073. ** [sqlite3_bind_blob | sqlite3_bind_* documentation] for
  1074. ** additional information.
  1075. **
  1076. ** The sqlite3_result_blob() interface sets the result from
  1077. ** an application defined function to be the BLOB whose content is pointed
  1078. ** to by the second parameter and which is N bytes long where N is the
  1079. ** third parameter. 
  1080. ** The sqlite3_result_zeroblob() inerfaces set the result of
  1081. ** the application defined function to be a BLOB containing all zero
  1082. ** bytes and N bytes in size, where N is the value of the 2nd parameter.
  1083. **
  1084. ** The sqlite3_result_double() interface sets the result from
  1085. ** an application defined function to be a floating point value specified
  1086. ** by its 2nd argument.
  1087. **
  1088. ** The sqlite3_result_error() and sqlite3_result_error16() functions
  1089. ** cause the implemented SQL function to throw an exception.
  1090. ** SQLite uses the string pointed to by the
  1091. ** 2nd parameter of sqlite3_result_error() or sqlite3_result_error16()
  1092. ** as the text of an error message.  SQLite interprets the error
  1093. ** message string from sqlite3_result_error() as UTF8. SQLite
  1094. ** interprets the string from sqlite3_result_error16() as UTF16 in native
  1095. ** byte order.  If the third parameter to sqlite3_result_error()
  1096. ** or sqlite3_result_error16() is negative then SQLite takes as the error
  1097. ** message all text up through the first zero character.
  1098. ** If the third parameter to sqlite3_result_error() or
  1099. ** sqlite3_result_error16() is non-negative then SQLite takes that many
  1100. ** bytes (not characters) from the 2nd parameter as the error message.
  1101. ** The sqlite3_result_error() and sqlite3_result_error16()
  1102. ** routines make a copy private copy of the error message text before
  1103. ** they return.  Hence, the calling function can deallocate or
  1104. ** modify the text after they return without harm.
  1105. ** The sqlite3_result_error_code() function changes the error code
  1106. ** returned by SQLite as a result of an error in a function.  By default,
  1107. ** the error code is SQLITE_ERROR.  A subsequent call to sqlite3_result_error()
  1108. ** or sqlite3_result_error16() resets the error code to SQLITE_ERROR.
  1109. **
  1110. ** The sqlite3_result_toobig() interface causes SQLite
  1111. ** to throw an error indicating that a string or BLOB is to long
  1112. ** to represent.  The sqlite3_result_nomem() interface
  1113. ** causes SQLite to throw an exception indicating that the a
  1114. ** memory allocation failed.
  1115. **
  1116. ** The sqlite3_result_int() interface sets the return value
  1117. ** of the application-defined function to be the 32-bit signed integer
  1118. ** value given in the 2nd argument.
  1119. ** The sqlite3_result_int64() interface sets the return value
  1120. ** of the application-defined function to be the 64-bit signed integer
  1121. ** value given in the 2nd argument.
  1122. **
  1123. ** The sqlite3_result_null() interface sets the return value
  1124. ** of the application-defined function to be NULL.
  1125. **
  1126. ** The sqlite3_result_text(), sqlite3_result_text16(), 
  1127. ** sqlite3_result_text16le(), and sqlite3_result_text16be() interfaces
  1128. ** set the return value of the application-defined function to be
  1129. ** a text string which is represented as UTF-8, UTF-16 native byte order,
  1130. ** UTF-16 little endian, or UTF-16 big endian, respectively.
  1131. ** SQLite takes the text result from the application from
  1132. ** the 2nd parameter of the sqlite3_result_text* interfaces.
  1133. ** If the 3rd parameter to the sqlite3_result_text* interfaces
  1134. ** is negative, then SQLite takes result text from the 2nd parameter 
  1135. ** through the first zero character.
  1136. ** If the 3rd parameter to the sqlite3_result_text* interfaces
  1137. ** is non-negative, then as many bytes (not characters) of the text
  1138. ** pointed to by the 2nd parameter are taken as the application-defined
  1139. ** function result.
  1140. ** If the 4th parameter to the sqlite3_result_text* interfaces
  1141. ** or sqlite3_result_blob is a non-NULL pointer, then SQLite calls that
  1142. ** function as the destructor on the text or blob result when it has
  1143. ** finished using that result.
  1144. ** If the 4th parameter to the sqlite3_result_text* interfaces
  1145. ** or sqlite3_result_blob is the special constant SQLITE_STATIC, then
  1146. ** SQLite assumes that the text or blob result is constant space and
  1147. ** does not copy the space or call a destructor when it has
  1148. ** finished using that result.
  1149. ** If the 4th parameter to the sqlite3_result_text* interfaces
  1150. ** or sqlite3_result_blob is the special constant SQLITE_TRANSIENT
  1151. ** then SQLite makes a copy of the result into space obtained from
  1152. ** from [sqlite3_malloc()] before it returns.
  1153. **
  1154. ** The sqlite3_result_value() interface sets the result of
  1155. ** the application-defined function to be a copy the
  1156. ** [unprotected sqlite3_value] object specified by the 2nd parameter.  The
  1157. ** sqlite3_result_value() interface makes a copy of the [sqlite3_value]
  1158. ** so that [sqlite3_value] specified in the parameter may change or
  1159. ** be deallocated after sqlite3_result_value() returns without harm.
  1160. ** A [protected sqlite3_value] object may always be used where an
  1161. ** [unprotected sqlite3_value] object is required, so either
  1162. ** kind of [sqlite3_value] object can be used with this interface.
  1163. **
  1164. ** If these routines are called from within the different thread 
  1165. ** than the one containing the application-defined function that recieved
  1166. ** the [sqlite3_context] pointer, the results are undefined.
  1167. **
  1168. ** INVARIANTS:
  1169. **
  1170. ** {F16403} The default return value from any SQL function is NULL.
  1171. **
  1172. ** {F16406} The [sqlite3_result_blob(C,V,N,D)] interface changes the
  1173. **          return value of function C to be a blob that is N bytes
  1174. **          in length and with content pointed to by V.
  1175. **
  1176. ** {F16409} The [sqlite3_result_double(C,V)] interface changes the
  1177. **          return value of function C to be the floating point value V.
  1178. **
  1179. ** {F16412} The [sqlite3_result_error(C,V,N)] interface changes the return
  1180. **          value of function C to be an exception with error code
  1181. **          [SQLITE_ERROR] and a UTF8 error message copied from V up to the
  1182. **          first zero byte or until N bytes are read if N is positive.
  1183. **
  1184. ** {F16415} The [sqlite3_result_error16(C,V,N)] interface changes the return
  1185. **          value of function C to be an exception with error code
  1186. **          [SQLITE_ERROR] and a UTF16 native byte order error message
  1187. **          copied from V up to the first zero terminator or until N bytes
  1188. **          are read if N is positive.
  1189. **
  1190. ** {F16418} The [sqlite3_result_error_toobig(C)] interface changes the return
  1191. **          value of the function C to be an exception with error code
  1192. **          [SQLITE_TOOBIG] and an appropriate error message.
  1193. **
  1194. ** {F16421} The [sqlite3_result_error_nomem(C)] interface changes the return
  1195. **          value of the function C to be an exception with error code
  1196. **          [SQLITE_NOMEM] and an appropriate error message.
  1197. **
  1198. ** {F16424} The [sqlite3_result_error_code(C,E)] interface changes the return
  1199. **          value of the function C to be an exception with error code E.
  1200. **          The error message text is unchanged.
  1201. **
  1202. ** {F16427} The [sqlite3_result_int(C,V)] interface changes the
  1203. **          return value of function C to be the 32-bit integer value V.
  1204. **
  1205. ** {F16430} The [sqlite3_result_int64(C,V)] interface changes the
  1206. **          return value of function C to be the 64-bit integer value V.
  1207. **
  1208. ** {F16433} The [sqlite3_result_null(C)] interface changes the
  1209. **          return value of function C to be NULL.
  1210. **
  1211. ** {F16436} The [sqlite3_result_text(C,V,N,D)] interface changes the
  1212. **          return value of function C to be the UTF8 string
  1213. **          V up the first zero if N is negative
  1214. **          or the first N bytes of V if N is non-negative.
  1215. **
  1216. ** {F16439} The [sqlite3_result_text16(C,V,N,D)] interface changes the
  1217. **          return value of function C to be the UTF16 native byte order
  1218. **          string V up to the first zero if N is
  1219. **          negative or the first N bytes of V if N is non-negative.
  1220. **
  1221. ** {F16442} The [sqlite3_result_text16be(C,V,N,D)] interface changes the
  1222. **          return value of function C to be the UTF16 big-endian
  1223. **          string V up to the first zero if N is
  1224. **          is negative or the first N bytes or V if N is non-negative.
  1225. **
  1226. ** {F16445} The [sqlite3_result_text16le(C,V,N,D)] interface changes the
  1227. **          return value of function C to be the UTF16 little-endian
  1228. **          string V up to the first zero if N is
  1229. **          negative or the first N bytes of V if N is non-negative.
  1230. **
  1231. ** {F16448} The [sqlite3_result_value(C,V)] interface changes the
  1232. **          return value of function C to be [unprotected sqlite3_value]
  1233. **          object V.
  1234. **
  1235. ** {F16451} The [sqlite3_result_zeroblob(C,N)] interface changes the
  1236. **          return value of function C to be an N-byte blob of all zeros.
  1237. **
  1238. ** {F16454} The [sqlite3_result_error()] and [sqlite3_result_error16()]
  1239. **          interfaces make a copy of their error message strings before
  1240. **          returning.
  1241. **
  1242. ** {F16457} If the D destructor parameter to [sqlite3_result_blob(C,V,N,D)],
  1243. **          [sqlite3_result_text(C,V,N,D)], [sqlite3_result_text16(C,V,N,D)],
  1244. **          [sqlite3_result_text16be(C,V,N,D)], or
  1245. **          [sqlite3_result_text16le(C,V,N,D)] is the constant [SQLITE_STATIC]
  1246. **          then no destructor is ever called on the pointer V and SQLite
  1247. **          assumes that V is immutable.
  1248. **
  1249. ** {F16460} If the D destructor parameter to [sqlite3_result_blob(C,V,N,D)],
  1250. **          [sqlite3_result_text(C,V,N,D)], [sqlite3_result_text16(C,V,N,D)],
  1251. **          [sqlite3_result_text16be(C,V,N,D)], or
  1252. **          [sqlite3_result_text16le(C,V,N,D)] is the constant
  1253. **          [SQLITE_TRANSIENT] then the interfaces makes a copy of the
  1254. **          content of V and retains the copy.
  1255. **
  1256. ** {F16463} If the D destructor parameter to [sqlite3_result_blob(C,V,N,D)],
  1257. **          [sqlite3_result_text(C,V,N,D)], [sqlite3_result_text16(C,V,N,D)],
  1258. **          [sqlite3_result_text16be(C,V,N,D)], or
  1259. **          [sqlite3_result_text16le(C,V,N,D)] is some value other than
  1260. **          the constants [SQLITE_STATIC] and [SQLITE_TRANSIENT] then 
  1261. **          SQLite will invoke the destructor D with V as its only argument
  1262. **          when it has finished with the V value.
  1263. */
  1264. void sqlite3_result_blob(sqlite3_context*, const void*, int, void(*)(void*));
  1265. void sqlite3_result_double(sqlite3_context*, double);
  1266. void sqlite3_result_error(sqlite3_context*, const char*, int);
  1267. void sqlite3_result_error16(sqlite3_context*, const void*, int);
  1268. void sqlite3_result_error_toobig(sqlite3_context*);
  1269. void sqlite3_result_error_nomem(sqlite3_context*);
  1270. void sqlite3_result_error_code(sqlite3_context*, int);
  1271. void sqlite3_result_int(sqlite3_context*, int);
  1272. void sqlite3_result_int64(sqlite3_context*, sqlite3_int64);
  1273. void sqlite3_result_null(sqlite3_context*);
  1274. void sqlite3_result_text(sqlite3_context*, const char*, int, void(*)(void*));
  1275. void sqlite3_result_text16(sqlite3_context*, const void*, int, void(*)(void*));
  1276. void sqlite3_result_text16le(sqlite3_context*, const void*, int,void(*)(void*));
  1277. void sqlite3_result_text16be(sqlite3_context*, const void*, int,void(*)(void*));
  1278. void sqlite3_result_value(sqlite3_context*, sqlite3_value*);
  1279. void sqlite3_result_zeroblob(sqlite3_context*, int n);
  1280. /*
  1281. ** CAPI3REF: Define New Collating Sequences {F16600}
  1282. **
  1283. ** These functions are used to add new collation sequences to the
  1284. ** [sqlite3*] handle specified as the first argument. 
  1285. **
  1286. ** The name of the new collation sequence is specified as a UTF-8 string
  1287. ** for sqlite3_create_collation() and sqlite3_create_collation_v2()
  1288. ** and a UTF-16 string for sqlite3_create_collation16(). In all cases
  1289. ** the name is passed as the second function argument.
  1290. **
  1291. ** The third argument may be one of the constants [SQLITE_UTF8],
  1292. ** [SQLITE_UTF16LE] or [SQLITE_UTF16BE], indicating that the user-supplied
  1293. ** routine expects to be passed pointers to strings encoded using UTF-8,
  1294. ** UTF-16 little-endian or UTF-16 big-endian respectively. The
  1295. ** third argument might also be [SQLITE_UTF16_ALIGNED] to indicate that
  1296. ** the routine expects pointers to 16-bit word aligned strings
  1297. ** of UTF16 in the native byte order of the host computer.
  1298. **
  1299. ** A pointer to the user supplied routine must be passed as the fifth
  1300. ** argument.  If it is NULL, this is the same as deleting the collation
  1301. ** sequence (so that SQLite cannot call it anymore).
  1302. ** Each time the application
  1303. ** supplied function is invoked, it is passed a copy of the void* passed as
  1304. ** the fourth argument to sqlite3_create_collation() or
  1305. ** sqlite3_create_collation16() as its first parameter.
  1306. **
  1307. ** The remaining arguments to the application-supplied routine are two strings,
  1308. ** each represented by a (length, data) pair and encoded in the encoding
  1309. ** that was passed as the third argument when the collation sequence was
  1310. ** registered. {END} The application defined collation routine should
  1311. ** return negative, zero or positive if
  1312. ** the first string is less than, equal to, or greater than the second
  1313. ** string. i.e. (STRING1 - STRING2).
  1314. **
  1315. ** The sqlite3_create_collation_v2() works like sqlite3_create_collation()
  1316. ** excapt that it takes an extra argument which is a destructor for
  1317. ** the collation.  The destructor is called when the collation is
  1318. ** destroyed and is passed a copy of the fourth parameter void* pointer
  1319. ** of the sqlite3_create_collation_v2().
  1320. ** Collations are destroyed when
  1321. ** they are overridden by later calls to the collation creation functions
  1322. ** or when the [sqlite3*] database handle is closed using [sqlite3_close()].
  1323. **
  1324. ** INVARIANTS:
  1325. **
  1326. ** {F16603} A successful call to the
  1327. **          [sqlite3_create_collation_v2(B,X,E,P,F,D)] interface
  1328. **          registers function F as the comparison function used to
  1329. **          implement collation X on [database connection] B for
  1330. **          databases having encoding E.
  1331. **
  1332. ** {F16604} SQLite understands the X parameter to
  1333. **          [sqlite3_create_collation_v2(B,X,E,P,F,D)] as a zero-terminated
  1334. **          UTF-8 string in which case is ignored for ASCII characters and
  1335. **          is significant for non-ASCII characters.
  1336. **
  1337. ** {F16606} Successive calls to [sqlite3_create_collation_v2(B,X,E,P,F,D)]
  1338. **          with the same values for B, X, and E, override prior values
  1339. **          of P, F, and D.
  1340. **
  1341. ** {F16609} The destructor D in [sqlite3_create_collation_v2(B,X,E,P,F,D)]
  1342. **          is not NULL then it is called with argument P when the
  1343. **          collating function is dropped by SQLite.
  1344. **
  1345. ** {F16612} A collating function is dropped when it is overloaded.
  1346. **
  1347. ** {F16615} A collating function is dropped when the database connection
  1348. **          is closed using [sqlite3_close()].
  1349. **
  1350. ** {F16618} The pointer P in [sqlite3_create_collation_v2(B,X,E,P,F,D)]
  1351. **          is passed through as the first parameter to the comparison
  1352. **          function F for all subsequent invocations of F.
  1353. **
  1354. ** {F16621} A call to [sqlite3_create_collation(B,X,E,P,F)] is exactly
  1355. **          the same as a call to [sqlite3_create_collation_v2()] with
  1356. **          the same parameters and a NULL destructor.
  1357. **
  1358. ** {F16624} Following a [sqlite3_create_collation_v2(B,X,E,P,F,D)],
  1359. **          SQLite uses the comparison function F for all text comparison
  1360. **          operations on [database connection] B on text values that
  1361. **          use the collating sequence name X.
  1362. **
  1363. ** {F16627} The [sqlite3_create_collation16(B,X,E,P,F)] works the same
  1364. **          as [sqlite3_create_collation(B,X,E,P,F)] except that the
  1365. **          collation name X is understood as UTF-16 in native byte order
  1366. **          instead of UTF-8.
  1367. **
  1368. ** {F16630} When multiple comparison functions are available for the same
  1369. **          collating sequence, SQLite chooses the one whose text encoding
  1370. **          requires the least amount of conversion from the default
  1371. **          text encoding of the database.
  1372. */
  1373. int sqlite3_create_collation(
  1374.   sqlite3*, 
  1375.   const char *zName, 
  1376.   int eTextRep, 
  1377.   void*,
  1378.   int(*xCompare)(void*,int,const void*,int,const void*)
  1379. );
  1380. int sqlite3_create_collation_v2(
  1381.   sqlite3*, 
  1382.   const char *zName, 
  1383.   int eTextRep, 
  1384.   void*,
  1385.   int(*xCompare)(void*,int,const void*,int,const void*),
  1386.   void(*xDestroy)(void*)
  1387. );
  1388. int sqlite3_create_collation16(
  1389.   sqlite3*, 
  1390.   const char *zName, 
  1391.   int eTextRep, 
  1392.   void*,
  1393.   int(*xCompare)(void*,int,const void*,int,const void*)
  1394. );
  1395. /*
  1396. ** CAPI3REF: Collation Needed Callbacks {F16700}
  1397. **
  1398. ** To avoid having to register all collation sequences before a database
  1399. ** can be used, a single callback function may be registered with the
  1400. ** database handle to be called whenever an undefined collation sequence is
  1401. ** required.
  1402. **
  1403. ** If the function is registered using the sqlite3_collation_needed() API,
  1404. ** then it is passed the names of undefined collation sequences as strings
  1405. ** encoded in UTF-8. {F16703} If sqlite3_collation_needed16() is used, the names
  1406. ** are passed as UTF-16 in machine native byte order. A call to either
  1407. ** function replaces any existing callback.
  1408. **
  1409. ** When the callback is invoked, the first argument passed is a copy
  1410. ** of the second argument to sqlite3_collation_needed() or
  1411. ** sqlite3_collation_needed16().  The second argument is the database
  1412. ** handle.  The third argument is one of [SQLITE_UTF8],
  1413. ** [SQLITE_UTF16BE], or [SQLITE_UTF16LE], indicating the most
  1414. ** desirable form of the collation sequence function required.
  1415. ** The fourth parameter is the name of the
  1416. ** required collation sequence.
  1417. **
  1418. ** The callback function should register the desired collation using
  1419. ** [sqlite3_create_collation()], [sqlite3_create_collation16()], or
  1420. ** [sqlite3_create_collation_v2()].
  1421. **
  1422. ** INVARIANTS:
  1423. **
  1424. ** {F16702} A successful call to [sqlite3_collation_needed(D,P,F)]
  1425. **          or [sqlite3_collation_needed16(D,P,F)] causes
  1426. **          the [database connection] D to invoke callback F with first
  1427. **          parameter P whenever it needs a comparison function for a
  1428. **          collating sequence that it does not know about.
  1429. **
  1430. ** {F16704} Each successful call to [sqlite3_collation_needed()] or
  1431. **          [sqlite3_collation_needed16()] overrides the callback registered
  1432. **          on the same [database connection] by prior calls to either
  1433. **          interface.
  1434. **
  1435. ** {F16706} The name of the requested collating function passed in the
  1436. **          4th parameter to the callback is in UTF-8 if the callback
  1437. **          was registered using [sqlite3_collation_needed()] and
  1438. **          is in UTF-16 native byte order if the callback was
  1439. **          registered using [sqlite3_collation_needed16()].
  1440. **
  1441. ** 
  1442. */
  1443. int sqlite3_collation_needed(
  1444.   sqlite3*, 
  1445.   void*, 
  1446.   void(*)(void*,sqlite3*,int eTextRep,const char*)
  1447. );
  1448. int sqlite3_collation_needed16(
  1449.   sqlite3*, 
  1450.   void*,
  1451.   void(*)(void*,sqlite3*,int eTextRep,const void*)
  1452. );
  1453. /*
  1454. ** Specify the key for an encrypted database.  This routine should be
  1455. ** called right after sqlite3_open().
  1456. **
  1457. ** The code to implement this API is not available in the public release
  1458. ** of SQLite.
  1459. */
  1460. int sqlite3_key(
  1461.   sqlite3 *db,                   /* Database to be rekeyed */
  1462.   const void *pKey, int nKey     /* The key */
  1463. );
  1464. /*
  1465. ** Change the key on an open database.  If the current database is not
  1466. ** encrypted, this routine will encrypt it.  If pNew==0 or nNew==0, the
  1467. ** database is decrypted.
  1468. **
  1469. ** The code to implement this API is not available in the public release
  1470. ** of SQLite.
  1471. */
  1472. int sqlite3_rekey(
  1473.   sqlite3 *db,                   /* Database to be rekeyed */
  1474.   const void *pKey, int nKey     /* The new key */
  1475. );
  1476. /*
  1477. ** CAPI3REF:  Suspend Execution For A Short Time {F10530}
  1478. **
  1479. ** The sqlite3_sleep() function
  1480. ** causes the current thread to suspend execution
  1481. ** for at least a number of milliseconds specified in its parameter.
  1482. **
  1483. ** If the operating system does not support sleep requests with 
  1484. ** millisecond time resolution, then the time will be rounded up to 
  1485. ** the nearest second. The number of milliseconds of sleep actually 
  1486. ** requested from the operating system is returned.
  1487. **
  1488. ** SQLite implements this interface by calling the xSleep()
  1489. ** method of the default [sqlite3_vfs] object.
  1490. **
  1491. ** INVARIANTS:
  1492. **
  1493. ** {F10533} The [sqlite3_sleep(M)] interface invokes the xSleep
  1494. **          method of the default [sqlite3_vfs|VFS] in order to
  1495. **          suspend execution of the current thread for at least
  1496. **          M milliseconds.
  1497. **
  1498. ** {F10536} The [sqlite3_sleep(M)] interface returns the number of
  1499. **          milliseconds of sleep actually requested of the operating
  1500. **          system, which might be larger than the parameter M.
  1501. */
  1502. int sqlite3_sleep(int);
  1503. /*
  1504. ** CAPI3REF:  Name Of The Folder Holding Temporary Files {F10310}
  1505. **
  1506. ** If this global variable is made to point to a string which is
  1507. ** the name of a folder (a.ka. directory), then all temporary files
  1508. ** created by SQLite will be placed in that directory.  If this variable
  1509. ** is NULL pointer, then SQLite does a search for an appropriate temporary
  1510. ** file directory.
  1511. **
  1512. ** It is not safe to modify this variable once a database connection
  1513. ** has been opened.  It is intended that this variable be set once
  1514. ** as part of process initialization and before any SQLite interface
  1515. ** routines have been call and remain unchanged thereafter.
  1516. */
  1517. SQLITE_EXTERN char *sqlite3_temp_directory;
  1518. /*
  1519. ** CAPI3REF:  Test To See If The Database Is In Auto-Commit Mode {F12930}
  1520. **
  1521. ** The sqlite3_get_autocommit() interfaces returns non-zero or
  1522. ** zero if the given database connection is or is not in autocommit mode,
  1523. ** respectively.   Autocommit mode is on
  1524. ** by default.  Autocommit mode is disabled by a [BEGIN] statement.
  1525. ** Autocommit mode is reenabled by a [COMMIT] or [ROLLBACK].
  1526. **
  1527. ** If certain kinds of errors occur on a statement within a multi-statement
  1528. ** transactions (errors including [SQLITE_FULL], [SQLITE_IOERR], 
  1529. ** [SQLITE_NOMEM], [SQLITE_BUSY], and [SQLITE_INTERRUPT]) then the
  1530. ** transaction might be rolled back automatically.  The only way to
  1531. ** find out if SQLite automatically rolled back the transaction after
  1532. ** an error is to use this function.
  1533. **
  1534. ** INVARIANTS:
  1535. **
  1536. ** {F12931} The [sqlite3_get_autocommit(D)] interface returns non-zero or
  1537. **          zero if the [database connection] D is or is not in autocommit
  1538. **          mode, respectively.
  1539. **
  1540. ** {F12932} Autocommit mode is on by default.
  1541. **
  1542. ** {F12933} Autocommit mode is disabled by a successful [BEGIN] statement.
  1543. **
  1544. ** {F12934} Autocommit mode is enabled by a successful [COMMIT] or [ROLLBACK]
  1545. **          statement.
  1546. ** 
  1547. **
  1548. ** LIMITATIONS:
  1549. ***
  1550. ** {U12936} If another thread changes the autocommit status of the database
  1551. **          connection while this routine is running, then the return value
  1552. **          is undefined.
  1553. */
  1554. int sqlite3_get_autocommit(sqlite3*);
  1555. /*
  1556. ** CAPI3REF:  Find The Database Handle Of A Prepared Statement {F13120}
  1557. **
  1558. ** The sqlite3_db_handle interface
  1559. ** returns the [sqlite3*] database handle to which a
  1560. ** [prepared statement] belongs.
  1561. ** The database handle returned by sqlite3_db_handle
  1562. ** is the same database handle that was
  1563. ** the first argument to the [sqlite3_prepare_v2()] or its variants
  1564. ** that was used to create the statement in the first place.
  1565. **
  1566. ** INVARIANTS:
  1567. **
  1568. ** {F13123} The [sqlite3_db_handle(S)] interface returns a pointer
  1569. **          to the [database connection] associated with
  1570. **          [prepared statement] S.
  1571. */
  1572. sqlite3 *sqlite3_db_handle(sqlite3_stmt*);
  1573. /*
  1574. ** CAPI3REF: Commit And Rollback Notification Callbacks {F12950}
  1575. **
  1576. ** The sqlite3_commit_hook() interface registers a callback
  1577. ** function to be invoked whenever a transaction is committed.
  1578. ** Any callback set by a previous call to sqlite3_commit_hook()
  1579. ** for the same database connection is overridden.
  1580. ** The sqlite3_rollback_hook() interface registers a callback
  1581. ** function to be invoked whenever a transaction is committed.
  1582. ** Any callback set by a previous call to sqlite3_commit_hook()
  1583. ** for the same database connection is overridden.
  1584. ** The pArg argument is passed through
  1585. ** to the callback.  If the callback on a commit hook function 
  1586. ** returns non-zero, then the commit is converted into a rollback.
  1587. **
  1588. ** If another function was previously registered, its
  1589. ** pArg value is returned.  Otherwise NULL is returned.
  1590. **
  1591. ** Registering a NULL function disables the callback.
  1592. **
  1593. ** For the purposes of this API, a transaction is said to have been 
  1594. ** rolled back if an explicit "ROLLBACK" statement is executed, or
  1595. ** an error or constraint causes an implicit rollback to occur.
  1596. ** The rollback callback is not invoked if a transaction is
  1597. ** automatically rolled back because the database connection is closed.
  1598. ** The rollback callback is not invoked if a transaction is
  1599. ** rolled back because a commit callback returned non-zero.
  1600. ** <todo> Check on this </todo>
  1601. **
  1602. ** These are experimental interfaces and are subject to change.
  1603. **
  1604. ** INVARIANTS:
  1605. **
  1606. ** {F12951} The [sqlite3_commit_hook(D,F,P)] interface registers the
  1607. **          callback function F to be invoked with argument P whenever
  1608. **          a transaction commits on [database connection] D.
  1609. **
  1610. ** {F12952} The [sqlite3_commit_hook(D,F,P)] interface returns the P
  1611. **          argument from the previous call with the same 
  1612. **          [database connection ] D , or NULL on the first call
  1613. **          for a particular [database connection] D.
  1614. **
  1615. ** {F12953} Each call to [sqlite3_commit_hook()] overwrites the callback
  1616. **          registered by prior calls.
  1617. **
  1618. ** {F12954} If the F argument to [sqlite3_commit_hook(D,F,P)] is NULL
  1619. **          then the commit hook callback is cancelled and no callback
  1620. **          is invoked when a transaction commits.
  1621. **
  1622. ** {F12955} If the commit callback returns non-zero then the commit is
  1623. **          converted into a rollback.
  1624. **
  1625. ** {F12961} The [sqlite3_rollback_hook(D,F,P)] interface registers the
  1626. **          callback function F to be invoked with argument P whenever
  1627. **          a transaction rolls back on [database connection] D.
  1628. **
  1629. ** {F12962} The [sqlite3_rollback_hook(D,F,P)] interface returns the P
  1630. **          argument from the previous call with the same 
  1631. **          [database connection ] D , or NULL on the first call
  1632. **          for a particular [database connection] D.
  1633. **
  1634. ** {F12963} Each call to [sqlite3_rollback_hook()] overwrites the callback
  1635. **          registered by prior calls.
  1636. **
  1637. ** {F12964} If the F argument to [sqlite3_rollback_hook(D,F,P)] is NULL
  1638. **          then the rollback hook callback is cancelled and no callback
  1639. **          is invoked when a transaction rolls back.
  1640. */
  1641. void *sqlite3_commit_hook(sqlite3*, int(*)(void*), void*);
  1642. void *sqlite3_rollback_hook(sqlite3*, void(*)(void *), void*);
  1643. /*
  1644. ** CAPI3REF: Data Change Notification Callbacks {F12970}
  1645. **
  1646. ** The sqlite3_update_hook() interface
  1647. ** registers a callback function with the database connection identified by the 
  1648. ** first argument to be invoked whenever a row is updated, inserted or deleted.
  1649. ** Any callback set by a previous call to this function for the same 
  1650. ** database connection is overridden.
  1651. **
  1652. ** The second argument is a pointer to the function to invoke when a 
  1653. ** row is updated, inserted or deleted. 
  1654. ** The first argument to the callback is
  1655. ** a copy of the third argument to sqlite3_update_hook().
  1656. ** The second callback 
  1657. ** argument is one of [SQLITE_INSERT], [SQLITE_DELETE] or [SQLITE_UPDATE],
  1658. ** depending on the operation that caused the callback to be invoked.
  1659. ** The third and 
  1660. ** fourth arguments to the callback contain pointers to the database and 
  1661. ** table name containing the affected row.
  1662. ** The final callback parameter is 
  1663. ** the rowid of the row.
  1664. ** In the case of an update, this is the rowid after 
  1665. ** the update takes place.
  1666. **
  1667. ** The update hook is not invoked when internal system tables are
  1668. ** modified (i.e. sqlite_master and sqlite_sequence).
  1669. **
  1670. ** If another function was previously registered, its pArg value
  1671. ** is returned.  Otherwise NULL is returned.
  1672. **
  1673. ** INVARIANTS:
  1674. **
  1675. ** {F12971} The [sqlite3_update_hook(D,F,P)] interface causes callback
  1676. **          function F to be invoked with first parameter P whenever
  1677. **          a table row is modified, inserted, or deleted on
  1678. **          [database connection] D.
  1679. **
  1680. ** {F12973} The [sqlite3_update_hook(D,F,P)] interface returns the value
  1681. **          of P for the previous call on the same [database connection] D,
  1682. **          or NULL for the first call.
  1683. **
  1684. ** {F12975} If the update hook callback F in [sqlite3_update_hook(D,F,P)]
  1685. **          is NULL then the no update callbacks are made.
  1686. **
  1687. ** {F12977} Each call to [sqlite3_update_hook(D,F,P)] overrides prior calls
  1688. **          to the same interface on the same [database connection] D.
  1689. **
  1690. ** {F12979} The update hook callback is not invoked when internal system
  1691. **          tables such as sqlite_master and sqlite_sequence are modified.
  1692. **
  1693. ** {F12981} The second parameter to the update callback 
  1694. **          is one of [SQLITE_INSERT], [SQLITE_DELETE] or [SQLITE_UPDATE],
  1695. **          depending on the operation that caused the callback to be invoked.
  1696. **
  1697. ** {F12983} The third and fourth arguments to the callback contain pointers
  1698. **          to zero-terminated UTF-8 strings which are the names of the
  1699. **          database and table that is being updated.
  1700. ** {F12985} The final callback parameter is the rowid of the row after
  1701. **          the change occurs.
  1702. */
  1703. void *sqlite3_update_hook(
  1704.   sqlite3*, 
  1705.   void(*)(void *,int ,char const *,char const *,sqlite3_int64),
  1706.   void*
  1707. );
  1708. /*
  1709. ** CAPI3REF:  Enable Or Disable Shared Pager Cache {F10330}
  1710. **
  1711. ** This routine enables or disables the sharing of the database cache
  1712. ** and schema data structures between connections to the same database.
  1713. ** Sharing is enabled if the argument is true and disabled if the argument
  1714. ** is false.
  1715. **
  1716. ** Cache sharing is enabled and disabled
  1717. ** for an entire process. {END} This is a change as of SQLite version 3.5.0.
  1718. ** In prior versions of SQLite, sharing was
  1719. ** enabled or disabled for each thread separately.
  1720. **
  1721. ** The cache sharing mode set by this interface effects all subsequent
  1722. ** calls to [sqlite3_open()], [sqlite3_open_v2()], and [sqlite3_open16()].
  1723. ** Existing database connections continue use the sharing mode
  1724. ** that was in effect at the time they were opened.
  1725. **
  1726. ** Virtual tables cannot be used with a shared cache.   When shared
  1727. ** cache is enabled, the [sqlite3_create_module()] API used to register
  1728. ** virtual tables will always return an error.
  1729. **
  1730. ** This routine returns [SQLITE_OK] if shared cache was
  1731. ** enabled or disabled successfully.  An [error code]
  1732. ** is returned otherwise.
  1733. **
  1734. ** Shared cache is disabled by default. But this might change in
  1735. ** future releases of SQLite.  Applications that care about shared
  1736. ** cache setting should set it explicitly.
  1737. **
  1738. ** INVARIANTS:
  1739. ** 
  1740. ** {F10331} A successful invocation of [sqlite3_enable_shared_cache(B)]
  1741. **          will enable or disable shared cache mode for any subsequently
  1742. **          created [database connection] in the same process.
  1743. **
  1744. ** {F10336} When shared cache is enabled, the [sqlite3_create_module()]
  1745. **          interface will always return an error.
  1746. **
  1747. ** {F10337} The [sqlite3_enable_shared_cache(B)] interface returns
  1748. **          [SQLITE_OK] if shared cache was enabled or disabled successfully.
  1749. **
  1750. ** {F10339} Shared cache is disabled by default.
  1751. */
  1752. int sqlite3_enable_shared_cache(int);
  1753. /*
  1754. ** CAPI3REF:  Attempt To Free Heap Memory {F17340}
  1755. **
  1756. ** The sqlite3_release_memory() interface attempts to
  1757. ** free N bytes of heap memory by deallocating non-essential memory
  1758. ** allocations held by the database labrary. {END}  Memory used
  1759. ** to cache database pages to improve performance is an example of
  1760. ** non-essential memory.  Sqlite3_release_memory() returns
  1761. ** the number of bytes actually freed, which might be more or less
  1762. ** than the amount requested.
  1763. **
  1764. ** INVARIANTS:
  1765. **
  1766. ** {F17341} The [sqlite3_release_memory(N)] interface attempts to
  1767. **          free N bytes of heap memory by deallocating non-essential
  1768. **          memory allocations held by the database labrary.
  1769. **
  1770. ** {F16342} The [sqlite3_release_memory(N)] returns the number
  1771. **          of bytes actually freed, which might be more or less
  1772. **          than the amount requested.
  1773. */
  1774. int sqlite3_release_memory(int);
  1775. /*
  1776. ** CAPI3REF:  Impose A Limit On Heap Size {F17350}
  1777. **
  1778. ** The sqlite3_soft_heap_limit() interface
  1779. ** places a "soft" limit on the amount of heap memory that may be allocated
  1780. ** by SQLite. If an internal allocation is requested 
  1781. ** that would exceed the soft heap limit, [sqlite3_release_memory()] is
  1782. ** invoked one or more times to free up some space before the allocation
  1783. ** is made.
  1784. **
  1785. ** The limit is called "soft", because if
  1786. ** [sqlite3_release_memory()] cannot
  1787. ** free sufficient memory to prevent the limit from being exceeded,
  1788. ** the memory is allocated anyway and the current operation proceeds.
  1789. **
  1790. ** A negative or zero value for N means that there is no soft heap limit and
  1791. ** [sqlite3_release_memory()] will only be called when memory is exhausted.
  1792. ** The default value for the soft heap limit is zero.
  1793. **
  1794. ** SQLite makes a best effort to honor the soft heap limit.  
  1795. ** But if the soft heap limit cannot honored, execution will
  1796. ** continue without error or notification.  This is why the limit is 
  1797. ** called a "soft" limit.  It is advisory only.
  1798. **
  1799. ** Prior to SQLite version 3.5.0, this routine only constrained the memory
  1800. ** allocated by a single thread - the same thread in which this routine
  1801. ** runs.  Beginning with SQLite version 3.5.0, the soft heap limit is
  1802. ** applied to all threads. The value specified for the soft heap limit
  1803. ** is an upper bound on the total memory allocation for all threads. In
  1804. ** version 3.5.0 there is no mechanism for limiting the heap usage for
  1805. ** individual threads.
  1806. **
  1807. ** INVARIANTS:
  1808. **
  1809. ** {F16351} The [sqlite3_soft_heap_limit(N)] interface places a soft limit
  1810. **          of N bytes on the amount of heap memory that may be allocated
  1811. **          using [sqlite3_malloc()] or [sqlite3_realloc()] at any point
  1812. **          in time.
  1813. **
  1814. ** {F16352} If a call to [sqlite3_malloc()] or [sqlite3_realloc()] would
  1815. **          cause the total amount of allocated memory to exceed the
  1816. **          soft heap limit, then [sqlite3_release_memory()] is invoked
  1817. **          in an attempt to reduce the memory usage prior to proceeding
  1818. **          with the memory allocation attempt.
  1819. **
  1820. ** {F16353} Calls to [sqlite3_malloc()] or [sqlite3_realloc()] that trigger
  1821. **          attempts to reduce memory usage through the soft heap limit
  1822. **          mechanism continue even if the attempt to reduce memory
  1823. **          usage is unsuccessful.
  1824. **
  1825. ** {F16354} A negative or zero value for N in a call to
  1826. **          [sqlite3_soft_heap_limit(N)] means that there is no soft
  1827. **          heap limit and [sqlite3_release_memory()] will only be
  1828. **          called when memory is completely exhausted.
  1829. **
  1830. ** {F16355} The default value for the soft heap limit is zero.
  1831. **
  1832. ** {F16358} Each call to [sqlite3_soft_heap_limit(N)] overrides the
  1833. **          values set by all prior calls.
  1834. */
  1835. void sqlite3_soft_heap_limit(int);
  1836. /*
  1837. ** CAPI3REF:  Extract Metadata About A Column Of A Table {F12850}
  1838. **
  1839. ** This routine
  1840. ** returns meta-data about a specific column of a specific database
  1841. ** table accessible using the connection handle passed as the first function 
  1842. ** argument.
  1843. **
  1844. ** The column is identified by the second, third and fourth parameters to 
  1845. ** this function. The second parameter is either the name of the database
  1846. ** (i.e. "main", "temp" or an attached database) containing the specified
  1847. ** table or NULL. If it is NULL, then all attached databases are searched
  1848. ** for the table using the same algorithm as the database engine uses to 
  1849. ** resolve unqualified table references.
  1850. **
  1851. ** The third and fourth parameters to this function are the table and column 
  1852. ** name of the desired column, respectively. Neither of these parameters 
  1853. ** may be NULL.
  1854. **
  1855. ** Meta information is returned by writing to the memory locations passed as
  1856. ** the 5th and subsequent parameters to this function. Any of these 
  1857. ** arguments may be NULL, in which case the corresponding element of meta 
  1858. ** information is ommitted.
  1859. **
  1860. ** <pre>
  1861. ** Parameter     Output Type      Description
  1862. ** -----------------------------------
  1863. **
  1864. **   5th         const char*      Data type
  1865. **   6th         const char*      Name of the default collation sequence 
  1866. **   7th         int              True if the column has a NOT NULL constraint
  1867. **   8th         int              True if the column is part of the PRIMARY KEY
  1868. **   9th         int              True if the column is AUTOINCREMENT
  1869. ** </pre>
  1870. **
  1871. **
  1872. ** The memory pointed to by the character pointers returned for the 
  1873. ** declaration type and collation sequence is valid only until the next 
  1874. ** call to any sqlite API function.
  1875. **
  1876. ** If the specified table is actually a view, then an error is returned.
  1877. **
  1878. ** If the specified column is "rowid", "oid" or "_rowid_" and an 
  1879. ** INTEGER PRIMARY KEY column has been explicitly declared, then the output 
  1880. ** parameters are set for the explicitly declared column. If there is no
  1881. ** explicitly declared IPK column, then the output parameters are set as 
  1882. ** follows:
  1883. **
  1884. ** <pre>
  1885. **     data type: "INTEGER"
  1886. **     collation sequence: "BINARY"
  1887. **     not null: 0
  1888. **     primary key: 1
  1889. **     auto increment: 0
  1890. ** </pre>
  1891. **
  1892. ** This function may load one or more schemas from database files. If an
  1893. ** error occurs during this process, or if the requested table or column
  1894. ** cannot be found, an SQLITE error code is returned and an error message
  1895. ** left in the database handle (to be retrieved using sqlite3_errmsg()).
  1896. **
  1897. ** This API is only available if the library was compiled with the
  1898. ** SQLITE_ENABLE_COLUMN_METADATA preprocessor symbol defined.
  1899. */
  1900. int sqlite3_table_column_metadata(
  1901.   sqlite3 *db,                /* Connection handle */
  1902.   const char *zDbName,        /* Database name or NULL */
  1903.   const char *zTableName,     /* Table name */
  1904.   const char *zColumnName,    /* Column name */
  1905.   char const **pzDataType,    /* OUTPUT: Declared data type */
  1906.   char const **pzCollSeq,     /* OUTPUT: Collation sequence name */
  1907.   int *pNotNull,              /* OUTPUT: True if NOT NULL constraint exists */
  1908.   int *pPrimaryKey,           /* OUTPUT: True if column part of PK */
  1909.   int *pAutoinc               /* OUTPUT: True if column is auto-increment */
  1910. );
  1911. /*
  1912. ** CAPI3REF: Load An Extension {F12600}
  1913. **
  1914. ** {F12601} The sqlite3_load_extension() interface
  1915. ** attempts to load an SQLite extension library contained in the file
  1916. ** zFile. {F12602} The entry point is zProc. {F12603} zProc may be 0
  1917. ** in which case the name of the entry point defaults
  1918. ** to "sqlite3_extension_init".
  1919. **
  1920. ** {F12604} The sqlite3_load_extension() interface shall
  1921. ** return [SQLITE_OK] on success and [SQLITE_ERROR] if something goes wrong.
  1922. **
  1923. ** {F12605}
  1924. ** If an error occurs and pzErrMsg is not 0, then the
  1925. ** sqlite3_load_extension() interface shall attempt to fill *pzErrMsg with 
  1926. ** error message text stored in memory obtained from [sqlite3_malloc()].
  1927. ** {END}  The calling function should free this memory
  1928. ** by calling [sqlite3_free()].
  1929. **
  1930. ** {F12606}
  1931. ** Extension loading must be enabled using [sqlite3_enable_load_extension()]
  1932. ** prior to calling this API or an error will be returned.
  1933. */
  1934. int sqlite3_load_extension(
  1935.   sqlite3 *db,          /* Load the extension into this database connection */
  1936.   const char *zFile,    /* Name of the shared library containing extension */
  1937.   const char *zProc,    /* Entry point.  Derived from zFile if 0 */
  1938.   char **pzErrMsg       /* Put error message here if not 0 */
  1939. );
  1940. /*
  1941. ** CAPI3REF:  Enable Or Disable Extension Loading {F12620}
  1942. **
  1943. ** So as not to open security holes in older applications that are
  1944. ** unprepared to deal with extension loading, and as a means of disabling
  1945. ** extension loading while evaluating user-entered SQL, the following
  1946. ** API is provided to turn the [sqlite3_load_extension()] mechanism on and
  1947. ** off.  {F12622} It is off by default. {END} See ticket #1863.
  1948. **
  1949. ** {F12621} Call the sqlite3_enable_load_extension() routine
  1950. ** with onoff==1 to turn extension loading on
  1951. ** and call it with onoff==0 to turn it back off again. {END}
  1952. */
  1953. int sqlite3_enable_load_extension(sqlite3 *db, int onoff);
  1954. /*
  1955. ** CAPI3REF: Make Arrangements To Automatically Load An Extension {F12640}
  1956. **
  1957. ** {F12641} This function
  1958. ** registers an extension entry point that is automatically invoked
  1959. ** whenever a new database connection is opened using
  1960. ** [sqlite3_open()], [sqlite3_open16()], or [sqlite3_open_v2()]. {END}
  1961. **
  1962. ** This API can be invoked at program startup in order to register
  1963. ** one or more statically linked extensions that will be available
  1964. ** to all new database connections.
  1965. **
  1966. ** {F12642} Duplicate extensions are detected so calling this routine multiple
  1967. ** times with the same extension is harmless.
  1968. **
  1969. ** {F12643} This routine stores a pointer to the extension in an array
  1970. ** that is obtained from sqlite_malloc(). {END} If you run a memory leak
  1971. ** checker on your program and it reports a leak because of this
  1972. ** array, then invoke [sqlite3_reset_auto_extension()] prior
  1973. ** to shutdown to free the memory.
  1974. **
  1975. ** {F12644} Automatic extensions apply across all threads. {END}
  1976. **
  1977. ** This interface is experimental and is subject to change or
  1978. ** removal in future releases of SQLite.
  1979. */
  1980. int sqlite3_auto_extension(void *xEntryPoint);
  1981. /*
  1982. ** CAPI3REF: Reset Automatic Extension Loading {F12660}
  1983. **
  1984. ** {F12661} This function disables all previously registered
  1985. ** automatic extensions. {END}  This
  1986. ** routine undoes the effect of all prior [sqlite3_auto_extension()]
  1987. ** calls.
  1988. **
  1989. ** {F12662} This call disabled automatic extensions in all threads. {END}
  1990. **
  1991. ** This interface is experimental and is subject to change or
  1992. ** removal in future releases of SQLite.
  1993. */
  1994. void sqlite3_reset_auto_extension(void);
  1995. /*
  1996. ****** EXPERIMENTAL - subject to change without notice **************
  1997. **
  1998. ** The interface to the virtual-table mechanism is currently considered
  1999. ** to be experimental.  The interface might change in incompatible ways.
  2000. ** If this is a problem for you, do not use the interface at this time.
  2001. **
  2002. ** When the virtual-table mechanism stablizes, we will declare the
  2003. ** interface fixed, support it indefinitely, and remove this comment.
  2004. */
  2005. /*
  2006. ** Structures used by the virtual table interface
  2007. */
  2008. typedef struct sqlite3_vtab sqlite3_vtab;
  2009. typedef struct sqlite3_index_info sqlite3_index_info;
  2010. typedef struct sqlite3_vtab_cursor sqlite3_vtab_cursor;
  2011. typedef struct sqlite3_module sqlite3_module;
  2012. /*
  2013. ** CAPI3REF: Virtual Table Object {F18000}
  2014. ** KEYWORDS: sqlite3_module
  2015. **
  2016. ** A module is a class of virtual tables.  Each module is defined
  2017. ** by an instance of the following structure.  This structure consists
  2018. ** mostly of methods for the module.
  2019. */
  2020. struct sqlite3_module {
  2021.   int iVersion;
  2022.   int (*xCreate)(sqlite3*, void *pAux,
  2023.                int argc, const char *const*argv,
  2024.                sqlite3_vtab **ppVTab, char**);
  2025.   int (*xConnect)(sqlite3*, void *pAux,
  2026.                int argc, const char *const*argv,
  2027.                sqlite3_vtab **ppVTab, char**);
  2028.   int (*xBestIndex)(sqlite3_vtab *pVTab, sqlite3_index_info*);
  2029.   int (*xDisconnect)(sqlite3_vtab *pVTab);
  2030.   int (*xDestroy)(sqlite3_vtab *pVTab);
  2031.   int (*xOpen)(sqlite3_vtab *pVTab, sqlite3_vtab_cursor **ppCursor);
  2032.   int (*xClose)(sqlite3_vtab_cursor*);
  2033.   int (*xFilter)(sqlite3_vtab_cursor*, int idxNum, const char *idxStr,
  2034.                 int argc, sqlite3_value **argv);
  2035.   int (*xNext)(sqlite3_vtab_cursor*);
  2036.   int (*xEof)(sqlite3_vtab_cursor*);
  2037.   int (*xColumn)(sqlite3_vtab_cursor*, sqlite3_context*, int);
  2038.   int (*xRowid)(sqlite3_vtab_cursor*, sqlite3_int64 *pRowid);
  2039.   int (*xUpdate)(sqlite3_vtab *, int, sqlite3_value **, sqlite3_int64 *);
  2040.   int (*xBegin)(sqlite3_vtab *pVTab);
  2041.   int (*xSync)(sqlite3_vtab *pVTab);
  2042.   int (*xCommit)(sqlite3_vtab *pVTab);
  2043.   int (*xRollback)(sqlite3_vtab *pVTab);
  2044.   int (*xFindFunction)(sqlite3_vtab *pVtab, int nArg, const char *zName,
  2045.                        void (**pxFunc)(sqlite3_context*,int,sqlite3_value**),
  2046.                        void **ppArg);
  2047.   int (*xRename)(sqlite3_vtab *pVtab, const char *zNew);
  2048. };
  2049. /*
  2050. ** CAPI3REF: Virtual Table Indexing Information {F18100}
  2051. ** KEYWORDS: sqlite3_index_info
  2052. **
  2053. ** The sqlite3_index_info structure and its substructures is used to
  2054. ** pass information into and receive the reply from the xBestIndex
  2055. ** method of an sqlite3_module.  The fields under **Inputs** are the
  2056. ** inputs to xBestIndex and are read-only.  xBestIndex inserts its
  2057. ** results into the **Outputs** fields.
  2058. **
  2059. ** The aConstraint[] array records WHERE clause constraints of the
  2060. ** form:
  2061. **
  2062. **         column OP expr
  2063. **
  2064. ** Where OP is =, &lt;, &lt;=, &gt;, or &gt;=.  
  2065. ** The particular operator is stored
  2066. ** in aConstraint[].op.  The index of the column is stored in 
  2067. ** aConstraint[].iColumn.  aConstraint[].usable is TRUE if the
  2068. ** expr on the right-hand side can be evaluated (and thus the constraint
  2069. ** is usable) and false if it cannot.
  2070. **
  2071. ** The optimizer automatically inverts terms of the form "expr OP column"
  2072. ** and makes other simplifications to the WHERE clause in an attempt to
  2073. ** get as many WHERE clause terms into the form shown above as possible.
  2074. ** The aConstraint[] array only reports WHERE clause terms in the correct
  2075. ** form that refer to the particular virtual table being queried.
  2076. **
  2077. ** Information about the ORDER BY clause is stored in aOrderBy[].
  2078. ** Each term of aOrderBy records a column of the ORDER BY clause.
  2079. **
  2080. ** The xBestIndex method must fill aConstraintUsage[] with information
  2081. ** about what parameters to pass to xFilter.  If argvIndex>0 then
  2082. ** the right-hand side of the corresponding aConstraint[] is evaluated
  2083. ** and becomes the argvIndex-th entry in argv.  If aConstraintUsage[].omit
  2084. ** is true, then the constraint is assumed to be fully handled by the
  2085. ** virtual table and is not checked again by SQLite.
  2086. **
  2087. ** The idxNum and idxPtr values are recorded and passed into xFilter.
  2088. ** sqlite3_free() is used to free idxPtr if needToFreeIdxPtr is true.
  2089. **
  2090. ** The orderByConsumed means that output from xFilter will occur in
  2091. ** the correct order to satisfy the ORDER BY clause so that no separate
  2092. ** sorting step is required.
  2093. **
  2094. ** The estimatedCost value is an estimate of the cost of doing the
  2095. ** particular lookup.  A full scan of a table with N entries should have
  2096. ** a cost of N.  A binary search of a table of N entries should have a
  2097. ** cost of approximately log(N).
  2098. */
  2099. struct sqlite3_index_info {
  2100.   /* Inputs */
  2101.   int nConstraint;           /* Number of entries in aConstraint */
  2102.   struct sqlite3_index_constraint {
  2103.      int iColumn;              /* Column on left-hand side of constraint */
  2104.      unsigned char op;         /* Constraint operator */
  2105.      unsigned char usable;     /* True if this constraint is usable */
  2106.      int iTermOffset;          /* Used internally - xBestIndex should ignore */
  2107.   } *aConstraint;            /* Table of WHERE clause constraints */
  2108.   int nOrderBy;              /* Number of terms in the ORDER BY clause */
  2109.   struct sqlite3_index_orderby {
  2110.      int iColumn;              /* Column number */
  2111.      unsigned char desc;       /* True for DESC.  False for ASC. */
  2112.   } *aOrderBy;               /* The ORDER BY clause */
  2113.   /* Outputs */
  2114.   struct sqlite3_index_constraint_usage {
  2115.     int argvIndex;           /* if >0, constraint is part of argv to xFilter */
  2116.     unsigned char omit;      /* Do not code a test for this constraint */
  2117.   } *aConstraintUsage;
  2118.   int idxNum;                /* Number used to identify the index */
  2119.   char *idxStr;              /* String, possibly obtained from sqlite3_malloc */
  2120.   int needToFreeIdxStr;      /* Free idxStr using sqlite3_free() if true */
  2121.   int orderByConsumed;       /* True if output is already ordered */
  2122.   double estimatedCost;      /* Estimated cost of using this index */
  2123. };
  2124. #define SQLITE_INDEX_CONSTRAINT_EQ    2
  2125. #define SQLITE_INDEX_CONSTRAINT_GT    4
  2126. #define SQLITE_INDEX_CONSTRAINT_LE    8
  2127. #define SQLITE_INDEX_CONSTRAINT_LT    16
  2128. #define SQLITE_INDEX_CONSTRAINT_GE    32
  2129. #define SQLITE_INDEX_CONSTRAINT_MATCH 64
  2130. /*
  2131. ** CAPI3REF: Register A Virtual Table Implementation {F18200}
  2132. **
  2133. ** This routine is used to register a new module name with an SQLite
  2134. ** connection.  Module names must be registered before creating new
  2135. ** virtual tables on the module, or before using preexisting virtual
  2136. ** tables of the module.
  2137. */
  2138. int sqlite3_create_module(
  2139.   sqlite3 *db,               /* SQLite connection to register module with */
  2140.   const char *zName,         /* Name of the module */
  2141.   const sqlite3_module *,    /* Methods for the module */
  2142.   void *                     /* Client data for xCreate/xConnect */
  2143. );
  2144. /*
  2145. ** CAPI3REF: Register A Virtual Table Implementation {F18210}
  2146. **
  2147. ** This routine is identical to the sqlite3_create_module() method above,
  2148. ** except that it allows a destructor function to be specified. It is
  2149. ** even more experimental than the rest of the virtual tables API.
  2150. */
  2151. int sqlite3_create_module_v2(
  2152.   sqlite3 *db,               /* SQLite connection to register module with */
  2153.   const char *zName,         /* Name of the module */
  2154.   const sqlite3_module *,    /* Methods for the module */
  2155.   void *,                    /* Client data for xCreate/xConnect */
  2156.   void(*xDestroy)(void*)     /* Module destructor function */
  2157. );
  2158. /*
  2159. ** CAPI3REF: Virtual Table Instance Object {F18010}
  2160. ** KEYWORDS: sqlite3_vtab
  2161. **
  2162. ** Every module implementation uses a subclass of the following structure
  2163. ** to describe a particular instance of the module.  Each subclass will
  2164. ** be tailored to the specific needs of the module implementation.   The
  2165. ** purpose of this superclass is to define certain fields that are common
  2166. ** to all module implementations.
  2167. **
  2168. ** Virtual tables methods can set an error message by assigning a
  2169. ** string obtained from sqlite3_mprintf() to zErrMsg.  The method should
  2170. ** take care that any prior string is freed by a call to sqlite3_free()
  2171. ** prior to assigning a new string to zErrMsg.  After the error message
  2172. ** is delivered up to the client application, the string will be automatically
  2173. ** freed by sqlite3_free() and the zErrMsg field will be zeroed.  Note
  2174. ** that sqlite3_mprintf() and sqlite3_free() are used on the zErrMsg field
  2175. ** since virtual tables are commonly implemented in loadable extensions which
  2176. ** do not have access to sqlite3MPrintf() or sqlite3Free().
  2177. */
  2178. struct sqlite3_vtab {
  2179.   const sqlite3_module *pModule;  /* The module for this virtual table */
  2180.   int nRef;                       /* Used internally */
  2181.   char *zErrMsg;                  /* Error message from sqlite3_mprintf() */
  2182.   /* Virtual table implementations will typically add additional fields */
  2183. };
  2184. /*
  2185. ** CAPI3REF: Virtual Table Cursor Object  {F18020}
  2186. ** KEYWORDS: sqlite3_vtab_cursor
  2187. **
  2188. ** Every module implementation uses a subclass of the following structure
  2189. ** to describe cursors that point into the virtual table and are used
  2190. ** to loop through the virtual table.  Cursors are created using the
  2191. ** xOpen method of the module.  Each module implementation will define
  2192. ** the content of a cursor structure to suit its own needs.
  2193. **
  2194. ** This superclass exists in order to define fields of the cursor that
  2195. ** are common to all implementations.
  2196. */
  2197. struct sqlite3_vtab_cursor {
  2198.   sqlite3_vtab *pVtab;      /* Virtual table of this cursor */
  2199.   /* Virtual table implementations will typically add additional fields */
  2200. };
  2201. /*
  2202. ** CAPI3REF: Declare The Schema Of A Virtual Table {F18280}
  2203. **
  2204. ** The xCreate and xConnect methods of a module use the following API
  2205. ** to declare the format (the names and datatypes of the columns) of
  2206. ** the virtual tables they implement.
  2207. */
  2208. int sqlite3_declare_vtab(sqlite3*, const char *zCreateTable);
  2209. /*
  2210. ** CAPI3REF: Overload A Function For A Virtual Table {F18300}
  2211. **
  2212. ** Virtual tables can provide alternative implementations of functions
  2213. ** using the xFindFunction method.  But global versions of those functions
  2214. ** must exist in order to be overloaded.
  2215. **
  2216. ** This API makes sure a global version of a function with a particular
  2217. ** name and number of parameters exists.  If no such function exists
  2218. ** before this API is called, a new function is created.  The implementation
  2219. ** of the new function always causes an exception to be thrown.  So
  2220. ** the new function is not good for anything by itself.  Its only
  2221. ** purpose is to be a place-holder function that can be overloaded
  2222. ** by virtual tables.
  2223. **
  2224. ** This API should be considered part of the virtual table interface,
  2225. ** which is experimental and subject to change.
  2226. */
  2227. int sqlite3_overload_function(sqlite3*, const char *zFuncName, int nArg);
  2228. /*
  2229. ** The interface to the virtual-table mechanism defined above (back up
  2230. ** to a comment remarkably similar to this one) is currently considered
  2231. ** to be experimental.  The interface might change in incompatible ways.
  2232. ** If this is a problem for you, do not use the interface at this time.
  2233. **
  2234. ** When the virtual-table mechanism stabilizes, we will declare the
  2235. ** interface fixed, support it indefinitely, and remove this comment.
  2236. **
  2237. ****** EXPERIMENTAL - subject to change without notice **************
  2238. */
  2239. /*
  2240. ** CAPI3REF: A Handle To An Open BLOB {F17800}
  2241. **
  2242. ** An instance of this object represents an open BLOB on which
  2243. ** incremental I/O can be preformed.
  2244. ** Objects of this type are created by
  2245. ** [sqlite3_blob_open()] and destroyed by [sqlite3_blob_close()].
  2246. ** The [sqlite3_blob_read()] and [sqlite3_blob_write()] interfaces
  2247. ** can be used to read or write small subsections of the blob.
  2248. ** The [sqlite3_blob_bytes()] interface returns the size of the
  2249. ** blob in bytes.
  2250. */
  2251. typedef struct sqlite3_blob sqlite3_blob;
  2252. /*
  2253. ** CAPI3REF: Open A BLOB For Incremental I/O {F17810}
  2254. **
  2255. ** This interfaces opens a handle to the blob located
  2256. ** in row iRow, column zColumn, table zTable in database zDb;
  2257. ** in other words,  the same blob that would be selected by:
  2258. **
  2259. ** <pre>
  2260. **     SELECT zColumn FROM zDb.zTable WHERE rowid = iRow;
  2261. ** </pre> {END}
  2262. **
  2263. ** If the flags parameter is non-zero, the blob is opened for 
  2264. ** read and write access. If it is zero, the blob is opened for read 
  2265. ** access.
  2266. **
  2267. ** Note that the database name is not the filename that contains
  2268. ** the database but rather the symbolic name of the database that
  2269. ** is assigned when the database is connected using [ATTACH].
  2270. ** For the main database file, the database name is "main".  For
  2271. ** TEMP tables, the database name is "temp".
  2272. **
  2273. ** On success, [SQLITE_OK] is returned and the new 
  2274. ** [sqlite3_blob | blob handle] is written to *ppBlob. 
  2275. ** Otherwise an error code is returned and 
  2276. ** any value written to *ppBlob should not be used by the caller.
  2277. ** This function sets the database-handle error code and message
  2278. ** accessible via [sqlite3_errcode()] and [sqlite3_errmsg()].
  2279. ** 
  2280. ** INVARIANTS:
  2281. **
  2282. ** {F17813} A successful invocation of the [sqlite3_blob_open(D,B,T,C,R,F,P)]
  2283. **          interface opens an [sqlite3_blob] object P on the blob
  2284. **          in column C of table T in database B on [database connection] D.
  2285. **
  2286. ** {F17814} A successful invocation of [sqlite3_blob_open(D,...)] starts
  2287. **          a new transaction on [database connection] D if that connection
  2288. **          is not already in a transaction.
  2289. **
  2290. ** {F17816} The [sqlite3_blob_open(D,B,T,C,R,F,P)] interface opens the blob
  2291. **          for read and write access if and only if the F parameter
  2292. **          is non-zero.
  2293. **
  2294. ** {F17819} The [sqlite3_blob_open()] interface returns [SQLITE_OK] on 
  2295. **          success and an appropriate [error code] on failure.
  2296. **
  2297. ** {F17821} If an error occurs during evaluation of [sqlite3_blob_open(D,...)]
  2298. **          then subsequent calls to [sqlite3_errcode(D)],
  2299. **          [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] will return
  2300. **          information approprate for that error.
  2301. */
  2302. int sqlite3_blob_open(
  2303.   sqlite3*,
  2304.   const char *zDb,
  2305.   const char *zTable,
  2306.   const char *zColumn,
  2307.   sqlite3_int64 iRow,
  2308.   int flags,
  2309.   sqlite3_blob **ppBlob
  2310. );
  2311. /*
  2312. ** CAPI3REF:  Close A BLOB Handle {F17830}
  2313. **
  2314. ** Close an open [sqlite3_blob | blob handle].
  2315. **
  2316. ** Closing a BLOB shall cause the current transaction to commit
  2317. ** if there are no other BLOBs, no pending prepared statements, and the
  2318. ** database connection is in autocommit mode.
  2319. ** If any writes were made to the BLOB, they might be held in cache
  2320. ** until the close operation if they will fit. {END}
  2321. ** Closing the BLOB often forces the changes
  2322. ** out to disk and so if any I/O errors occur, they will likely occur
  2323. ** at the time when the BLOB is closed.  {F17833} Any errors that occur during
  2324. ** closing are reported as a non-zero return value.
  2325. **
  2326. ** The BLOB is closed unconditionally.  Even if this routine returns
  2327. ** an error code, the BLOB is still closed.
  2328. **
  2329. ** INVARIANTS:
  2330. **
  2331. ** {F17833} The [sqlite3_blob_close(P)] interface closes an
  2332. **          [sqlite3_blob] object P previously opened using
  2333. **          [sqlite3_blob_open()].
  2334. **
  2335. ** {F17836} Closing an [sqlite3_blob] object using
  2336. **          [sqlite3_blob_close()] shall cause the current transaction to
  2337. **          commit if there are no other open [sqlite3_blob] objects
  2338. **          or [prepared statements] on the same [database connection] and
  2339. **          the [database connection] is in
  2340. **          [sqlite3_get_autocommit | autocommit mode].
  2341. **
  2342. ** {F17839} The [sqlite3_blob_close(P)] interfaces closes the 
  2343. **          [sqlite3_blob] object P unconditionally, even if
  2344. **          [sqlite3_blob_close(P)] returns something other than [SQLITE_OK].
  2345. **          
  2346. */
  2347. int sqlite3_blob_close(sqlite3_blob *);
  2348. /*
  2349. ** CAPI3REF:  Return The Size Of An Open BLOB {F17840}
  2350. **
  2351. ** Return the size in bytes of the blob accessible via the open 
  2352. ** [sqlite3_blob] object in its only argument.
  2353. **
  2354. ** INVARIANTS:
  2355. **
  2356. ** {F17843} The [sqlite3_blob_bytes(P)] interface returns the size
  2357. **          in bytes of the BLOB that the [sqlite3_blob] object P
  2358. **          refers to.
  2359. */
  2360. int sqlite3_blob_bytes(sqlite3_blob *);
  2361. /*
  2362. ** CAPI3REF:  Read Data From A BLOB Incrementally {F17850}
  2363. **
  2364. ** This function is used to read data from an open 
  2365. ** [sqlite3_blob | blob-handle] into a caller supplied buffer.
  2366. ** N bytes of data are copied into buffer
  2367. ** Z from the open blob, starting at offset iOffset.
  2368. **
  2369. ** If offset iOffset is less than N bytes from the end of the blob, 
  2370. ** [SQLITE_ERROR] is returned and no data is read.  If N or iOffset is
  2371. ** less than zero [SQLITE_ERROR] is returned and no data is read.
  2372. **
  2373. ** On success, SQLITE_OK is returned. Otherwise, an 
  2374. ** [error code] or an [extended error code] is returned.
  2375. **
  2376. ** INVARIANTS:
  2377. **
  2378. ** {F17853} The [sqlite3_blob_read(P,Z,N,X)] interface reads N bytes
  2379. **          beginning at offset X from
  2380. **          the blob that [sqlite3_blob] object P refers to
  2381. **          and writes those N bytes into buffer Z.
  2382. **
  2383. ** {F17856} In [sqlite3_blob_read(P,Z,N,X)] if the size of the blob
  2384. **          is less than N+X bytes, then the function returns [SQLITE_ERROR]
  2385. **          and nothing is read from the blob.
  2386. **
  2387. ** {F17859} In [sqlite3_blob_read(P,Z,N,X)] if X or N is less than zero
  2388. **          then the function returns [SQLITE_ERROR]
  2389. **          and nothing is read from the blob.
  2390. **
  2391. ** {F17862} The [sqlite3_blob_read(P,Z,N,X)] interface returns [SQLITE_OK]
  2392. **          if N bytes where successfully read into buffer Z.
  2393. **
  2394. ** {F17865} If the requested read could not be completed,
  2395. **          the [sqlite3_blob_read(P,Z,N,X)] interface returns an
  2396. **          appropriate [error code] or [extended error code].
  2397. **
  2398. ** {F17868} If an error occurs during evaluation of [sqlite3_blob_read(D,...)]
  2399. **          then subsequent calls to [sqlite3_errcode(D)],
  2400. **          [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] will return
  2401. **          information approprate for that error.
  2402. */
  2403. int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset);
  2404. /*
  2405. ** CAPI3REF:  Write Data Into A BLOB Incrementally {F17870}
  2406. **
  2407. ** This function is used to write data into an open 
  2408. ** [sqlite3_blob | blob-handle] from a user supplied buffer.
  2409. ** n bytes of data are copied from the buffer
  2410. ** pointed to by z into the open blob, starting at offset iOffset.
  2411. **
  2412. ** If the [sqlite3_blob | blob-handle] passed as the first argument
  2413. ** was not opened for writing (the flags parameter to [sqlite3_blob_open()]
  2414. *** was zero), this function returns [SQLITE_READONLY].
  2415. **
  2416. ** This function may only modify the contents of the blob; it is
  2417. ** not possible to increase the size of a blob using this API.
  2418. ** If offset iOffset is less than n bytes from the end of the blob, 
  2419. ** [SQLITE_ERROR] is returned and no data is written.  If n is
  2420. ** less than zero [SQLITE_ERROR] is returned and no data is written.
  2421. **
  2422. ** On success, SQLITE_OK is returned. Otherwise, an 
  2423. ** [error code] or an [extended error code] is returned.
  2424. **
  2425. ** INVARIANTS:
  2426. **
  2427. ** {F17873} The [sqlite3_blob_write(P,Z,N,X)] interface writes N bytes
  2428. **          from buffer Z into
  2429. **          the blob that [sqlite3_blob] object P refers to
  2430. **          beginning at an offset of X into the blob.
  2431. **
  2432. ** {F17875} The [sqlite3_blob_write(P,Z,N,X)] interface returns
  2433. **          [SQLITE_READONLY] if the [sqlite3_blob] object P was
  2434. **          [sqlite3_blob_open | opened] for reading only.
  2435. **
  2436. ** {F17876} In [sqlite3_blob_write(P,Z,N,X)] if the size of the blob
  2437. **          is less than N+X bytes, then the function returns [SQLITE_ERROR]
  2438. **          and nothing is written into the blob.
  2439. **
  2440. ** {F17879} In [sqlite3_blob_write(P,Z,N,X)] if X or N is less than zero
  2441. **          then the function returns [SQLITE_ERROR]
  2442. **          and nothing is written into the blob.
  2443. **
  2444. ** {F17882} The [sqlite3_blob_write(P,Z,N,X)] interface returns [SQLITE_OK]
  2445. **          if N bytes where successfully written into blob.
  2446. **
  2447. ** {F17885} If the requested write could not be completed,
  2448. **          the [sqlite3_blob_write(P,Z,N,X)] interface returns an
  2449. **          appropriate [error code] or [extended error code].
  2450. **
  2451. ** {F17888} If an error occurs during evaluation of [sqlite3_blob_write(D,...)]
  2452. **          then subsequent calls to [sqlite3_errcode(D)],
  2453. **          [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] will return
  2454. **          information approprate for that error.
  2455. */
  2456. int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset);
  2457. /*
  2458. ** CAPI3REF:  Virtual File System Objects {F11200}
  2459. **
  2460. ** A virtual filesystem (VFS) is an [sqlite3_vfs] object
  2461. ** that SQLite uses to interact
  2462. ** with the underlying operating system.  Most SQLite builds come with a
  2463. ** single default VFS that is appropriate for the host computer.
  2464. ** New VFSes can be registered and existing VFSes can be unregistered.
  2465. ** The following interfaces are provided.
  2466. **
  2467. ** The sqlite3_vfs_find() interface returns a pointer to 
  2468. ** a VFS given its name.  Names are case sensitive.
  2469. ** Names are zero-terminated UTF-8 strings.
  2470. ** If there is no match, a NULL
  2471. ** pointer is returned.  If zVfsName is NULL then the default 
  2472. ** VFS is returned. 
  2473. **
  2474. ** New VFSes are registered with sqlite3_vfs_register().
  2475. ** Each new VFS becomes the default VFS if the makeDflt flag is set.
  2476. ** The same VFS can be registered multiple times without injury.
  2477. ** To make an existing VFS into the default VFS, register it again
  2478. ** with the makeDflt flag set.  If two different VFSes with the
  2479. ** same name are registered, the behavior is undefined.  If a
  2480. ** VFS is registered with a name that is NULL or an empty string,
  2481. ** then the behavior is undefined.
  2482. ** 
  2483. ** Unregister a VFS with the sqlite3_vfs_unregister() interface.
  2484. ** If the default VFS is unregistered, another VFS is chosen as
  2485. ** the default.  The choice for the new VFS is arbitrary.
  2486. **
  2487. ** INVARIANTS:
  2488. **
  2489. ** {F11203} The [sqlite3_vfs_find(N)] interface returns a pointer to the
  2490. **          registered [sqlite3_vfs] object whose name exactly matches
  2491. **          the zero-terminated UTF-8 string N, or it returns NULL if
  2492. **          there is no match.
  2493. **
  2494. ** {F11206} If the N parameter to [sqlite3_vfs_find(N)] is NULL then
  2495. **          the function returns a pointer to the default [sqlite3_vfs]
  2496. **          object if there is one, or NULL if there is no default 
  2497. **          [sqlite3_vfs] object.
  2498. **
  2499. ** {F11209} The [sqlite3_vfs_register(P,F)] interface registers the
  2500. **          well-formed [sqlite3_vfs] object P using the name given
  2501. **          by the zName field of the object.
  2502. **
  2503. ** {F11212} Using the [sqlite3_vfs_register(P,F)] interface to register
  2504. **          the same [sqlite3_vfs] object multiple times is a harmless no-op.
  2505. **
  2506. ** {F11215} The [sqlite3_vfs_register(P,F)] interface makes the
  2507. **          the [sqlite3_vfs] object P the default [sqlite3_vfs] object
  2508. **          if F is non-zero.
  2509. **
  2510. ** {F11218} The [sqlite3_vfs_unregister(P)] interface unregisters the
  2511. **          [sqlite3_vfs] object P so that it is no longer returned by
  2512. **          subsequent calls to [sqlite3_vfs_find()].
  2513. */
  2514. sqlite3_vfs *sqlite3_vfs_find(const char *zVfsName);
  2515. int sqlite3_vfs_register(sqlite3_vfs*, int makeDflt);
  2516. int sqlite3_vfs_unregister(sqlite3_vfs*);
  2517. /*
  2518. ** CAPI3REF: Mutexes {F17000}
  2519. **
  2520. ** The SQLite core uses these routines for thread
  2521. ** synchronization.  Though they are intended for internal
  2522. ** use by SQLite, code that links against SQLite is
  2523. ** permitted to use any of these routines.
  2524. **
  2525. ** The SQLite source code contains multiple implementations 
  2526. ** of these mutex routines.  An appropriate implementation
  2527. ** is selected automatically at compile-time.  The following
  2528. ** implementations are available in the SQLite core:
  2529. **
  2530. ** <ul>
  2531. ** <li>   SQLITE_MUTEX_OS2
  2532. ** <li>   SQLITE_MUTEX_PTHREAD
  2533. ** <li>   SQLITE_MUTEX_W32
  2534. ** <li>   SQLITE_MUTEX_NOOP
  2535. ** </ul>
  2536. **
  2537. ** The SQLITE_MUTEX_NOOP implementation is a set of routines 
  2538. ** that does no real locking and is appropriate for use in 
  2539. ** a single-threaded application.  The SQLITE_MUTEX_OS2,
  2540. ** SQLITE_MUTEX_PTHREAD, and SQLITE_MUTEX_W32 implementations
  2541. ** are appropriate for use on os/2, unix, and windows.
  2542. ** 
  2543. ** If SQLite is compiled with the SQLITE_MUTEX_APPDEF preprocessor
  2544. ** macro defined (with "-DSQLITE_MUTEX_APPDEF=1"), then no mutex
  2545. ** implementation is included with the library.  The
  2546. ** mutex interface routines defined here become external
  2547. ** references in the SQLite library for which implementations
  2548. ** must be provided by the application.  This facility allows an
  2549. ** application that links against SQLite to provide its own mutex
  2550. ** implementation without having to modify the SQLite core.
  2551. **
  2552. ** {F17011} The sqlite3_mutex_alloc() routine allocates a new
  2553. ** mutex and returns a pointer to it. {F17012} If it returns NULL
  2554. ** that means that a mutex could not be allocated. {F17013} SQLite
  2555. ** will unwind its stack and return an error. {F17014} The argument
  2556. ** to sqlite3_mutex_alloc() is one of these integer constants:
  2557. **
  2558. ** <ul>
  2559. ** <li>  SQLITE_MUTEX_FAST
  2560. ** <li>  SQLITE_MUTEX_RECURSIVE
  2561. ** <li>  SQLITE_MUTEX_STATIC_MASTER
  2562. ** <li>  SQLITE_MUTEX_STATIC_MEM
  2563. ** <li>  SQLITE_MUTEX_STATIC_MEM2
  2564. ** <li>  SQLITE_MUTEX_STATIC_PRNG
  2565. ** <li>  SQLITE_MUTEX_STATIC_LRU
  2566. ** <li>  SQLITE_MUTEX_STATIC_LRU2
  2567. ** </ul> {END}
  2568. **
  2569. ** {F17015} The first two constants cause sqlite3_mutex_alloc() to create
  2570. ** a new mutex.  The new mutex is recursive when SQLITE_MUTEX_RECURSIVE
  2571. ** is used but not necessarily so when SQLITE_MUTEX_FAST is used. {END}
  2572. ** The mutex implementation does not need to make a distinction
  2573. ** between SQLITE_MUTEX_RECURSIVE and SQLITE_MUTEX_FAST if it does
  2574. ** not want to.  {F17016} But SQLite will only request a recursive mutex in
  2575. ** cases where it really needs one.  {END} If a faster non-recursive mutex
  2576. ** implementation is available on the host platform, the mutex subsystem
  2577. ** might return such a mutex in response to SQLITE_MUTEX_FAST.
  2578. **
  2579. ** {F17017} The other allowed parameters to sqlite3_mutex_alloc() each return
  2580. ** a pointer to a static preexisting mutex. {END}  Four static mutexes are
  2581. ** used by the current version of SQLite.  Future versions of SQLite
  2582. ** may add additional static mutexes.  Static mutexes are for internal
  2583. ** use by SQLite only.  Applications that use SQLite mutexes should
  2584. ** use only the dynamic mutexes returned by SQLITE_MUTEX_FAST or
  2585. ** SQLITE_MUTEX_RECURSIVE.
  2586. **
  2587. ** {F17018} Note that if one of the dynamic mutex parameters (SQLITE_MUTEX_FAST
  2588. ** or SQLITE_MUTEX_RECURSIVE) is used then sqlite3_mutex_alloc()
  2589. ** returns a different mutex on every call.  {F17034} But for the static 
  2590. ** mutex types, the same mutex is returned on every call that has
  2591. ** the same type number. {END}
  2592. **
  2593. ** {F17019} The sqlite3_mutex_free() routine deallocates a previously
  2594. ** allocated dynamic mutex. {F17020} SQLite is careful to deallocate every
  2595. ** dynamic mutex that it allocates. {U17021} The dynamic mutexes must not be in 
  2596. ** use when they are deallocated. {U17022} Attempting to deallocate a static
  2597. ** mutex results in undefined behavior. {F17023} SQLite never deallocates
  2598. ** a static mutex. {END}
  2599. **
  2600. ** The sqlite3_mutex_enter() and sqlite3_mutex_try() routines attempt
  2601. ** to enter a mutex. {F17024} If another thread is already within the mutex,
  2602. ** sqlite3_mutex_enter() will block and sqlite3_mutex_try() will return
  2603. ** SQLITE_BUSY. {F17025}  The sqlite3_mutex_try() interface returns SQLITE_OK
  2604. ** upon successful entry.  {F17026} Mutexes created using
  2605. ** SQLITE_MUTEX_RECURSIVE can be entered multiple times by the same thread.
  2606. ** {F17027} In such cases the,
  2607. ** mutex must be exited an equal number of times before another thread
  2608. ** can enter.  {U17028} If the same thread tries to enter any other
  2609. ** kind of mutex more than once, the behavior is undefined.
  2610. ** {F17029} SQLite will never exhibit
  2611. ** such behavior in its own use of mutexes. {END}
  2612. **
  2613. ** Some systems (ex: windows95) do not the operation implemented by
  2614. ** sqlite3_mutex_try().  On those systems, sqlite3_mutex_try() will
  2615. ** always return SQLITE_BUSY.  {F17030} The SQLite core only ever uses
  2616. ** sqlite3_mutex_try() as an optimization so this is acceptable behavior. {END}
  2617. **
  2618. ** {F17031} The sqlite3_mutex_leave() routine exits a mutex that was
  2619. ** previously entered by the same thread.  {U17032} The behavior
  2620. ** is undefined if the mutex is not currently entered by the
  2621. ** calling thread or is not currently allocated.  {F17033} SQLite will
  2622. ** never do either. {END}
  2623. **
  2624. ** See also: [sqlite3_mutex_held()] and [sqlite3_mutex_notheld()].
  2625. */
  2626. sqlite3_mutex *sqlite3_mutex_alloc(int);
  2627. void sqlite3_mutex_free(sqlite3_mutex*);
  2628. void sqlite3_mutex_enter(sqlite3_mutex*);
  2629. int sqlite3_mutex_try(sqlite3_mutex*);
  2630. void sqlite3_mutex_leave(sqlite3_mutex*);
  2631. /*
  2632. ** CAPI3REF: Mutex Verifcation Routines {F17080}
  2633. **
  2634. ** The sqlite3_mutex_held() and sqlite3_mutex_notheld() routines
  2635. ** are intended for use inside assert() statements. {F17081} The SQLite core
  2636. ** never uses these routines except inside an assert() and applications
  2637. ** are advised to follow the lead of the core.  {F17082} The core only
  2638. ** provides implementations for these routines when it is compiled
  2639. ** with the SQLITE_DEBUG flag.  {U17087} External mutex implementations
  2640. ** are only required to provide these routines if SQLITE_DEBUG is
  2641. ** defined and if NDEBUG is not defined.
  2642. **
  2643. ** {F17083} These routines should return true if the mutex in their argument
  2644. ** is held or not held, respectively, by the calling thread. {END}
  2645. **
  2646. ** {X17084} The implementation is not required to provided versions of these
  2647. ** routines that actually work.
  2648. ** If the implementation does not provide working
  2649. ** versions of these routines, it should at least provide stubs
  2650. ** that always return true so that one does not get spurious
  2651. ** assertion failures. {END}
  2652. **
  2653. ** {F17085} If the argument to sqlite3_mutex_held() is a NULL pointer then
  2654. ** the routine should return 1.  {END} This seems counter-intuitive since
  2655. ** clearly the mutex cannot be held if it does not exist.  But the
  2656. ** the reason the mutex does not exist is because the build is not
  2657. ** using mutexes.  And we do not want the assert() containing the
  2658. ** call to sqlite3_mutex_held() to fail, so a non-zero return is
  2659. ** the appropriate thing to do.  {F17086} The sqlite3_mutex_notheld() 
  2660. ** interface should also return 1 when given a NULL pointer.
  2661. */
  2662. int sqlite3_mutex_held(sqlite3_mutex*);
  2663. int sqlite3_mutex_notheld(sqlite3_mutex*);
  2664. /*
  2665. ** CAPI3REF: Mutex Types {F17001}
  2666. **
  2667. ** {F17002} The [sqlite3_mutex_alloc()] interface takes a single argument
  2668. ** which is one of these integer constants. {END}
  2669. */
  2670. #define SQLITE_MUTEX_FAST             0
  2671. #define SQLITE_MUTEX_RECURSIVE        1
  2672. #define SQLITE_MUTEX_STATIC_MASTER    2
  2673. #define SQLITE_MUTEX_STATIC_MEM       3  /* sqlite3_malloc() */
  2674. #define SQLITE_MUTEX_STATIC_MEM2      4  /* sqlite3_release_memory() */
  2675. #define SQLITE_MUTEX_STATIC_PRNG      5  /* sqlite3_random() */
  2676. #define SQLITE_MUTEX_STATIC_LRU       6  /* lru page list */
  2677. #define SQLITE_MUTEX_STATIC_LRU2      7  /* lru page list */
  2678. /*
  2679. ** CAPI3REF: Low-Level Control Of Database Files {F11300}
  2680. **
  2681. ** {F11301} The [sqlite3_file_control()] interface makes a direct call to the
  2682. ** xFileControl method for the [sqlite3_io_methods] object associated
  2683. ** with a particular database identified by the second argument. {F11302} The
  2684. ** name of the database is the name assigned to the database by the
  2685. ** <a href="lang_attach.html">ATTACH</a> SQL command that opened the
  2686. ** database. {F11303} To control the main database file, use the name "main"
  2687. ** or a NULL pointer. {F11304} The third and fourth parameters to this routine
  2688. ** are passed directly through to the second and third parameters of
  2689. ** the xFileControl method.  {F11305} The return value of the xFileControl
  2690. ** method becomes the return value of this routine.
  2691. **
  2692. ** {F11306} If the second parameter (zDbName) does not match the name of any
  2693. ** open database file, then SQLITE_ERROR is returned. {F11307} This error
  2694. ** code is not remembered and will not be recalled by [sqlite3_errcode()]
  2695. ** or [sqlite3_errmsg()]. {U11308} The underlying xFileControl method might
  2696. ** also return SQLITE_ERROR.  {U11309} There is no way to distinguish between
  2697. ** an incorrect zDbName and an SQLITE_ERROR return from the underlying
  2698. ** xFileControl method. {END}
  2699. **
  2700. ** See also: [SQLITE_FCNTL_LOCKSTATE]
  2701. */
  2702. int sqlite3_file_control(sqlite3*, const char *zDbName, int op, void*);
  2703. /*
  2704. ** CAPI3REF: Testing Interface {F11400}
  2705. **
  2706. ** The sqlite3_test_control() interface is used to read out internal
  2707. ** state of SQLite and to inject faults into SQLite for testing
  2708. ** purposes.  The first parameter a operation code that determines
  2709. ** the number, meaning, and operation of all subsequent parameters.
  2710. **
  2711. ** This interface is not for use by applications.  It exists solely
  2712. ** for verifying the correct operation of the SQLite library.  Depending
  2713. ** on how the SQLite library is compiled, this interface might not exist.
  2714. **
  2715. ** The details of the operation codes, their meanings, the parameters
  2716. ** they take, and what they do are all subject to change without notice.
  2717. ** Unlike most of the SQLite API, this function is not guaranteed to
  2718. ** operate consistently from one release to the next.
  2719. */
  2720. int sqlite3_test_control(int op, ...);
  2721. /*
  2722. ** CAPI3REF: Testing Interface Operation Codes {F11410}
  2723. **
  2724. ** These constants are the valid operation code parameters used
  2725. ** as the first argument to [sqlite3_test_control()].
  2726. **
  2727. ** These parameters and their meansing are subject to change
  2728. ** without notice.  These values are for testing purposes only.
  2729. ** Applications should not use any of these parameters or the
  2730. ** [sqlite3_test_control()] interface.
  2731. */
  2732. #define SQLITE_TESTCTRL_FAULT_CONFIG             1
  2733. #define SQLITE_TESTCTRL_FAULT_FAILURES           2
  2734. #define SQLITE_TESTCTRL_FAULT_BENIGN_FAILURES    3
  2735. #define SQLITE_TESTCTRL_FAULT_PENDING            4
  2736. #define SQLITE_TESTCTRL_PRNG_SAVE                5
  2737. #define SQLITE_TESTCTRL_PRNG_RESTORE             6
  2738. #define SQLITE_TESTCTRL_PRNG_RESET               7
  2739. #define SQLITE_TESTCTRL_BITVEC_TEST              8
  2740. /*
  2741. ** Undo the hack that converts floating point types to integer for
  2742. ** builds on processors without floating point support.
  2743. */
  2744. #ifdef SQLITE_OMIT_FLOATING_POINT
  2745. # undef double
  2746. #endif
  2747. #ifdef __cplusplus
  2748. }  /* End of the 'extern "C"' block */
  2749. #endif
  2750. #endif