1/*
2** 2007 May 1
3**
4** The author disclaims copyright to this source code. In place of
5** a legal notice, here is a blessing:
6**
7** May you do good and not evil.
8** May you find forgiveness for yourself and forgive others.
9** May you share freely, never taking more than you give.
10**
11*************************************************************************
12**
13** This file contains code used to implement incremental BLOB I/O.
14*/
15
16#include "sqliteInt.h"
17#include "vdbeInt.h"
18
19#ifndef SQLITE_OMIT_INCRBLOB
20
21/*
22** Valid sqlite3_blob* handles point to Incrblob structures.
23*/
24typedef struct Incrblob Incrblob;
25struct Incrblob {
26 int nByte; /* Size of open blob, in bytes */
27 int iOffset; /* Byte offset of blob in cursor data */
28 u16 iCol; /* Table column this handle is open on */
29 BtCursor *pCsr; /* Cursor pointing at blob row */
30 sqlite3_stmt *pStmt; /* Statement holding cursor open */
31 sqlite3 *db; /* The associated database */
32 char *zDb; /* Database name */
33 Table *pTab; /* Table object */
34};
35
36
37/*
38** This function is used by both blob_open() and blob_reopen(). It seeks
39** the b-tree cursor associated with blob handle p to point to row iRow.
40** If successful, SQLITE_OK is returned and subsequent calls to
41** sqlite3_blob_read() or sqlite3_blob_write() access the specified row.
42**
43** If an error occurs, or if the specified row does not exist or does not
44** contain a value of type TEXT or BLOB in the column nominated when the
45** blob handle was opened, then an error code is returned and *pzErr may
46** be set to point to a buffer containing an error message. It is the
47** responsibility of the caller to free the error message buffer using
48** sqlite3DbFree().
49**
50** If an error does occur, then the b-tree cursor is closed. All subsequent
51** calls to sqlite3_blob_read(), blob_write() or blob_reopen() will
52** immediately return SQLITE_ABORT.
53*/
54static int blobSeekToRow(Incrblob *p, sqlite3_int64 iRow, char **pzErr){
55 int rc; /* Error code */
56 char *zErr = 0; /* Error message */
57 Vdbe *v = (Vdbe *)p->pStmt;
58
59 /* Set the value of register r[1] in the SQL statement to integer iRow.
60 ** This is done directly as a performance optimization
61 */
62 v->aMem[1].flags = MEM_Int;
63 v->aMem[1].u.i = iRow;
64
65 /* If the statement has been run before (and is paused at the OP_ResultRow)
66 ** then back it up to the point where it does the OP_NotExists. This could
67 ** have been down with an extra OP_Goto, but simply setting the program
68 ** counter is faster. */
69 if( v->pc>4 ){
70 v->pc = 4;
71 assert( v->aOp[v->pc].opcode==OP_NotExists );
72 rc = sqlite3VdbeExec(v);
73 }else{
74 rc = sqlite3_step(p->pStmt);
75 }
76 if( rc==SQLITE_ROW ){
77 VdbeCursor *pC = v->apCsr[0];
78 u32 type;
79 assert( pC!=0 );
80 assert( pC->eCurType==CURTYPE_BTREE );
81 type = pC->nHdrParsed>p->iCol ? pC->aType[p->iCol] : 0;
82 testcase( pC->nHdrParsed==p->iCol );
83 testcase( pC->nHdrParsed==p->iCol+1 );
84 if( type<12 ){
85 zErr = sqlite3MPrintf(p->db, "cannot open value of type %s",
86 type==0?"null": type==7?"real": "integer"
87 );
88 rc = SQLITE_ERROR;
89 sqlite3_finalize(p->pStmt);
90 p->pStmt = 0;
91 }else{
92 p->iOffset = pC->aType[p->iCol + pC->nField];
93 p->nByte = sqlite3VdbeSerialTypeLen(type);
94 p->pCsr = pC->uc.pCursor;
95 sqlite3BtreeIncrblobCursor(p->pCsr);
96 }
97 }
98
99 if( rc==SQLITE_ROW ){
100 rc = SQLITE_OK;
101 }else if( p->pStmt ){
102 rc = sqlite3_finalize(p->pStmt);
103 p->pStmt = 0;
104 if( rc==SQLITE_OK ){
105 zErr = sqlite3MPrintf(p->db, "no such rowid: %lld", iRow);
106 rc = SQLITE_ERROR;
107 }else{
108 zErr = sqlite3MPrintf(p->db, "%s", sqlite3_errmsg(p->db));
109 }
110 }
111
112 assert( rc!=SQLITE_OK || zErr==0 );
113 assert( rc!=SQLITE_ROW && rc!=SQLITE_DONE );
114
115 *pzErr = zErr;
116 return rc;
117}
118
119/*
120** Open a blob handle.
121*/
122int sqlite3_blob_open(
123 sqlite3* db, /* The database connection */
124 const char *zDb, /* The attached database containing the blob */
125 const char *zTable, /* The table containing the blob */
126 const char *zColumn, /* The column containing the blob */
127 sqlite_int64 iRow, /* The row containing the glob */
128 int wrFlag, /* True -> read/write access, false -> read-only */
129 sqlite3_blob **ppBlob /* Handle for accessing the blob returned here */
130){
131 int nAttempt = 0;
132 int iCol; /* Index of zColumn in row-record */
133 int rc = SQLITE_OK;
134 char *zErr = 0;
135 Table *pTab;
136 Incrblob *pBlob = 0;
137 Parse sParse;
138
139#ifdef SQLITE_ENABLE_API_ARMOR
140 if( ppBlob==0 ){
141 return SQLITE_MISUSE_BKPT;
142 }
143#endif
144 *ppBlob = 0;
145#ifdef SQLITE_ENABLE_API_ARMOR
146 if( !sqlite3SafetyCheckOk(db) || zTable==0 ){
147 return SQLITE_MISUSE_BKPT;
148 }
149#endif
150 wrFlag = !!wrFlag; /* wrFlag = (wrFlag ? 1 : 0); */
151
152 sqlite3_mutex_enter(db->mutex);
153
154 pBlob = (Incrblob *)sqlite3DbMallocZero(db, sizeof(Incrblob));
155 while(1){
156 sqlite3ParseObjectInit(&sParse,db);
157 if( !pBlob ) goto blob_open_out;
158 sqlite3DbFree(db, zErr);
159 zErr = 0;
160
161 sqlite3BtreeEnterAll(db);
162 pTab = sqlite3LocateTable(&sParse, 0, zTable, zDb);
163 if( pTab && IsVirtual(pTab) ){
164 pTab = 0;
165 sqlite3ErrorMsg(&sParse, "cannot open virtual table: %s", zTable);
166 }
167 if( pTab && !HasRowid(pTab) ){
168 pTab = 0;
169 sqlite3ErrorMsg(&sParse, "cannot open table without rowid: %s", zTable);
170 }
171#ifndef SQLITE_OMIT_VIEW
172 if( pTab && IsView(pTab) ){
173 pTab = 0;
174 sqlite3ErrorMsg(&sParse, "cannot open view: %s", zTable);
175 }
176#endif
177 if( !pTab ){
178 if( sParse.zErrMsg ){
179 sqlite3DbFree(db, zErr);
180 zErr = sParse.zErrMsg;
181 sParse.zErrMsg = 0;
182 }
183 rc = SQLITE_ERROR;
184 sqlite3BtreeLeaveAll(db);
185 goto blob_open_out;
186 }
187 pBlob->pTab = pTab;
188 pBlob->zDb = db->aDb[sqlite3SchemaToIndex(db, pTab->pSchema)].zDbSName;
189
190 /* Now search pTab for the exact column. */
191 for(iCol=0; iCol<pTab->nCol; iCol++) {
192 if( sqlite3StrICmp(pTab->aCol[iCol].zCnName, zColumn)==0 ){
193 break;
194 }
195 }
196 if( iCol==pTab->nCol ){
197 sqlite3DbFree(db, zErr);
198 zErr = sqlite3MPrintf(db, "no such column: \"%s\"", zColumn);
199 rc = SQLITE_ERROR;
200 sqlite3BtreeLeaveAll(db);
201 goto blob_open_out;
202 }
203
204 /* If the value is being opened for writing, check that the
205 ** column is not indexed, and that it is not part of a foreign key.
206 */
207 if( wrFlag ){
208 const char *zFault = 0;
209 Index *pIdx;
210#ifndef SQLITE_OMIT_FOREIGN_KEY
211 if( db->flags&SQLITE_ForeignKeys ){
212 /* Check that the column is not part of an FK child key definition. It
213 ** is not necessary to check if it is part of a parent key, as parent
214 ** key columns must be indexed. The check below will pick up this
215 ** case. */
216 FKey *pFKey;
217 assert( IsOrdinaryTable(pTab) );
218 for(pFKey=pTab->u.tab.pFKey; pFKey; pFKey=pFKey->pNextFrom){
219 int j;
220 for(j=0; j<pFKey->nCol; j++){
221 if( pFKey->aCol[j].iFrom==iCol ){
222 zFault = "foreign key";
223 }
224 }
225 }
226 }
227#endif
228 for(pIdx=pTab->pIndex; pIdx; pIdx=pIdx->pNext){
229 int j;
230 for(j=0; j<pIdx->nKeyCol; j++){
231 /* FIXME: Be smarter about indexes that use expressions */
232 if( pIdx->aiColumn[j]==iCol || pIdx->aiColumn[j]==XN_EXPR ){
233 zFault = "indexed";
234 }
235 }
236 }
237 if( zFault ){
238 sqlite3DbFree(db, zErr);
239 zErr = sqlite3MPrintf(db, "cannot open %s column for writing", zFault);
240 rc = SQLITE_ERROR;
241 sqlite3BtreeLeaveAll(db);
242 goto blob_open_out;
243 }
244 }
245
246 pBlob->pStmt = (sqlite3_stmt *)sqlite3VdbeCreate(&sParse);
247 assert( pBlob->pStmt || db->mallocFailed );
248 if( pBlob->pStmt ){
249
250 /* This VDBE program seeks a btree cursor to the identified
251 ** db/table/row entry. The reason for using a vdbe program instead
252 ** of writing code to use the b-tree layer directly is that the
253 ** vdbe program will take advantage of the various transaction,
254 ** locking and error handling infrastructure built into the vdbe.
255 **
256 ** After seeking the cursor, the vdbe executes an OP_ResultRow.
257 ** Code external to the Vdbe then "borrows" the b-tree cursor and
258 ** uses it to implement the blob_read(), blob_write() and
259 ** blob_bytes() functions.
260 **
261 ** The sqlite3_blob_close() function finalizes the vdbe program,
262 ** which closes the b-tree cursor and (possibly) commits the
263 ** transaction.
264 */
265 static const int iLn = VDBE_OFFSET_LINENO(2);
266 static const VdbeOpList openBlob[] = {
267 {OP_TableLock, 0, 0, 0}, /* 0: Acquire a read or write lock */
268 {OP_OpenRead, 0, 0, 0}, /* 1: Open a cursor */
269 /* blobSeekToRow() will initialize r[1] to the desired rowid */
270 {OP_NotExists, 0, 5, 1}, /* 2: Seek the cursor to rowid=r[1] */
271 {OP_Column, 0, 0, 1}, /* 3 */
272 {OP_ResultRow, 1, 0, 0}, /* 4 */
273 {OP_Halt, 0, 0, 0}, /* 5 */
274 };
275 Vdbe *v = (Vdbe *)pBlob->pStmt;
276 int iDb = sqlite3SchemaToIndex(db, pTab->pSchema);
277 VdbeOp *aOp;
278
279 sqlite3VdbeAddOp4Int(v, OP_Transaction, iDb, wrFlag,
280 pTab->pSchema->schema_cookie,
281 pTab->pSchema->iGeneration);
282 sqlite3VdbeChangeP5(v, 1);
283 assert( sqlite3VdbeCurrentAddr(v)==2 || db->mallocFailed );
284 aOp = sqlite3VdbeAddOpList(v, ArraySize(openBlob), openBlob, iLn);
285
286 /* Make sure a mutex is held on the table to be accessed */
287 sqlite3VdbeUsesBtree(v, iDb);
288
289 if( db->mallocFailed==0 ){
290 assert( aOp!=0 );
291 /* Configure the OP_TableLock instruction */
292#ifdef SQLITE_OMIT_SHARED_CACHE
293 aOp[0].opcode = OP_Noop;
294#else
295 aOp[0].p1 = iDb;
296 aOp[0].p2 = pTab->tnum;
297 aOp[0].p3 = wrFlag;
298 sqlite3VdbeChangeP4(v, 2, pTab->zName, P4_TRANSIENT);
299 }
300 if( db->mallocFailed==0 ){
301#endif
302
303 /* Remove either the OP_OpenWrite or OpenRead. Set the P2
304 ** parameter of the other to pTab->tnum. */
305 if( wrFlag ) aOp[1].opcode = OP_OpenWrite;
306 aOp[1].p2 = pTab->tnum;
307 aOp[1].p3 = iDb;
308
309 /* Configure the number of columns. Configure the cursor to
310 ** think that the table has one more column than it really
311 ** does. An OP_Column to retrieve this imaginary column will
312 ** always return an SQL NULL. This is useful because it means
313 ** we can invoke OP_Column to fill in the vdbe cursors type
314 ** and offset cache without causing any IO.
315 */
316 aOp[1].p4type = P4_INT32;
317 aOp[1].p4.i = pTab->nCol+1;
318 aOp[3].p2 = pTab->nCol;
319
320 sParse.nVar = 0;
321 sParse.nMem = 1;
322 sParse.nTab = 1;
323 sqlite3VdbeMakeReady(v, &sParse);
324 }
325 }
326
327 pBlob->iCol = iCol;
328 pBlob->db = db;
329 sqlite3BtreeLeaveAll(db);
330 if( db->mallocFailed ){
331 goto blob_open_out;
332 }
333 rc = blobSeekToRow(pBlob, iRow, &zErr);
334 if( (++nAttempt)>=SQLITE_MAX_SCHEMA_RETRY || rc!=SQLITE_SCHEMA ) break;
335 sqlite3ParseObjectReset(&sParse);
336 }
337
338blob_open_out:
339 if( rc==SQLITE_OK && db->mallocFailed==0 ){
340 *ppBlob = (sqlite3_blob *)pBlob;
341 }else{
342 if( pBlob && pBlob->pStmt ) sqlite3VdbeFinalize((Vdbe *)pBlob->pStmt);
343 sqlite3DbFree(db, pBlob);
344 }
345 sqlite3ErrorWithMsg(db, rc, (zErr ? "%s" : 0), zErr);
346 sqlite3DbFree(db, zErr);
347 sqlite3ParseObjectReset(&sParse);
348 rc = sqlite3ApiExit(db, rc);
349 sqlite3_mutex_leave(db->mutex);
350 return rc;
351}
352
353/*
354** Close a blob handle that was previously created using
355** sqlite3_blob_open().
356*/
357int sqlite3_blob_close(sqlite3_blob *pBlob){
358 Incrblob *p = (Incrblob *)pBlob;
359 int rc;
360 sqlite3 *db;
361
362 if( p ){
363 sqlite3_stmt *pStmt = p->pStmt;
364 db = p->db;
365 sqlite3_mutex_enter(db->mutex);
366 sqlite3DbFree(db, p);
367 sqlite3_mutex_leave(db->mutex);
368 rc = sqlite3_finalize(pStmt);
369 }else{
370 rc = SQLITE_OK;
371 }
372 return rc;
373}
374
375/*
376** Perform a read or write operation on a blob
377*/
378static int blobReadWrite(
379 sqlite3_blob *pBlob,
380 void *z,
381 int n,
382 int iOffset,
383 int (*xCall)(BtCursor*, u32, u32, void*)
384){
385 int rc;
386 Incrblob *p = (Incrblob *)pBlob;
387 Vdbe *v;
388 sqlite3 *db;
389
390 if( p==0 ) return SQLITE_MISUSE_BKPT;
391 db = p->db;
392 sqlite3_mutex_enter(db->mutex);
393 v = (Vdbe*)p->pStmt;
394
395 if( n<0 || iOffset<0 || ((sqlite3_int64)iOffset+n)>p->nByte ){
396 /* Request is out of range. Return a transient error. */
397 rc = SQLITE_ERROR;
398 }else if( v==0 ){
399 /* If there is no statement handle, then the blob-handle has
400 ** already been invalidated. Return SQLITE_ABORT in this case.
401 */
402 rc = SQLITE_ABORT;
403 }else{
404 /* Call either BtreeData() or BtreePutData(). If SQLITE_ABORT is
405 ** returned, clean-up the statement handle.
406 */
407 assert( db == v->db );
408 sqlite3BtreeEnterCursor(p->pCsr);
409
410#ifdef SQLITE_ENABLE_PREUPDATE_HOOK
411 if( xCall==sqlite3BtreePutData && db->xPreUpdateCallback ){
412 /* If a pre-update hook is registered and this is a write cursor,
413 ** invoke it here.
414 **
415 ** TODO: The preupdate-hook is passed SQLITE_DELETE, even though this
416 ** operation should really be an SQLITE_UPDATE. This is probably
417 ** incorrect, but is convenient because at this point the new.* values
418 ** are not easily obtainable. And for the sessions module, an
419 ** SQLITE_UPDATE where the PK columns do not change is handled in the
420 ** same way as an SQLITE_DELETE (the SQLITE_DELETE code is actually
421 ** slightly more efficient). Since you cannot write to a PK column
422 ** using the incremental-blob API, this works. For the sessions module
423 ** anyhow.
424 */
425 sqlite3_int64 iKey;
426 iKey = sqlite3BtreeIntegerKey(p->pCsr);
427 assert( v->apCsr[0]!=0 );
428 assert( v->apCsr[0]->eCurType==CURTYPE_BTREE );
429 sqlite3VdbePreUpdateHook(
430 v, v->apCsr[0], SQLITE_DELETE, p->zDb, p->pTab, iKey, -1, p->iCol
431 );
432 }
433#endif
434
435 rc = xCall(p->pCsr, iOffset+p->iOffset, n, z);
436 sqlite3BtreeLeaveCursor(p->pCsr);
437 if( rc==SQLITE_ABORT ){
438 sqlite3VdbeFinalize(v);
439 p->pStmt = 0;
440 }else{
441 v->rc = rc;
442 }
443 }
444 sqlite3Error(db, rc);
445 rc = sqlite3ApiExit(db, rc);
446 sqlite3_mutex_leave(db->mutex);
447 return rc;
448}
449
450/*
451** Read data from a blob handle.
452*/
453int sqlite3_blob_read(sqlite3_blob *pBlob, void *z, int n, int iOffset){
454 return blobReadWrite(pBlob, z, n, iOffset, sqlite3BtreePayloadChecked);
455}
456
457/*
458** Write data to a blob handle.
459*/
460int sqlite3_blob_write(sqlite3_blob *pBlob, const void *z, int n, int iOffset){
461 return blobReadWrite(pBlob, (void *)z, n, iOffset, sqlite3BtreePutData);
462}
463
464/*
465** Query a blob handle for the size of the data.
466**
467** The Incrblob.nByte field is fixed for the lifetime of the Incrblob
468** so no mutex is required for access.
469*/
470int sqlite3_blob_bytes(sqlite3_blob *pBlob){
471 Incrblob *p = (Incrblob *)pBlob;
472 return (p && p->pStmt) ? p->nByte : 0;
473}
474
475/*
476** Move an existing blob handle to point to a different row of the same
477** database table.
478**
479** If an error occurs, or if the specified row does not exist or does not
480** contain a blob or text value, then an error code is returned and the
481** database handle error code and message set. If this happens, then all
482** subsequent calls to sqlite3_blob_xxx() functions (except blob_close())
483** immediately return SQLITE_ABORT.
484*/
485int sqlite3_blob_reopen(sqlite3_blob *pBlob, sqlite3_int64 iRow){
486 int rc;
487 Incrblob *p = (Incrblob *)pBlob;
488 sqlite3 *db;
489
490 if( p==0 ) return SQLITE_MISUSE_BKPT;
491 db = p->db;
492 sqlite3_mutex_enter(db->mutex);
493
494 if( p->pStmt==0 ){
495 /* If there is no statement handle, then the blob-handle has
496 ** already been invalidated. Return SQLITE_ABORT in this case.
497 */
498 rc = SQLITE_ABORT;
499 }else{
500 char *zErr;
501 ((Vdbe*)p->pStmt)->rc = SQLITE_OK;
502 rc = blobSeekToRow(p, iRow, &zErr);
503 if( rc!=SQLITE_OK ){
504 sqlite3ErrorWithMsg(db, rc, (zErr ? "%s" : 0), zErr);
505 sqlite3DbFree(db, zErr);
506 }
507 assert( rc!=SQLITE_SCHEMA );
508 }
509
510 rc = sqlite3ApiExit(db, rc);
511 assert( rc==SQLITE_OK || p->pStmt==0 );
512 sqlite3_mutex_leave(db->mutex);
513 return rc;
514}
515
516#endif /* #ifndef SQLITE_OMIT_INCRBLOB */
517