Many hyperlinks are disabled.
Use anonymous login
to enable hyperlinks.
Overview
Comment: | Document the rules for when an sqlite3_blob object expires. (CVS 5313) |
---|---|
Downloads: | Tarball | ZIP archive |
Timelines: | family | ancestors | descendants | both | trunk |
Files: | files | file ages | folders |
SHA1: |
e1de2287fd9b067f687cb8b427786b87 |
User & Date: | drh 2008-06-26 15:04:58.000 |
Context
2008-06-26
| ||
18:04 | Fix handling of "x IN (...)" and "x NOT IN (...)" expressions when the set contains an SQL NULL value. (CVS 5314) (check-in: d45a97be71 user: danielk1977 tags: trunk) | |
15:04 | Document the rules for when an sqlite3_blob object expires. (CVS 5313) (check-in: e1de2287fd user: drh tags: trunk) | |
10:54 | Change the TEMP_STORE preprocessor symbol to SQLITE_TEMP_STORE. (CVS 5312) (check-in: 1e3b830802 user: danielk1977 tags: trunk) | |
Changes
Changes to src/sqlite.h.in.
︙ | ︙ | |||
26 27 28 29 30 31 32 | ** on how SQLite interfaces are suppose to operate. ** ** The name of this file under configuration management is "sqlite.h.in". ** The makefile makes some minor changes to this file (such as inserting ** the version number) and changes its name to "sqlite3.h" as ** part of the build process. ** | | | 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 | ** on how SQLite interfaces are suppose to operate. ** ** The name of this file under configuration management is "sqlite.h.in". ** The makefile makes some minor changes to this file (such as inserting ** the version number) and changes its name to "sqlite3.h" as ** part of the build process. ** ** @(#) $Id: sqlite.h.in,v 1.359 2008/06/26 15:04:58 drh Exp $ */ #ifndef _SQLITE3_H_ #define _SQLITE3_H_ #include <stdarg.h> /* Needed for the definition of va_list */ /* ** Make sure we can call this stuff from C++. |
︙ | ︙ | |||
5441 5442 5443 5444 5445 5446 5447 5448 5449 5450 | ** ** On success, [SQLITE_OK] is returned and the new [BLOB handle] is written ** to *ppBlob. Otherwise an [error code] is returned and any value written ** to *ppBlob should not be used by the caller. ** This function sets the [database connection] error code and message ** accessible via [sqlite3_errcode()] and [sqlite3_errmsg()]. ** ** INVARIANTS: ** ** {F17813} A successful invocation of the [sqlite3_blob_open(D,B,T,C,R,F,P)] | > > > > > > > > > > > | | > | | | > | | > > > > > | 5441 5442 5443 5444 5445 5446 5447 5448 5449 5450 5451 5452 5453 5454 5455 5456 5457 5458 5459 5460 5461 5462 5463 5464 5465 5466 5467 5468 5469 5470 5471 5472 5473 5474 5475 5476 5477 5478 5479 5480 5481 5482 5483 5484 5485 5486 5487 5488 5489 5490 5491 5492 | ** ** On success, [SQLITE_OK] is returned and the new [BLOB handle] is written ** to *ppBlob. Otherwise an [error code] is returned and any value written ** to *ppBlob should not be used by the caller. ** This function sets the [database connection] error code and message ** accessible via [sqlite3_errcode()] and [sqlite3_errmsg()]. ** ** If the row that a BLOB handle points to is modified by an ** [UPDATE], [DELETE], or by [ON CONFLICT] side-effects ** then the BLOB handle is marked as "expired". ** This is true if any column of the row is changed, even a column ** other than the one the BLOB handle is open on. ** Calls to [sqlite3_blob_read()] and [sqlite3_blob_write()] for ** a expired BLOB handle fail with an return code of [SQLITE_ABORT]. ** Changes written into a BLOB prior to the BLOB expiring are not ** rollback by the expiration of the BLOB. Such changes will eventually ** commit if the transaction continues to completion. ** ** INVARIANTS: ** ** {F17813} A successful invocation of the [sqlite3_blob_open(D,B,T,C,R,F,P)] ** interface shall open an [sqlite3_blob] object P on the BLOB ** in column C of the table T in the database B on ** the [database connection] D. ** ** {F17814} A successful invocation of [sqlite3_blob_open(D,...)] shall start ** a new transaction on the [database connection] D if that ** connection is not already in a transaction. ** ** {F17816} The [sqlite3_blob_open(D,B,T,C,R,F,P)] interface shall open ** the BLOB for read and write access if and only if the F ** parameter is non-zero. ** ** {F17819} The [sqlite3_blob_open()] interface shall return [SQLITE_OK] on ** success and an appropriate [error code] on failure. ** ** {F17821} If an error occurs during evaluation of [sqlite3_blob_open(D,...)] ** then subsequent calls to [sqlite3_errcode(D)], ** [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] shall return ** information appropriate for that error. ** ** {F17824} If any column in the row that a [sqlite3_blob] has open is ** changed by a separate [UPDATE] or [DELETE] statement or by ** an [ON CONFLICT] side effect, then the [sqlite3_blob] shall ** be marked as invalid. */ int sqlite3_blob_open( sqlite3*, const char *zDb, const char *zTable, const char *zColumn, sqlite3_int64 iRow, |
︙ | ︙ | |||
5502 5503 5504 5505 5506 5507 5508 | ** ** {F17836} Closing an [sqlite3_blob] object using ** [sqlite3_blob_close()] shall cause the current transaction to ** commit if there are no other open [sqlite3_blob] objects ** or [prepared statements] on the same [database connection] and ** the database connection is in [autocommit mode]. ** | | | 5520 5521 5522 5523 5524 5525 5526 5527 5528 5529 5530 5531 5532 5533 5534 | ** ** {F17836} Closing an [sqlite3_blob] object using ** [sqlite3_blob_close()] shall cause the current transaction to ** commit if there are no other open [sqlite3_blob] objects ** or [prepared statements] on the same [database connection] and ** the database connection is in [autocommit mode]. ** ** {F17839} The [sqlite3_blob_close(P)] interfaces shall close the ** [sqlite3_blob] object P unconditionally, even if ** [sqlite3_blob_close(P)] returns something other than [SQLITE_OK]. */ int sqlite3_blob_close(sqlite3_blob *); /* ** CAPI3REF: Return The Size Of An Open BLOB {F17840} |
︙ | ︙ | |||
5532 5533 5534 5535 5536 5537 5538 5539 5540 5541 5542 5543 5544 | ** This function is used to read data from an open [BLOB handle] into a ** caller-supplied buffer. N bytes of data are copied into buffer Z ** from the open BLOB, starting at offset iOffset. ** ** If offset iOffset is less than N bytes from the end of the BLOB, ** [SQLITE_ERROR] is returned and no data is read. If N or iOffset is ** less than zero, [SQLITE_ERROR] is returned and no data is read. ** ** On success, SQLITE_OK is returned. ** Otherwise, an [error code] or an [extended error code] is returned. ** ** INVARIANTS: ** | > > > | | > | | | | | | | > > > > | | | 5550 5551 5552 5553 5554 5555 5556 5557 5558 5559 5560 5561 5562 5563 5564 5565 5566 5567 5568 5569 5570 5571 5572 5573 5574 5575 5576 5577 5578 5579 5580 5581 5582 5583 5584 5585 5586 5587 5588 5589 5590 5591 5592 5593 5594 5595 5596 5597 5598 5599 | ** This function is used to read data from an open [BLOB handle] into a ** caller-supplied buffer. N bytes of data are copied into buffer Z ** from the open BLOB, starting at offset iOffset. ** ** If offset iOffset is less than N bytes from the end of the BLOB, ** [SQLITE_ERROR] is returned and no data is read. If N or iOffset is ** less than zero, [SQLITE_ERROR] is returned and no data is read. ** ** An attempt to read from an expired [BLOB handle] fails with an ** error code of [SQLITE_ABORT]. ** ** On success, SQLITE_OK is returned. ** Otherwise, an [error code] or an [extended error code] is returned. ** ** INVARIANTS: ** ** {F17853} A successful invocation of [sqlite3_blob_read(P,Z,N,X)] ** shall reads N bytes of data out of the BLOB referenced by ** [BLOB handle] P beginning at offset X and store those bytes ** into buffer Z. ** ** {F17856} In [sqlite3_blob_read(P,Z,N,X)] if the size of the BLOB ** is less than N+X bytes, then the function shall leave the ** Z buffer unchanged and return [SQLITE_ERROR]. ** ** {F17859} In [sqlite3_blob_read(P,Z,N,X)] if X or N is less than zero ** then the function shall leave the Z buffer unchanged ** and return [SQLITE_ERROR]. ** ** {F17862} The [sqlite3_blob_read(P,Z,N,X)] interface shall return [SQLITE_OK] ** if N bytes are successfully read into buffer Z. ** ** {F17863} If the [BLOB handle] P is expired and X and N are within bounds ** then [sqlite3_blob_read(P,Z,N,X)] shall leave the Z buffer ** unchanged and return [SQLITE_ABORT]. ** ** {F17865} If the requested read could not be completed, ** the [sqlite3_blob_read(P,Z,N,X)] interface shall return an ** appropriate [error code] or [extended error code]. ** ** {F17868} If an error occurs during evaluation of [sqlite3_blob_read(P,...)] ** then subsequent calls to [sqlite3_errcode(D)], ** [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] shall return ** information appropriate for that error, where D is the ** [database connection] that was used to open the [BLOB handle] P. */ int sqlite3_blob_read(sqlite3_blob *, void *Z, int N, int iOffset); /* ** CAPI3REF: Write Data Into A BLOB Incrementally {F17870} |
︙ | ︙ | |||
5582 5583 5584 5585 5586 5587 5588 5589 5590 5591 5592 5593 | ** ** This function may only modify the contents of the BLOB; it is ** not possible to increase the size of a BLOB using this API. ** If offset iOffset is less than N bytes from the end of the BLOB, ** [SQLITE_ERROR] is returned and no data is written. If N is ** less than zero [SQLITE_ERROR] is returned and no data is written. ** ** On success, SQLITE_OK is returned. ** Otherwise, an [error code] or an [extended error code] is returned. ** ** INVARIANTS: ** | > > > > > > > | | > | > | | > | > > > | | > > > | | | | | | | | | 5608 5609 5610 5611 5612 5613 5614 5615 5616 5617 5618 5619 5620 5621 5622 5623 5624 5625 5626 5627 5628 5629 5630 5631 5632 5633 5634 5635 5636 5637 5638 5639 5640 5641 5642 5643 5644 5645 5646 5647 5648 5649 5650 5651 5652 5653 5654 5655 5656 5657 5658 5659 5660 5661 5662 5663 5664 5665 5666 5667 5668 | ** ** This function may only modify the contents of the BLOB; it is ** not possible to increase the size of a BLOB using this API. ** If offset iOffset is less than N bytes from the end of the BLOB, ** [SQLITE_ERROR] is returned and no data is written. If N is ** less than zero [SQLITE_ERROR] is returned and no data is written. ** ** An attempt to write to an expired [BLOB handle] fails with an ** error code of [SQLITE_ABORT]. Writes to the BLOB that occurred ** before the [BLOB handle] expired are not rolled back by the ** expiration of the handle, though of course those changes might ** have been overwritten by the statement that expired the BLOB handle ** or by other independent statements. ** ** On success, SQLITE_OK is returned. ** Otherwise, an [error code] or an [extended error code] is returned. ** ** INVARIANTS: ** ** {F17873} A successful invocation of [sqlite3_blob_write(P,Z,N,X)] ** shall write N bytes of data from buffer Z into the BLOB ** referenced by [BLOB handle] P beginning at offset X into ** the BLOB. ** ** {F17874} In the absence of other overridding changes, the changes ** written to a BLOB by [sqlite3_blob_write()] shall ** remain in effect after the associated [BLOB handle] expires. ** ** {F17875} If the [BLOB handle] P was opened for reading only then ** an invocation of [sqlite3_blob_write(P,Z,N,X)] shall leave ** the referenced BLOB unchanged and return [SQLITE_READONLY]. ** ** {F17876} If the size of the BLOB referenced by [BLOB handle] P is ** less than N+X bytes then [sqlite3_blob_write(P,Z,N,X)] shall ** leave the BLOB unchanged and return [SQLITE_ERROR]. ** ** {F17877} If the [BLOB handle] P is expired and X and N are within bounds ** then [sqlite3_blob_read(P,Z,N,X)] shall leave the BLOB ** unchanged and return [SQLITE_ABORT]. ** ** {F17879} If X or N are less than zero then [sqlite3_blob_write(P,Z,N,X)] ** shall leave the BLOB referenced by [BLOB handle] P unchanged ** and return [SQLITE_ERROR]. ** ** {F17882} The [sqlite3_blob_write(P,Z,N,X)] interface shall return ** [SQLITE_OK] if N bytes where successfully written into the BLOB. ** ** {F17885} If the requested write could not be completed, ** the [sqlite3_blob_write(P,Z,N,X)] interface shall return an ** appropriate [error code] or [extended error code]. ** ** {F17888} If an error occurs during evaluation of [sqlite3_blob_write(D,...)] ** then subsequent calls to [sqlite3_errcode(D)], ** [sqlite3_errmsg(D)], and [sqlite3_errmsg16(D)] shall return ** information appropriate for that error. */ int sqlite3_blob_write(sqlite3_blob *, const void *z, int n, int iOffset); /* ** CAPI3REF: Virtual File System Objects {F11200} ** |
︙ | ︙ |