Merge Chromium + Blink git repositories
[chromium-blink-merge.git] / third_party / sqlite / sqlite-src-3080704 / src / vtab.c
blobfaee4ae4788dd59b5fe99fe695712876a5483872
1 /*
2 ** 2006 June 10
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.
11 *************************************************************************
12 ** This file contains code used to help implement virtual tables.
14 #ifndef SQLITE_OMIT_VIRTUALTABLE
15 #include "sqliteInt.h"
18 ** Before a virtual table xCreate() or xConnect() method is invoked, the
19 ** sqlite3.pVtabCtx member variable is set to point to an instance of
20 ** this struct allocated on the stack. It is used by the implementation of
21 ** the sqlite3_declare_vtab() and sqlite3_vtab_config() APIs, both of which
22 ** are invoked only from within xCreate and xConnect methods.
24 struct VtabCtx {
25 VTable *pVTable; /* The virtual table being constructed */
26 Table *pTab; /* The Table object to which the virtual table belongs */
30 ** The actual function that does the work of creating a new module.
31 ** This function implements the sqlite3_create_module() and
32 ** sqlite3_create_module_v2() interfaces.
34 static int createModule(
35 sqlite3 *db, /* Database in which module is registered */
36 const char *zName, /* Name assigned to this module */
37 const sqlite3_module *pModule, /* The definition of the module */
38 void *pAux, /* Context pointer for xCreate/xConnect */
39 void (*xDestroy)(void *) /* Module destructor function */
41 int rc = SQLITE_OK;
42 int nName;
44 sqlite3_mutex_enter(db->mutex);
45 nName = sqlite3Strlen30(zName);
46 if( sqlite3HashFind(&db->aModule, zName) ){
47 rc = SQLITE_MISUSE_BKPT;
48 }else{
49 Module *pMod;
50 pMod = (Module *)sqlite3DbMallocRaw(db, sizeof(Module) + nName + 1);
51 if( pMod ){
52 Module *pDel;
53 char *zCopy = (char *)(&pMod[1]);
54 memcpy(zCopy, zName, nName+1);
55 pMod->zName = zCopy;
56 pMod->pModule = pModule;
57 pMod->pAux = pAux;
58 pMod->xDestroy = xDestroy;
59 pDel = (Module *)sqlite3HashInsert(&db->aModule,zCopy,(void*)pMod);
60 assert( pDel==0 || pDel==pMod );
61 if( pDel ){
62 db->mallocFailed = 1;
63 sqlite3DbFree(db, pDel);
67 rc = sqlite3ApiExit(db, rc);
68 if( rc!=SQLITE_OK && xDestroy ) xDestroy(pAux);
70 sqlite3_mutex_leave(db->mutex);
71 return rc;
76 ** External API function used to create a new virtual-table module.
78 int sqlite3_create_module(
79 sqlite3 *db, /* Database in which module is registered */
80 const char *zName, /* Name assigned to this module */
81 const sqlite3_module *pModule, /* The definition of the module */
82 void *pAux /* Context pointer for xCreate/xConnect */
84 return createModule(db, zName, pModule, pAux, 0);
88 ** External API function used to create a new virtual-table module.
90 int sqlite3_create_module_v2(
91 sqlite3 *db, /* Database in which module is registered */
92 const char *zName, /* Name assigned to this module */
93 const sqlite3_module *pModule, /* The definition of the module */
94 void *pAux, /* Context pointer for xCreate/xConnect */
95 void (*xDestroy)(void *) /* Module destructor function */
97 return createModule(db, zName, pModule, pAux, xDestroy);
101 ** Lock the virtual table so that it cannot be disconnected.
102 ** Locks nest. Every lock should have a corresponding unlock.
103 ** If an unlock is omitted, resources leaks will occur.
105 ** If a disconnect is attempted while a virtual table is locked,
106 ** the disconnect is deferred until all locks have been removed.
108 void sqlite3VtabLock(VTable *pVTab){
109 pVTab->nRef++;
114 ** pTab is a pointer to a Table structure representing a virtual-table.
115 ** Return a pointer to the VTable object used by connection db to access
116 ** this virtual-table, if one has been created, or NULL otherwise.
118 VTable *sqlite3GetVTable(sqlite3 *db, Table *pTab){
119 VTable *pVtab;
120 assert( IsVirtual(pTab) );
121 for(pVtab=pTab->pVTable; pVtab && pVtab->db!=db; pVtab=pVtab->pNext);
122 return pVtab;
126 ** Decrement the ref-count on a virtual table object. When the ref-count
127 ** reaches zero, call the xDisconnect() method to delete the object.
129 void sqlite3VtabUnlock(VTable *pVTab){
130 sqlite3 *db = pVTab->db;
132 assert( db );
133 assert( pVTab->nRef>0 );
134 assert( db->magic==SQLITE_MAGIC_OPEN || db->magic==SQLITE_MAGIC_ZOMBIE );
136 pVTab->nRef--;
137 if( pVTab->nRef==0 ){
138 sqlite3_vtab *p = pVTab->pVtab;
139 if( p ){
140 p->pModule->xDisconnect(p);
142 sqlite3DbFree(db, pVTab);
147 ** Table p is a virtual table. This function moves all elements in the
148 ** p->pVTable list to the sqlite3.pDisconnect lists of their associated
149 ** database connections to be disconnected at the next opportunity.
150 ** Except, if argument db is not NULL, then the entry associated with
151 ** connection db is left in the p->pVTable list.
153 static VTable *vtabDisconnectAll(sqlite3 *db, Table *p){
154 VTable *pRet = 0;
155 VTable *pVTable = p->pVTable;
156 p->pVTable = 0;
158 /* Assert that the mutex (if any) associated with the BtShared database
159 ** that contains table p is held by the caller. See header comments
160 ** above function sqlite3VtabUnlockList() for an explanation of why
161 ** this makes it safe to access the sqlite3.pDisconnect list of any
162 ** database connection that may have an entry in the p->pVTable list.
164 assert( db==0 || sqlite3SchemaMutexHeld(db, 0, p->pSchema) );
166 while( pVTable ){
167 sqlite3 *db2 = pVTable->db;
168 VTable *pNext = pVTable->pNext;
169 assert( db2 );
170 if( db2==db ){
171 pRet = pVTable;
172 p->pVTable = pRet;
173 pRet->pNext = 0;
174 }else{
175 pVTable->pNext = db2->pDisconnect;
176 db2->pDisconnect = pVTable;
178 pVTable = pNext;
181 assert( !db || pRet );
182 return pRet;
186 ** Table *p is a virtual table. This function removes the VTable object
187 ** for table *p associated with database connection db from the linked
188 ** list in p->pVTab. It also decrements the VTable ref count. This is
189 ** used when closing database connection db to free all of its VTable
190 ** objects without disturbing the rest of the Schema object (which may
191 ** be being used by other shared-cache connections).
193 void sqlite3VtabDisconnect(sqlite3 *db, Table *p){
194 VTable **ppVTab;
196 assert( IsVirtual(p) );
197 assert( sqlite3BtreeHoldsAllMutexes(db) );
198 assert( sqlite3_mutex_held(db->mutex) );
200 for(ppVTab=&p->pVTable; *ppVTab; ppVTab=&(*ppVTab)->pNext){
201 if( (*ppVTab)->db==db ){
202 VTable *pVTab = *ppVTab;
203 *ppVTab = pVTab->pNext;
204 sqlite3VtabUnlock(pVTab);
205 break;
212 ** Disconnect all the virtual table objects in the sqlite3.pDisconnect list.
214 ** This function may only be called when the mutexes associated with all
215 ** shared b-tree databases opened using connection db are held by the
216 ** caller. This is done to protect the sqlite3.pDisconnect list. The
217 ** sqlite3.pDisconnect list is accessed only as follows:
219 ** 1) By this function. In this case, all BtShared mutexes and the mutex
220 ** associated with the database handle itself must be held.
222 ** 2) By function vtabDisconnectAll(), when it adds a VTable entry to
223 ** the sqlite3.pDisconnect list. In this case either the BtShared mutex
224 ** associated with the database the virtual table is stored in is held
225 ** or, if the virtual table is stored in a non-sharable database, then
226 ** the database handle mutex is held.
228 ** As a result, a sqlite3.pDisconnect cannot be accessed simultaneously
229 ** by multiple threads. It is thread-safe.
231 void sqlite3VtabUnlockList(sqlite3 *db){
232 VTable *p = db->pDisconnect;
233 db->pDisconnect = 0;
235 assert( sqlite3BtreeHoldsAllMutexes(db) );
236 assert( sqlite3_mutex_held(db->mutex) );
238 if( p ){
239 sqlite3ExpirePreparedStatements(db);
240 do {
241 VTable *pNext = p->pNext;
242 sqlite3VtabUnlock(p);
243 p = pNext;
244 }while( p );
249 ** Clear any and all virtual-table information from the Table record.
250 ** This routine is called, for example, just before deleting the Table
251 ** record.
253 ** Since it is a virtual-table, the Table structure contains a pointer
254 ** to the head of a linked list of VTable structures. Each VTable
255 ** structure is associated with a single sqlite3* user of the schema.
256 ** The reference count of the VTable structure associated with database
257 ** connection db is decremented immediately (which may lead to the
258 ** structure being xDisconnected and free). Any other VTable structures
259 ** in the list are moved to the sqlite3.pDisconnect list of the associated
260 ** database connection.
262 void sqlite3VtabClear(sqlite3 *db, Table *p){
263 if( !db || db->pnBytesFreed==0 ) vtabDisconnectAll(0, p);
264 if( p->azModuleArg ){
265 int i;
266 for(i=0; i<p->nModuleArg; i++){
267 if( i!=1 ) sqlite3DbFree(db, p->azModuleArg[i]);
269 sqlite3DbFree(db, p->azModuleArg);
274 ** Add a new module argument to pTable->azModuleArg[].
275 ** The string is not copied - the pointer is stored. The
276 ** string will be freed automatically when the table is
277 ** deleted.
279 static void addModuleArgument(sqlite3 *db, Table *pTable, char *zArg){
280 int i = pTable->nModuleArg++;
281 int nBytes = sizeof(char *)*(1+pTable->nModuleArg);
282 char **azModuleArg;
283 azModuleArg = sqlite3DbRealloc(db, pTable->azModuleArg, nBytes);
284 if( azModuleArg==0 ){
285 int j;
286 for(j=0; j<i; j++){
287 sqlite3DbFree(db, pTable->azModuleArg[j]);
289 sqlite3DbFree(db, zArg);
290 sqlite3DbFree(db, pTable->azModuleArg);
291 pTable->nModuleArg = 0;
292 }else{
293 azModuleArg[i] = zArg;
294 azModuleArg[i+1] = 0;
296 pTable->azModuleArg = azModuleArg;
300 ** The parser calls this routine when it first sees a CREATE VIRTUAL TABLE
301 ** statement. The module name has been parsed, but the optional list
302 ** of parameters that follow the module name are still pending.
304 void sqlite3VtabBeginParse(
305 Parse *pParse, /* Parsing context */
306 Token *pName1, /* Name of new table, or database name */
307 Token *pName2, /* Name of new table or NULL */
308 Token *pModuleName, /* Name of the module for the virtual table */
309 int ifNotExists /* No error if the table already exists */
311 int iDb; /* The database the table is being created in */
312 Table *pTable; /* The new virtual table */
313 sqlite3 *db; /* Database connection */
315 sqlite3StartTable(pParse, pName1, pName2, 0, 0, 1, ifNotExists);
316 pTable = pParse->pNewTable;
317 if( pTable==0 ) return;
318 assert( 0==pTable->pIndex );
320 db = pParse->db;
321 iDb = sqlite3SchemaToIndex(db, pTable->pSchema);
322 assert( iDb>=0 );
324 pTable->tabFlags |= TF_Virtual;
325 pTable->nModuleArg = 0;
326 addModuleArgument(db, pTable, sqlite3NameFromToken(db, pModuleName));
327 addModuleArgument(db, pTable, 0);
328 addModuleArgument(db, pTable, sqlite3DbStrDup(db, pTable->zName));
329 pParse->sNameToken.n = (int)(&pModuleName->z[pModuleName->n] - pName1->z);
331 #ifndef SQLITE_OMIT_AUTHORIZATION
332 /* Creating a virtual table invokes the authorization callback twice.
333 ** The first invocation, to obtain permission to INSERT a row into the
334 ** sqlite_master table, has already been made by sqlite3StartTable().
335 ** The second call, to obtain permission to create the table, is made now.
337 if( pTable->azModuleArg ){
338 sqlite3AuthCheck(pParse, SQLITE_CREATE_VTABLE, pTable->zName,
339 pTable->azModuleArg[0], pParse->db->aDb[iDb].zName);
341 #endif
345 ** This routine takes the module argument that has been accumulating
346 ** in pParse->zArg[] and appends it to the list of arguments on the
347 ** virtual table currently under construction in pParse->pTable.
349 static void addArgumentToVtab(Parse *pParse){
350 if( pParse->sArg.z && pParse->pNewTable ){
351 const char *z = (const char*)pParse->sArg.z;
352 int n = pParse->sArg.n;
353 sqlite3 *db = pParse->db;
354 addModuleArgument(db, pParse->pNewTable, sqlite3DbStrNDup(db, z, n));
359 ** The parser calls this routine after the CREATE VIRTUAL TABLE statement
360 ** has been completely parsed.
362 void sqlite3VtabFinishParse(Parse *pParse, Token *pEnd){
363 Table *pTab = pParse->pNewTable; /* The table being constructed */
364 sqlite3 *db = pParse->db; /* The database connection */
366 if( pTab==0 ) return;
367 addArgumentToVtab(pParse);
368 pParse->sArg.z = 0;
369 if( pTab->nModuleArg<1 ) return;
371 /* If the CREATE VIRTUAL TABLE statement is being entered for the
372 ** first time (in other words if the virtual table is actually being
373 ** created now instead of just being read out of sqlite_master) then
374 ** do additional initialization work and store the statement text
375 ** in the sqlite_master table.
377 if( !db->init.busy ){
378 char *zStmt;
379 char *zWhere;
380 int iDb;
381 Vdbe *v;
383 /* Compute the complete text of the CREATE VIRTUAL TABLE statement */
384 if( pEnd ){
385 pParse->sNameToken.n = (int)(pEnd->z - pParse->sNameToken.z) + pEnd->n;
387 zStmt = sqlite3MPrintf(db, "CREATE VIRTUAL TABLE %T", &pParse->sNameToken);
389 /* A slot for the record has already been allocated in the
390 ** SQLITE_MASTER table. We just need to update that slot with all
391 ** the information we've collected.
393 ** The VM register number pParse->regRowid holds the rowid of an
394 ** entry in the sqlite_master table tht was created for this vtab
395 ** by sqlite3StartTable().
397 iDb = sqlite3SchemaToIndex(db, pTab->pSchema);
398 sqlite3NestedParse(pParse,
399 "UPDATE %Q.%s "
400 "SET type='table', name=%Q, tbl_name=%Q, rootpage=0, sql=%Q "
401 "WHERE rowid=#%d",
402 db->aDb[iDb].zName, SCHEMA_TABLE(iDb),
403 pTab->zName,
404 pTab->zName,
405 zStmt,
406 pParse->regRowid
408 sqlite3DbFree(db, zStmt);
409 v = sqlite3GetVdbe(pParse);
410 sqlite3ChangeCookie(pParse, iDb);
412 sqlite3VdbeAddOp2(v, OP_Expire, 0, 0);
413 zWhere = sqlite3MPrintf(db, "name='%q' AND type='table'", pTab->zName);
414 sqlite3VdbeAddParseSchemaOp(v, iDb, zWhere);
415 sqlite3VdbeAddOp4(v, OP_VCreate, iDb, 0, 0,
416 pTab->zName, sqlite3Strlen30(pTab->zName) + 1);
419 /* If we are rereading the sqlite_master table create the in-memory
420 ** record of the table. The xConnect() method is not called until
421 ** the first time the virtual table is used in an SQL statement. This
422 ** allows a schema that contains virtual tables to be loaded before
423 ** the required virtual table implementations are registered. */
424 else {
425 Table *pOld;
426 Schema *pSchema = pTab->pSchema;
427 const char *zName = pTab->zName;
428 assert( sqlite3SchemaMutexHeld(db, 0, pSchema) );
429 pOld = sqlite3HashInsert(&pSchema->tblHash, zName, pTab);
430 if( pOld ){
431 db->mallocFailed = 1;
432 assert( pTab==pOld ); /* Malloc must have failed inside HashInsert() */
433 return;
435 pParse->pNewTable = 0;
440 ** The parser calls this routine when it sees the first token
441 ** of an argument to the module name in a CREATE VIRTUAL TABLE statement.
443 void sqlite3VtabArgInit(Parse *pParse){
444 addArgumentToVtab(pParse);
445 pParse->sArg.z = 0;
446 pParse->sArg.n = 0;
450 ** The parser calls this routine for each token after the first token
451 ** in an argument to the module name in a CREATE VIRTUAL TABLE statement.
453 void sqlite3VtabArgExtend(Parse *pParse, Token *p){
454 Token *pArg = &pParse->sArg;
455 if( pArg->z==0 ){
456 pArg->z = p->z;
457 pArg->n = p->n;
458 }else{
459 assert(pArg->z < p->z);
460 pArg->n = (int)(&p->z[p->n] - pArg->z);
465 ** Invoke a virtual table constructor (either xCreate or xConnect). The
466 ** pointer to the function to invoke is passed as the fourth parameter
467 ** to this procedure.
469 static int vtabCallConstructor(
470 sqlite3 *db,
471 Table *pTab,
472 Module *pMod,
473 int (*xConstruct)(sqlite3*,void*,int,const char*const*,sqlite3_vtab**,char**),
474 char **pzErr
476 VtabCtx sCtx, *pPriorCtx;
477 VTable *pVTable;
478 int rc;
479 const char *const*azArg = (const char *const*)pTab->azModuleArg;
480 int nArg = pTab->nModuleArg;
481 char *zErr = 0;
482 char *zModuleName = sqlite3MPrintf(db, "%s", pTab->zName);
483 int iDb;
485 if( !zModuleName ){
486 return SQLITE_NOMEM;
489 pVTable = sqlite3DbMallocZero(db, sizeof(VTable));
490 if( !pVTable ){
491 sqlite3DbFree(db, zModuleName);
492 return SQLITE_NOMEM;
494 pVTable->db = db;
495 pVTable->pMod = pMod;
497 iDb = sqlite3SchemaToIndex(db, pTab->pSchema);
498 pTab->azModuleArg[1] = db->aDb[iDb].zName;
500 /* Invoke the virtual table constructor */
501 assert( &db->pVtabCtx );
502 assert( xConstruct );
503 sCtx.pTab = pTab;
504 sCtx.pVTable = pVTable;
505 pPriorCtx = db->pVtabCtx;
506 db->pVtabCtx = &sCtx;
507 rc = xConstruct(db, pMod->pAux, nArg, azArg, &pVTable->pVtab, &zErr);
508 db->pVtabCtx = pPriorCtx;
509 if( rc==SQLITE_NOMEM ) db->mallocFailed = 1;
511 if( SQLITE_OK!=rc ){
512 if( zErr==0 ){
513 *pzErr = sqlite3MPrintf(db, "vtable constructor failed: %s", zModuleName);
514 }else {
515 *pzErr = sqlite3MPrintf(db, "%s", zErr);
516 sqlite3_free(zErr);
518 sqlite3DbFree(db, pVTable);
519 }else if( ALWAYS(pVTable->pVtab) ){
520 /* Justification of ALWAYS(): A correct vtab constructor must allocate
521 ** the sqlite3_vtab object if successful. */
522 memset(pVTable->pVtab, 0, sizeof(pVTable->pVtab[0]));
523 pVTable->pVtab->pModule = pMod->pModule;
524 pVTable->nRef = 1;
525 if( sCtx.pTab ){
526 const char *zFormat = "vtable constructor did not declare schema: %s";
527 *pzErr = sqlite3MPrintf(db, zFormat, pTab->zName);
528 sqlite3VtabUnlock(pVTable);
529 rc = SQLITE_ERROR;
530 }else{
531 int iCol;
532 /* If everything went according to plan, link the new VTable structure
533 ** into the linked list headed by pTab->pVTable. Then loop through the
534 ** columns of the table to see if any of them contain the token "hidden".
535 ** If so, set the Column COLFLAG_HIDDEN flag and remove the token from
536 ** the type string. */
537 pVTable->pNext = pTab->pVTable;
538 pTab->pVTable = pVTable;
540 for(iCol=0; iCol<pTab->nCol; iCol++){
541 char *zType = pTab->aCol[iCol].zType;
542 int nType;
543 int i = 0;
544 if( !zType ) continue;
545 nType = sqlite3Strlen30(zType);
546 if( sqlite3StrNICmp("hidden", zType, 6)||(zType[6] && zType[6]!=' ') ){
547 for(i=0; i<nType; i++){
548 if( (0==sqlite3StrNICmp(" hidden", &zType[i], 7))
549 && (zType[i+7]=='\0' || zType[i+7]==' ')
551 i++;
552 break;
556 if( i<nType ){
557 int j;
558 int nDel = 6 + (zType[i+6] ? 1 : 0);
559 for(j=i; (j+nDel)<=nType; j++){
560 zType[j] = zType[j+nDel];
562 if( zType[i]=='\0' && i>0 ){
563 assert(zType[i-1]==' ');
564 zType[i-1] = '\0';
566 pTab->aCol[iCol].colFlags |= COLFLAG_HIDDEN;
572 sqlite3DbFree(db, zModuleName);
573 return rc;
577 ** This function is invoked by the parser to call the xConnect() method
578 ** of the virtual table pTab. If an error occurs, an error code is returned
579 ** and an error left in pParse.
581 ** This call is a no-op if table pTab is not a virtual table.
583 int sqlite3VtabCallConnect(Parse *pParse, Table *pTab){
584 sqlite3 *db = pParse->db;
585 const char *zMod;
586 Module *pMod;
587 int rc;
589 assert( pTab );
590 if( (pTab->tabFlags & TF_Virtual)==0 || sqlite3GetVTable(db, pTab) ){
591 return SQLITE_OK;
594 /* Locate the required virtual table module */
595 zMod = pTab->azModuleArg[0];
596 pMod = (Module*)sqlite3HashFind(&db->aModule, zMod);
598 if( !pMod ){
599 const char *zModule = pTab->azModuleArg[0];
600 sqlite3ErrorMsg(pParse, "no such module: %s", zModule);
601 rc = SQLITE_ERROR;
602 }else{
603 char *zErr = 0;
604 rc = vtabCallConstructor(db, pTab, pMod, pMod->pModule->xConnect, &zErr);
605 if( rc!=SQLITE_OK ){
606 sqlite3ErrorMsg(pParse, "%s", zErr);
608 sqlite3DbFree(db, zErr);
611 return rc;
614 ** Grow the db->aVTrans[] array so that there is room for at least one
615 ** more v-table. Return SQLITE_NOMEM if a malloc fails, or SQLITE_OK otherwise.
617 static int growVTrans(sqlite3 *db){
618 const int ARRAY_INCR = 5;
620 /* Grow the sqlite3.aVTrans array if required */
621 if( (db->nVTrans%ARRAY_INCR)==0 ){
622 VTable **aVTrans;
623 int nBytes = sizeof(sqlite3_vtab *) * (db->nVTrans + ARRAY_INCR);
624 aVTrans = sqlite3DbRealloc(db, (void *)db->aVTrans, nBytes);
625 if( !aVTrans ){
626 return SQLITE_NOMEM;
628 memset(&aVTrans[db->nVTrans], 0, sizeof(sqlite3_vtab *)*ARRAY_INCR);
629 db->aVTrans = aVTrans;
632 return SQLITE_OK;
636 ** Add the virtual table pVTab to the array sqlite3.aVTrans[]. Space should
637 ** have already been reserved using growVTrans().
639 static void addToVTrans(sqlite3 *db, VTable *pVTab){
640 /* Add pVtab to the end of sqlite3.aVTrans */
641 db->aVTrans[db->nVTrans++] = pVTab;
642 sqlite3VtabLock(pVTab);
646 ** This function is invoked by the vdbe to call the xCreate method
647 ** of the virtual table named zTab in database iDb.
649 ** If an error occurs, *pzErr is set to point an an English language
650 ** description of the error and an SQLITE_XXX error code is returned.
651 ** In this case the caller must call sqlite3DbFree(db, ) on *pzErr.
653 int sqlite3VtabCallCreate(sqlite3 *db, int iDb, const char *zTab, char **pzErr){
654 int rc = SQLITE_OK;
655 Table *pTab;
656 Module *pMod;
657 const char *zMod;
659 pTab = sqlite3FindTable(db, zTab, db->aDb[iDb].zName);
660 assert( pTab && (pTab->tabFlags & TF_Virtual)!=0 && !pTab->pVTable );
662 /* Locate the required virtual table module */
663 zMod = pTab->azModuleArg[0];
664 pMod = (Module*)sqlite3HashFind(&db->aModule, zMod);
666 /* If the module has been registered and includes a Create method,
667 ** invoke it now. If the module has not been registered, return an
668 ** error. Otherwise, do nothing.
670 if( !pMod ){
671 *pzErr = sqlite3MPrintf(db, "no such module: %s", zMod);
672 rc = SQLITE_ERROR;
673 }else{
674 rc = vtabCallConstructor(db, pTab, pMod, pMod->pModule->xCreate, pzErr);
677 /* Justification of ALWAYS(): The xConstructor method is required to
678 ** create a valid sqlite3_vtab if it returns SQLITE_OK. */
679 if( rc==SQLITE_OK && ALWAYS(sqlite3GetVTable(db, pTab)) ){
680 rc = growVTrans(db);
681 if( rc==SQLITE_OK ){
682 addToVTrans(db, sqlite3GetVTable(db, pTab));
686 return rc;
690 ** This function is used to set the schema of a virtual table. It is only
691 ** valid to call this function from within the xCreate() or xConnect() of a
692 ** virtual table module.
694 int sqlite3_declare_vtab(sqlite3 *db, const char *zCreateTable){
695 Parse *pParse;
697 int rc = SQLITE_OK;
698 Table *pTab;
699 char *zErr = 0;
701 sqlite3_mutex_enter(db->mutex);
702 if( !db->pVtabCtx || !(pTab = db->pVtabCtx->pTab) ){
703 sqlite3Error(db, SQLITE_MISUSE);
704 sqlite3_mutex_leave(db->mutex);
705 return SQLITE_MISUSE_BKPT;
707 assert( (pTab->tabFlags & TF_Virtual)!=0 );
709 pParse = sqlite3StackAllocZero(db, sizeof(*pParse));
710 if( pParse==0 ){
711 rc = SQLITE_NOMEM;
712 }else{
713 pParse->declareVtab = 1;
714 pParse->db = db;
715 pParse->nQueryLoop = 1;
717 if( SQLITE_OK==sqlite3RunParser(pParse, zCreateTable, &zErr)
718 && pParse->pNewTable
719 && !db->mallocFailed
720 && !pParse->pNewTable->pSelect
721 && (pParse->pNewTable->tabFlags & TF_Virtual)==0
723 if( !pTab->aCol ){
724 pTab->aCol = pParse->pNewTable->aCol;
725 pTab->nCol = pParse->pNewTable->nCol;
726 pParse->pNewTable->nCol = 0;
727 pParse->pNewTable->aCol = 0;
729 db->pVtabCtx->pTab = 0;
730 }else{
731 sqlite3ErrorWithMsg(db, SQLITE_ERROR, (zErr ? "%s" : 0), zErr);
732 sqlite3DbFree(db, zErr);
733 rc = SQLITE_ERROR;
735 pParse->declareVtab = 0;
737 if( pParse->pVdbe ){
738 sqlite3VdbeFinalize(pParse->pVdbe);
740 sqlite3DeleteTable(db, pParse->pNewTable);
741 sqlite3ParserReset(pParse);
742 sqlite3StackFree(db, pParse);
745 assert( (rc&0xff)==rc );
746 rc = sqlite3ApiExit(db, rc);
747 sqlite3_mutex_leave(db->mutex);
748 return rc;
752 ** This function is invoked by the vdbe to call the xDestroy method
753 ** of the virtual table named zTab in database iDb. This occurs
754 ** when a DROP TABLE is mentioned.
756 ** This call is a no-op if zTab is not a virtual table.
758 int sqlite3VtabCallDestroy(sqlite3 *db, int iDb, const char *zTab){
759 int rc = SQLITE_OK;
760 Table *pTab;
762 pTab = sqlite3FindTable(db, zTab, db->aDb[iDb].zName);
763 if( ALWAYS(pTab!=0 && pTab->pVTable!=0) ){
764 VTable *p = vtabDisconnectAll(db, pTab);
766 assert( rc==SQLITE_OK );
767 rc = p->pMod->pModule->xDestroy(p->pVtab);
769 /* Remove the sqlite3_vtab* from the aVTrans[] array, if applicable */
770 if( rc==SQLITE_OK ){
771 assert( pTab->pVTable==p && p->pNext==0 );
772 p->pVtab = 0;
773 pTab->pVTable = 0;
774 sqlite3VtabUnlock(p);
778 return rc;
782 ** This function invokes either the xRollback or xCommit method
783 ** of each of the virtual tables in the sqlite3.aVTrans array. The method
784 ** called is identified by the second argument, "offset", which is
785 ** the offset of the method to call in the sqlite3_module structure.
787 ** The array is cleared after invoking the callbacks.
789 static void callFinaliser(sqlite3 *db, int offset){
790 int i;
791 if( db->aVTrans ){
792 for(i=0; i<db->nVTrans; i++){
793 VTable *pVTab = db->aVTrans[i];
794 sqlite3_vtab *p = pVTab->pVtab;
795 if( p ){
796 int (*x)(sqlite3_vtab *);
797 x = *(int (**)(sqlite3_vtab *))((char *)p->pModule + offset);
798 if( x ) x(p);
800 pVTab->iSavepoint = 0;
801 sqlite3VtabUnlock(pVTab);
803 sqlite3DbFree(db, db->aVTrans);
804 db->nVTrans = 0;
805 db->aVTrans = 0;
810 ** Invoke the xSync method of all virtual tables in the sqlite3.aVTrans
811 ** array. Return the error code for the first error that occurs, or
812 ** SQLITE_OK if all xSync operations are successful.
814 ** If an error message is available, leave it in p->zErrMsg.
816 int sqlite3VtabSync(sqlite3 *db, Vdbe *p){
817 int i;
818 int rc = SQLITE_OK;
819 VTable **aVTrans = db->aVTrans;
821 db->aVTrans = 0;
822 for(i=0; rc==SQLITE_OK && i<db->nVTrans; i++){
823 int (*x)(sqlite3_vtab *);
824 sqlite3_vtab *pVtab = aVTrans[i]->pVtab;
825 if( pVtab && (x = pVtab->pModule->xSync)!=0 ){
826 rc = x(pVtab);
827 sqlite3VtabImportErrmsg(p, pVtab);
830 db->aVTrans = aVTrans;
831 return rc;
835 ** Invoke the xRollback method of all virtual tables in the
836 ** sqlite3.aVTrans array. Then clear the array itself.
838 int sqlite3VtabRollback(sqlite3 *db){
839 callFinaliser(db, offsetof(sqlite3_module,xRollback));
840 return SQLITE_OK;
844 ** Invoke the xCommit method of all virtual tables in the
845 ** sqlite3.aVTrans array. Then clear the array itself.
847 int sqlite3VtabCommit(sqlite3 *db){
848 callFinaliser(db, offsetof(sqlite3_module,xCommit));
849 return SQLITE_OK;
853 ** If the virtual table pVtab supports the transaction interface
854 ** (xBegin/xRollback/xCommit and optionally xSync) and a transaction is
855 ** not currently open, invoke the xBegin method now.
857 ** If the xBegin call is successful, place the sqlite3_vtab pointer
858 ** in the sqlite3.aVTrans array.
860 int sqlite3VtabBegin(sqlite3 *db, VTable *pVTab){
861 int rc = SQLITE_OK;
862 const sqlite3_module *pModule;
864 /* Special case: If db->aVTrans is NULL and db->nVTrans is greater
865 ** than zero, then this function is being called from within a
866 ** virtual module xSync() callback. It is illegal to write to
867 ** virtual module tables in this case, so return SQLITE_LOCKED.
869 if( sqlite3VtabInSync(db) ){
870 return SQLITE_LOCKED;
872 if( !pVTab ){
873 return SQLITE_OK;
875 pModule = pVTab->pVtab->pModule;
877 if( pModule->xBegin ){
878 int i;
880 /* If pVtab is already in the aVTrans array, return early */
881 for(i=0; i<db->nVTrans; i++){
882 if( db->aVTrans[i]==pVTab ){
883 return SQLITE_OK;
887 /* Invoke the xBegin method. If successful, add the vtab to the
888 ** sqlite3.aVTrans[] array. */
889 rc = growVTrans(db);
890 if( rc==SQLITE_OK ){
891 rc = pModule->xBegin(pVTab->pVtab);
892 if( rc==SQLITE_OK ){
893 addToVTrans(db, pVTab);
897 return rc;
901 ** Invoke either the xSavepoint, xRollbackTo or xRelease method of all
902 ** virtual tables that currently have an open transaction. Pass iSavepoint
903 ** as the second argument to the virtual table method invoked.
905 ** If op is SAVEPOINT_BEGIN, the xSavepoint method is invoked. If it is
906 ** SAVEPOINT_ROLLBACK, the xRollbackTo method. Otherwise, if op is
907 ** SAVEPOINT_RELEASE, then the xRelease method of each virtual table with
908 ** an open transaction is invoked.
910 ** If any virtual table method returns an error code other than SQLITE_OK,
911 ** processing is abandoned and the error returned to the caller of this
912 ** function immediately. If all calls to virtual table methods are successful,
913 ** SQLITE_OK is returned.
915 int sqlite3VtabSavepoint(sqlite3 *db, int op, int iSavepoint){
916 int rc = SQLITE_OK;
918 assert( op==SAVEPOINT_RELEASE||op==SAVEPOINT_ROLLBACK||op==SAVEPOINT_BEGIN );
919 assert( iSavepoint>=0 );
920 if( db->aVTrans ){
921 int i;
922 for(i=0; rc==SQLITE_OK && i<db->nVTrans; i++){
923 VTable *pVTab = db->aVTrans[i];
924 const sqlite3_module *pMod = pVTab->pMod->pModule;
925 if( pVTab->pVtab && pMod->iVersion>=2 ){
926 int (*xMethod)(sqlite3_vtab *, int);
927 switch( op ){
928 case SAVEPOINT_BEGIN:
929 xMethod = pMod->xSavepoint;
930 pVTab->iSavepoint = iSavepoint+1;
931 break;
932 case SAVEPOINT_ROLLBACK:
933 xMethod = pMod->xRollbackTo;
934 break;
935 default:
936 xMethod = pMod->xRelease;
937 break;
939 if( xMethod && pVTab->iSavepoint>iSavepoint ){
940 rc = xMethod(pVTab->pVtab, iSavepoint);
945 return rc;
949 ** The first parameter (pDef) is a function implementation. The
950 ** second parameter (pExpr) is the first argument to this function.
951 ** If pExpr is a column in a virtual table, then let the virtual
952 ** table implementation have an opportunity to overload the function.
954 ** This routine is used to allow virtual table implementations to
955 ** overload MATCH, LIKE, GLOB, and REGEXP operators.
957 ** Return either the pDef argument (indicating no change) or a
958 ** new FuncDef structure that is marked as ephemeral using the
959 ** SQLITE_FUNC_EPHEM flag.
961 FuncDef *sqlite3VtabOverloadFunction(
962 sqlite3 *db, /* Database connection for reporting malloc problems */
963 FuncDef *pDef, /* Function to possibly overload */
964 int nArg, /* Number of arguments to the function */
965 Expr *pExpr /* First argument to the function */
967 Table *pTab;
968 sqlite3_vtab *pVtab;
969 sqlite3_module *pMod;
970 void (*xFunc)(sqlite3_context*,int,sqlite3_value**) = 0;
971 void *pArg = 0;
972 FuncDef *pNew;
973 int rc = 0;
974 char *zLowerName;
975 unsigned char *z;
978 /* Check to see the left operand is a column in a virtual table */
979 if( NEVER(pExpr==0) ) return pDef;
980 if( pExpr->op!=TK_COLUMN ) return pDef;
981 pTab = pExpr->pTab;
982 if( NEVER(pTab==0) ) return pDef;
983 if( (pTab->tabFlags & TF_Virtual)==0 ) return pDef;
984 pVtab = sqlite3GetVTable(db, pTab)->pVtab;
985 assert( pVtab!=0 );
986 assert( pVtab->pModule!=0 );
987 pMod = (sqlite3_module *)pVtab->pModule;
988 if( pMod->xFindFunction==0 ) return pDef;
990 /* Call the xFindFunction method on the virtual table implementation
991 ** to see if the implementation wants to overload this function
993 zLowerName = sqlite3DbStrDup(db, pDef->zName);
994 if( zLowerName ){
995 for(z=(unsigned char*)zLowerName; *z; z++){
996 *z = sqlite3UpperToLower[*z];
998 rc = pMod->xFindFunction(pVtab, nArg, zLowerName, &xFunc, &pArg);
999 sqlite3DbFree(db, zLowerName);
1001 if( rc==0 ){
1002 return pDef;
1005 /* Create a new ephemeral function definition for the overloaded
1006 ** function */
1007 pNew = sqlite3DbMallocZero(db, sizeof(*pNew)
1008 + sqlite3Strlen30(pDef->zName) + 1);
1009 if( pNew==0 ){
1010 return pDef;
1012 *pNew = *pDef;
1013 pNew->zName = (char *)&pNew[1];
1014 memcpy(pNew->zName, pDef->zName, sqlite3Strlen30(pDef->zName)+1);
1015 pNew->xFunc = xFunc;
1016 pNew->pUserData = pArg;
1017 pNew->funcFlags |= SQLITE_FUNC_EPHEM;
1018 return pNew;
1022 ** Make sure virtual table pTab is contained in the pParse->apVirtualLock[]
1023 ** array so that an OP_VBegin will get generated for it. Add pTab to the
1024 ** array if it is missing. If pTab is already in the array, this routine
1025 ** is a no-op.
1027 void sqlite3VtabMakeWritable(Parse *pParse, Table *pTab){
1028 Parse *pToplevel = sqlite3ParseToplevel(pParse);
1029 int i, n;
1030 Table **apVtabLock;
1032 assert( IsVirtual(pTab) );
1033 for(i=0; i<pToplevel->nVtabLock; i++){
1034 if( pTab==pToplevel->apVtabLock[i] ) return;
1036 n = (pToplevel->nVtabLock+1)*sizeof(pToplevel->apVtabLock[0]);
1037 apVtabLock = sqlite3_realloc(pToplevel->apVtabLock, n);
1038 if( apVtabLock ){
1039 pToplevel->apVtabLock = apVtabLock;
1040 pToplevel->apVtabLock[pToplevel->nVtabLock++] = pTab;
1041 }else{
1042 pToplevel->db->mallocFailed = 1;
1047 ** Return the ON CONFLICT resolution mode in effect for the virtual
1048 ** table update operation currently in progress.
1050 ** The results of this routine are undefined unless it is called from
1051 ** within an xUpdate method.
1053 int sqlite3_vtab_on_conflict(sqlite3 *db){
1054 static const unsigned char aMap[] = {
1055 SQLITE_ROLLBACK, SQLITE_ABORT, SQLITE_FAIL, SQLITE_IGNORE, SQLITE_REPLACE
1057 assert( OE_Rollback==1 && OE_Abort==2 && OE_Fail==3 );
1058 assert( OE_Ignore==4 && OE_Replace==5 );
1059 assert( db->vtabOnConflict>=1 && db->vtabOnConflict<=5 );
1060 return (int)aMap[db->vtabOnConflict-1];
1064 ** Call from within the xCreate() or xConnect() methods to provide
1065 ** the SQLite core with additional information about the behavior
1066 ** of the virtual table being implemented.
1068 int sqlite3_vtab_config(sqlite3 *db, int op, ...){
1069 va_list ap;
1070 int rc = SQLITE_OK;
1072 sqlite3_mutex_enter(db->mutex);
1074 va_start(ap, op);
1075 switch( op ){
1076 case SQLITE_VTAB_CONSTRAINT_SUPPORT: {
1077 VtabCtx *p = db->pVtabCtx;
1078 if( !p ){
1079 rc = SQLITE_MISUSE_BKPT;
1080 }else{
1081 assert( p->pTab==0 || (p->pTab->tabFlags & TF_Virtual)!=0 );
1082 p->pVTable->bConstraint = (u8)va_arg(ap, int);
1084 break;
1086 default:
1087 rc = SQLITE_MISUSE_BKPT;
1088 break;
1090 va_end(ap);
1092 if( rc!=SQLITE_OK ) sqlite3Error(db, rc);
1093 sqlite3_mutex_leave(db->mutex);
1094 return rc;
1097 #endif /* SQLITE_OMIT_VIRTUALTABLE */