src/vtab.c

   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.
  10 **
  11 *************************************************************************
  12 ** This file contains code used to help implement virtual tables.
  13 */
  14 #ifndef SQLITE_OMIT_VIRTUALTABLE
  15 #include "sqliteInt.h"
  16
  17 /*
  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.
  23 */
  24 struct VtabCtx {
  25   Table *pTab;
  26   VTable *pVTable;
  27 };
  28
  29 /*
  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.
  33 */
  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 */
  40 ){
  41   int rc, nName;
  42   Module *pMod;
  43
  44   sqlite3_mutex_enter(db->mutex);
  45   nName = sqlite3Strlen30(zName);
  46   pMod = (Module *)sqlite3DbMallocRaw(db, sizeof(Module) + nName + 1);
  47   if( pMod ){
  48     Module *pDel;
  49     char *zCopy = (char *)(&pMod[1]);
  50     memcpy(zCopy, zName, nName+1);
  51     pMod->zName = zCopy;
  52     pMod->pModule = pModule;
  53     pMod->pAux = pAux;
  54     pMod->xDestroy = xDestroy;
  55     pDel = (Module *)sqlite3HashInsert(&db->aModule, zCopy, nName, (void*)pMod);
  56     if( pDel && pDel->xDestroy ){
  57       sqlite3ResetInternalSchema(db, -1);
  58       pDel->xDestroy(pDel->pAux);
  59     }
  60     sqlite3DbFree(db, pDel);
  61     if( pDel==pMod ){
  62       db->mallocFailed = 1;
  63     }
  64   }else if( xDestroy ){
  65     xDestroy(pAux);
  66   }
  67   rc = sqlite3ApiExit(db, SQLITE_OK);
  68   sqlite3_mutex_leave(db->mutex);
  69   return rc;
  70 }
  71
  72
  73 /*
  74 ** External API function used to create a new virtual-table module.
  75 */
  76 int sqlite3_create_module(
  77   sqlite3 *db,                    /* Database in which module is registered */
  78   const char *zName,              /* Name assigned to this module */
  79   const sqlite3_module *pModule,  /* The definition of the module */
  80   void *pAux                      /* Context pointer for xCreate/xConnect */
  81 ){
  82   return createModule(db, zName, pModule, pAux, 0);
  83 }
  84
  85 /*
  86 ** External API function used to create a new virtual-table module.
  87 */
  88 int sqlite3_create_module_v2(
  89   sqlite3 *db,                    /* Database in which module is registered */
  90   const char *zName,              /* Name assigned to this module */
  91   const sqlite3_module *pModule,  /* The definition of the module */
  92   void *pAux,                     /* Context pointer for xCreate/xConnect */
  93   void (*xDestroy)(void *)        /* Module destructor function */
  94 ){
  95   return createModule(db, zName, pModule, pAux, xDestroy);
  96 }
  97
  98 /*
  99 ** Lock the virtual table so that it cannot be disconnected.
 100 ** Locks nest.  Every lock should have a corresponding unlock.
 101 ** If an unlock is omitted, resources leaks will occur.
 102 **
 103 ** If a disconnect is attempted while a virtual table is locked,
 104 ** the disconnect is deferred until all locks have been removed.
 105 */
 106 void sqlite3VtabLock(VTable *pVTab){
 107   pVTab->nRef++;
 108 }
 109
 110
 111 /*
 112 ** pTab is a pointer to a Table structure representing a virtual-table.
 113 ** Return a pointer to the VTable object used by connection db to access
 114 ** this virtual-table, if one has been created, or NULL otherwise.
 115 */
 116 VTable *sqlite3GetVTable(sqlite3 *db, Table *pTab){
 117   VTable *pVtab;
 118   assert( IsVirtual(pTab) );
 119   for(pVtab=pTab->pVTable; pVtab && pVtab->db!=db; pVtab=pVtab->pNext);
 120   return pVtab;
 121 }
 122
 123 /*
 124 ** Decrement the ref-count on a virtual table object. When the ref-count
 125 ** reaches zero, call the xDisconnect() method to delete the object.
 126 */
 127 void sqlite3VtabUnlock(VTable *pVTab){
 128   sqlite3 *db = pVTab->db;
 129
 130   assert( db );
 131   assert( pVTab->nRef>0 );
 132   assert( sqlite3SafetyCheckOk(db) );
 133
 134   pVTab->nRef--;
 135   if( pVTab->nRef==0 ){
 136     sqlite3_vtab *p = pVTab->pVtab;
 137     if( p ){
 138       p->pModule->xDisconnect(p);
 139     }
 140     sqlite3DbFree(db, pVTab);
 141   }
 142 }
 143
 144 /*
 145 ** Table p is a virtual table. This function moves all elements in the
 146 ** p->pVTable list to the sqlite3.pDisconnect lists of their associated
 147 ** database connections to be disconnected at the next opportunity.
 148 ** Except, if argument db is not NULL, then the entry associated with
 149 ** connection db is left in the p->pVTable list.
 150 */
 151 static VTable *vtabDisconnectAll(sqlite3 *db, Table *p){
 152   VTable *pRet = 0;
 153   VTable *pVTable = p->pVTable;
 154   p->pVTable = 0;
 155
 156   /* Assert that the mutex (if any) associated with the BtShared database
 157   ** that contains table p is held by the caller. See header comments
 158   ** above function sqlite3VtabUnlockList() for an explanation of why
 159   ** this makes it safe to access the sqlite3.pDisconnect list of any
 160   ** database connection that may have an entry in the p->pVTable list.
 161   */
 162   assert( db==0 || sqlite3SchemaMutexHeld(db, 0, p->pSchema) );
 163
 164   while( pVTable ){
 165     sqlite3 *db2 = pVTable->db;
 166     VTable *pNext = pVTable->pNext;
 167     assert( db2 );
 168     if( db2==db ){
 169       pRet = pVTable;
 170       p->pVTable = pRet;
 171       pRet->pNext = 0;
 172     }else{
 173       pVTable->pNext = db2->pDisconnect;
 174       db2->pDisconnect = pVTable;
 175     }
 176     pVTable = pNext;
 177   }
 178
 179   assert( !db || pRet );
 180   return pRet;
 181 }
 182
 183
 184 /*
 185 ** Disconnect all the virtual table objects in the sqlite3.pDisconnect list.
 186 **
 187 ** This function may only be called when the mutexes associated with all
 188 ** shared b-tree databases opened using connection db are held by the
 189 ** caller. This is done to protect the sqlite3.pDisconnect list. The
 190 ** sqlite3.pDisconnect list is accessed only as follows:
 191 **
 192 **   1) By this function. In this case, all BtShared mutexes and the mutex
 193 **      associated with the database handle itself must be held.
 194 **
 195 **   2) By function vtabDisconnectAll(), when it adds a VTable entry to
 196 **      the sqlite3.pDisconnect list. In this case either the BtShared mutex
 197 **      associated with the database the virtual table is stored in is held
 198 **      or, if the virtual table is stored in a non-sharable database, then
 199 **      the database handle mutex is held.
 200 **
 201 ** As a result, a sqlite3.pDisconnect cannot be accessed simultaneously
 202 ** by multiple threads. It is thread-safe.
 203 */
 204 void sqlite3VtabUnlockList(sqlite3 *db){
 205   VTable *p = db->pDisconnect;
 206   db->pDisconnect = 0;
 207
 208   assert( sqlite3BtreeHoldsAllMutexes(db) );
 209   assert( sqlite3_mutex_held(db->mutex) );
 210
 211   if( p ){
 212     sqlite3ExpirePreparedStatements(db);
 213     do {
 214       VTable *pNext = p->pNext;
 215       sqlite3VtabUnlock(p);
 216       p = pNext;
 217     }while( p );
 218   }
 219 }
 220
 221 /*
 222 ** Clear any and all virtual-table information from the Table record.
 223 ** This routine is called, for example, just before deleting the Table
 224 ** record.
 225 **
 226 ** Since it is a virtual-table, the Table structure contains a pointer
 227 ** to the head of a linked list of VTable structures. Each VTable
 228 ** structure is associated with a single sqlite3* user of the schema.
 229 ** The reference count of the VTable structure associated with database
 230 ** connection db is decremented immediately (which may lead to the
 231 ** structure being xDisconnected and free). Any other VTable structures
 232 ** in the list are moved to the sqlite3.pDisconnect list of the associated
 233 ** database connection.
 234 */
 235 void sqlite3VtabClear(sqlite3 *db, Table *p){
 236   if( !db || db->pnBytesFreed==0 ) vtabDisconnectAll(0, p);
 237   if( p->azModuleArg ){
 238     int i;
 239     for(i=0; i<p->nModuleArg; i++){
 240       sqlite3DbFree(db, p->azModuleArg[i]);
 241     }
 242     sqlite3DbFree(db, p->azModuleArg);
 243   }
 244 }
 245
 246 /*
 247 ** Add a new module argument to pTable->azModuleArg[].
 248 ** The string is not copied - the pointer is stored.  The
 249 ** string will be freed automatically when the table is
 250 ** deleted.
 251 */
 252 static void addModuleArgument(sqlite3 *db, Table *pTable, char *zArg){
 253   int i = pTable->nModuleArg++;
 254   int nBytes = sizeof(char *)*(1+pTable->nModuleArg);
 255   char **azModuleArg;
 256   azModuleArg = sqlite3DbRealloc(db, pTable->azModuleArg, nBytes);
 257   if( azModuleArg==0 ){
 258     int j;
 259     for(j=0; j<i; j++){
 260       sqlite3DbFree(db, pTable->azModuleArg[j]);
 261     }
 262     sqlite3DbFree(db, zArg);
 263     sqlite3DbFree(db, pTable->azModuleArg);
 264     pTable->nModuleArg = 0;
 265   }else{
 266     azModuleArg[i] = zArg;
 267     azModuleArg[i+1] = 0;
 268   }
 269   pTable->azModuleArg = azModuleArg;
 270 }
 271
 272 /*
 273 ** The parser calls this routine when it first sees a CREATE VIRTUAL TABLE
 274 ** statement.  The module name has been parsed, but the optional list
 275 ** of parameters that follow the module name are still pending.
 276 */
 277 void sqlite3VtabBeginParse(
 278   Parse *pParse,        /* Parsing context */
 279   Token *pName1,        /* Name of new table, or database name */
 280   Token *pName2,        /* Name of new table or NULL */
 281   Token *pModuleName,   /* Name of the module for the virtual table */
 282   int ifNotExists       /* No error if the table already exists */
 283 ){
 284   int iDb;              /* The database the table is being created in */
 285   Table *pTable;        /* The new virtual table */
 286   sqlite3 *db;          /* Database connection */
 287
 288   sqlite3StartTable(pParse, pName1, pName2, 0, 0, 1, ifNotExists);
 289   pTable = pParse->pNewTable;
 290   if( pTable==0 ) return;
 291   assert( 0==pTable->pIndex );
 292
 293   db = pParse->db;
 294   iDb = sqlite3SchemaToIndex(db, pTable->pSchema);
 295   assert( iDb>=0 );
 296
 297   pTable->tabFlags |= TF_Virtual;
 298   pTable->nModuleArg = 0;
 299   addModuleArgument(db, pTable, sqlite3NameFromToken(db, pModuleName));
 300   addModuleArgument(db, pTable, sqlite3DbStrDup(db, db->aDb[iDb].zName));
 301   addModuleArgument(db, pTable, sqlite3DbStrDup(db, pTable->zName));
 302   pParse->sNameToken.n = (int)(&pModuleName->z[pModuleName->n] - pName1->z);
 303
 304 #ifndef SQLITE_OMIT_AUTHORIZATION
 305   /* Creating a virtual table invokes the authorization callback twice.
 306   ** The first invocation, to obtain permission to INSERT a row into the
 307   ** sqlite_master table, has already been made by sqlite3StartTable().
 308   ** The second call, to obtain permission to create the table, is made now.
 309   */
 310   if( pTable->azModuleArg ){
 311     sqlite3AuthCheck(pParse, SQLITE_CREATE_VTABLE, pTable->zName,
 312             pTable->azModuleArg[0], pParse->db->aDb[iDb].zName);
 313   }
 314 #endif
 315 }
 316
 317 /*
 318 ** This routine takes the module argument that has been accumulating
 319 ** in pParse->zArg[] and appends it to the list of arguments on the
 320 ** virtual table currently under construction in pParse->pTable.
 321 */
 322 static void addArgumentToVtab(Parse *pParse){
 323   if( pParse->sArg.z && pParse->pNewTable ){
 324     const char *z = (const char*)pParse->sArg.z;
 325     int n = pParse->sArg.n;
 326     sqlite3 *db = pParse->db;
 327     addModuleArgument(db, pParse->pNewTable, sqlite3DbStrNDup(db, z, n));
 328   }
 329 }
 330
 331 /*
 332 ** The parser calls this routine after the CREATE VIRTUAL TABLE statement
 333 ** has been completely parsed.
 334 */
 335 void sqlite3VtabFinishParse(Parse *pParse, Token *pEnd){
 336   Table *pTab = pParse->pNewTable;  /* The table being constructed */
 337   sqlite3 *db = pParse->db;         /* The database connection */
 338
 339   if( pTab==0 ) return;
 340   addArgumentToVtab(pParse);
 341   pParse->sArg.z = 0;
 342   if( pTab->nModuleArg<1 ) return;
 343
 344   /* If the CREATE VIRTUAL TABLE statement is being entered for the
 345   ** first time (in other words if the virtual table is actually being
 346   ** created now instead of just being read out of sqlite_master) then
 347   ** do additional initialization work and store the statement text
 348   ** in the sqlite_master table.
 349   */
 350   if( !db->init.busy ){
 351     char *zStmt;
 352     char *zWhere;
 353     int iDb;
 354     Vdbe *v;
 355
 356     /* Compute the complete text of the CREATE VIRTUAL TABLE statement */
 357     if( pEnd ){
 358       pParse->sNameToken.n = (int)(pEnd->z - pParse->sNameToken.z) + pEnd->n;
 359     }
 360     zStmt = sqlite3MPrintf(db, "CREATE VIRTUAL TABLE %T", &pParse->sNameToken);
 361
 362     /* A slot for the record has already been allocated in the
 363     ** SQLITE_MASTER table.  We just need to update that slot with all
 364     ** the information we've collected.
 365     **
 366     ** The VM register number pParse->regRowid holds the rowid of an
 367     ** entry in the sqlite_master table tht was created for this vtab
 368     ** by sqlite3StartTable().
 369     */
 370     iDb = sqlite3SchemaToIndex(db, pTab->pSchema);
 371     sqlite3NestedParse(pParse,
 372       "UPDATE %Q.%s "
 373          "SET type='table', name=%Q, tbl_name=%Q, rootpage=0, sql=%Q "
 374        "WHERE rowid=#%d",
 375       db->aDb[iDb].zName, SCHEMA_TABLE(iDb),
 376       pTab->zName,
 377       pTab->zName,
 378       zStmt,
 379       pParse->regRowid
 380     );
 381     sqlite3DbFree(db, zStmt);
 382     v = sqlite3GetVdbe(pParse);
 383     sqlite3ChangeCookie(pParse, iDb);
 384
 385     sqlite3VdbeAddOp2(v, OP_Expire, 0, 0);
 386     zWhere = sqlite3MPrintf(db, "name='%q' AND type='table'", pTab->zName);
 387     sqlite3VdbeAddParseSchemaOp(v, iDb, zWhere);
 388     sqlite3VdbeAddOp4(v, OP_VCreate, iDb, 0, 0,
 389                          pTab->zName, sqlite3Strlen30(pTab->zName) + 1);
 390   }
 391
 392   /* If we are rereading the sqlite_master table create the in-memory
 393   ** record of the table. The xConnect() method is not called until
 394   ** the first time the virtual table is used in an SQL statement. This
 395   ** allows a schema that contains virtual tables to be loaded before
 396   ** the required virtual table implementations are registered.  */
 397   else {
 398     Table *pOld;
 399     Schema *pSchema = pTab->pSchema;
 400     const char *zName = pTab->zName;
 401     int nName = sqlite3Strlen30(zName);
 402     assert( sqlite3SchemaMutexHeld(db, 0, pSchema) );
 403     pOld = sqlite3HashInsert(&pSchema->tblHash, zName, nName, pTab);
 404     if( pOld ){
 405       db->mallocFailed = 1;
 406       assert( pTab==pOld );  /* Malloc must have failed inside HashInsert() */
 407       return;
 408     }
 409     pParse->pNewTable = 0;
 410   }
 411 }
 412
 413 /*
 414 ** The parser calls this routine when it sees the first token
 415 ** of an argument to the module name in a CREATE VIRTUAL TABLE statement.
 416 */
 417 void sqlite3VtabArgInit(Parse *pParse){
 418   addArgumentToVtab(pParse);
 419   pParse->sArg.z = 0;
 420   pParse->sArg.n = 0;
 421 }
 422
 423 /*
 424 ** The parser calls this routine for each token after the first token
 425 ** in an argument to the module name in a CREATE VIRTUAL TABLE statement.
 426 */
 427 void sqlite3VtabArgExtend(Parse *pParse, Token *p){
 428   Token *pArg = &pParse->sArg;
 429   if( pArg->z==0 ){
 430     pArg->z = p->z;
 431     pArg->n = p->n;
 432   }else{
 433     assert(pArg->z < p->z);
 434     pArg->n = (int)(&p->z[p->n] - pArg->z);
 435   }
 436 }
 437
 438 /*
 439 ** Invoke a virtual table constructor (either xCreate or xConnect). The
 440 ** pointer to the function to invoke is passed as the fourth parameter
 441 ** to this procedure.
 442 */
 443 static int vtabCallConstructor(
 444   sqlite3 *db,
 445   Table *pTab,
 446   Module *pMod,
 447   int (*xConstruct)(sqlite3*,void*,int,const char*const*,sqlite3_vtab**,char**),
 448   char **pzErr
 449 ){
 450   VtabCtx sCtx, *pPriorCtx;
 451   VTable *pVTable;
 452   int rc;
 453   const char *const*azArg = (const char *const*)pTab->azModuleArg;
 454   int nArg = pTab->nModuleArg;
 455   char *zErr = 0;
 456   char *zModuleName = sqlite3MPrintf(db, "%s", pTab->zName);
 457
 458   if( !zModuleName ){
 459     return SQLITE_NOMEM;
 460   }
 461
 462   pVTable = sqlite3DbMallocZero(db, sizeof(VTable));
 463   if( !pVTable ){
 464     sqlite3DbFree(db, zModuleName);
 465     return SQLITE_NOMEM;
 466   }
 467   pVTable->db = db;
 468   pVTable->pMod = pMod;
 469
 470   /* Invoke the virtual table constructor */
 471   assert( &db->pVtabCtx );
 472   assert( xConstruct );
 473   sCtx.pTab = pTab;
 474   sCtx.pVTable = pVTable;
 475   pPriorCtx = db->pVtabCtx;
 476   db->pVtabCtx = &sCtx;
 477   rc = xConstruct(db, pMod->pAux, nArg, azArg, &pVTable->pVtab, &zErr);
 478   db->pVtabCtx = pPriorCtx;
 479   if( rc==SQLITE_NOMEM ) db->mallocFailed = 1;
 480
 481   if( SQLITE_OK!=rc ){
 482     if( zErr==0 ){
 483       *pzErr = sqlite3MPrintf(db, "vtable constructor failed: %s", zModuleName);
 484     }else {
 485       *pzErr = sqlite3MPrintf(db, "%s", zErr);
 486       sqlite3_free(zErr);
 487     }
 488     sqlite3DbFree(db, pVTable);
 489   }else if( ALWAYS(pVTable->pVtab) ){
 490     /* Justification of ALWAYS():  A correct vtab constructor must allocate
 491     ** the sqlite3_vtab object if successful.  */
 492     pVTable->pVtab->pModule = pMod->pModule;
 493     pVTable->nRef = 1;
 494     if( sCtx.pTab ){
 495       const char *zFormat = "vtable constructor did not declare schema: %s";
 496       *pzErr = sqlite3MPrintf(db, zFormat, pTab->zName);
 497       sqlite3VtabUnlock(pVTable);
 498       rc = SQLITE_ERROR;
 499     }else{
 500       int iCol;
 501       /* If everything went according to plan, link the new VTable structure
 502       ** into the linked list headed by pTab->pVTable. Then loop through the
 503       ** columns of the table to see if any of them contain the token "hidden".
 504       ** If so, set the Column.isHidden flag and remove the token from
 505       ** the type string.  */
 506       pVTable->pNext = pTab->pVTable;
 507       pTab->pVTable = pVTable;
 508
 509       for(iCol=0; iCol<pTab->nCol; iCol++){
 510         char *zType = pTab->aCol[iCol].zType;
 511         int nType;
 512         int i = 0;
 513         if( !zType ) continue;
 514         nType = sqlite3Strlen30(zType);
 515         if( sqlite3StrNICmp("hidden", zType, 6)||(zType[6] && zType[6]!=' ') ){
 516           for(i=0; i<nType; i++){
 517             if( (0==sqlite3StrNICmp(" hidden", &zType[i], 7))
 518              && (zType[i+7]=='\0' || zType[i+7]==' ')
 519             ){
 520               i++;
 521               break;
 522             }
 523           }
 524         }
 525         if( i<nType ){
 526           int j;
 527           int nDel = 6 + (zType[i+6] ? 1 : 0);
 528           for(j=i; (j+nDel)<=nType; j++){
 529             zType[j] = zType[j+nDel];
 530           }
 531           if( zType[i]=='\0' && i>0 ){
 532             assert(zType[i-1]==' ');
 533             zType[i-1] = '\0';
 534           }
 535           pTab->aCol[iCol].isHidden = 1;
 536         }
 537       }
 538     }
 539   }
 540
 541   sqlite3DbFree(db, zModuleName);
 542   return rc;
 543 }
 544
 545 /*
 546 ** This function is invoked by the parser to call the xConnect() method
 547 ** of the virtual table pTab. If an error occurs, an error code is returned
 548 ** and an error left in pParse.
 549 **
 550 ** This call is a no-op if table pTab is not a virtual table.
 551 */
 552 int sqlite3VtabCallConnect(Parse *pParse, Table *pTab){
 553   sqlite3 *db = pParse->db;
 554   const char *zMod;
 555   Module *pMod;
 556   int rc;
 557
 558   assert( pTab );
 559   if( (pTab->tabFlags & TF_Virtual)==0 || sqlite3GetVTable(db, pTab) ){
 560     return SQLITE_OK;
 561   }
 562
 563   /* Locate the required virtual table module */
 564   zMod = pTab->azModuleArg[0];
 565   pMod = (Module*)sqlite3HashFind(&db->aModule, zMod, sqlite3Strlen30(zMod));
 566
 567   if( !pMod ){
 568     const char *zModule = pTab->azModuleArg[0];
 569     sqlite3ErrorMsg(pParse, "no such module: %s", zModule);
 570     rc = SQLITE_ERROR;
 571   }else{
 572     char *zErr = 0;
 573     rc = vtabCallConstructor(db, pTab, pMod, pMod->pModule->xConnect, &zErr);
 574     if( rc!=SQLITE_OK ){
 575       sqlite3ErrorMsg(pParse, "%s", zErr);
 576     }
 577     sqlite3DbFree(db, zErr);
 578   }
 579
 580   return rc;
 581 }
 582 /*
 583 ** Grow the db->aVTrans[] array so that there is room for at least one
 584 ** more v-table. Return SQLITE_NOMEM if a malloc fails, or SQLITE_OK otherwise.
 585 */
 586 static int growVTrans(sqlite3 *db){
 587   const int ARRAY_INCR = 5;
 588
 589   /* Grow the sqlite3.aVTrans array if required */
 590   if( (db->nVTrans%ARRAY_INCR)==0 ){
 591     VTable **aVTrans;
 592     int nBytes = sizeof(sqlite3_vtab *) * (db->nVTrans + ARRAY_INCR);
 593     aVTrans = sqlite3DbRealloc(db, (void *)db->aVTrans, nBytes);
 594     if( !aVTrans ){
 595       return SQLITE_NOMEM;
 596     }
 597     memset(&aVTrans[db->nVTrans], 0, sizeof(sqlite3_vtab *)*ARRAY_INCR);
 598     db->aVTrans = aVTrans;
 599   }
 600
 601   return SQLITE_OK;
 602 }
 603
 604 /*
 605 ** Add the virtual table pVTab to the array sqlite3.aVTrans[]. Space should
 606 ** have already been reserved using growVTrans().
 607 */
 608 static void addToVTrans(sqlite3 *db, VTable *pVTab){
 609   /* Add pVtab to the end of sqlite3.aVTrans */
 610   db->aVTrans[db->nVTrans++] = pVTab;
 611   sqlite3VtabLock(pVTab);
 612 }
 613
 614 /*
 615 ** This function is invoked by the vdbe to call the xCreate method
 616 ** of the virtual table named zTab in database iDb.
 617 **
 618 ** If an error occurs, *pzErr is set to point an an English language
 619 ** description of the error and an SQLITE_XXX error code is returned.
 620 ** In this case the caller must call sqlite3DbFree(db, ) on *pzErr.
 621 */
 622 int sqlite3VtabCallCreate(sqlite3 *db, int iDb, const char *zTab, char **pzErr){
 623   int rc = SQLITE_OK;
 624   Table *pTab;
 625   Module *pMod;
 626   const char *zMod;
 627
 628   pTab = sqlite3FindTable(db, zTab, db->aDb[iDb].zName);
 629   assert( pTab && (pTab->tabFlags & TF_Virtual)!=0 && !pTab->pVTable );
 630
 631   /* Locate the required virtual table module */
 632   zMod = pTab->azModuleArg[0];
 633   pMod = (Module*)sqlite3HashFind(&db->aModule, zMod, sqlite3Strlen30(zMod));
 634
 635   /* If the module has been registered and includes a Create method,
 636   ** invoke it now. If the module has not been registered, return an
 637   ** error. Otherwise, do nothing.
 638   */
 639   if( !pMod ){
 640     *pzErr = sqlite3MPrintf(db, "no such module: %s", zMod);
 641     rc = SQLITE_ERROR;
 642   }else{
 643     rc = vtabCallConstructor(db, pTab, pMod, pMod->pModule->xCreate, pzErr);
 644   }
 645
 646   /* Justification of ALWAYS():  The xConstructor method is required to
 647   ** create a valid sqlite3_vtab if it returns SQLITE_OK. */
 648   if( rc==SQLITE_OK && ALWAYS(sqlite3GetVTable(db, pTab)) ){
 649     rc = growVTrans(db);
 650     if( rc==SQLITE_OK ){
 651       addToVTrans(db, sqlite3GetVTable(db, pTab));
 652     }
 653   }
 654
 655   return rc;
 656 }
 657
 658 /*
 659 ** This function is used to set the schema of a virtual table.  It is only
 660 ** valid to call this function from within the xCreate() or xConnect() of a
 661 ** virtual table module.
 662 */
 663 int sqlite3_declare_vtab(sqlite3 *db, const char *zCreateTable){
 664   Parse *pParse;
 665
 666   int rc = SQLITE_OK;
 667   Table *pTab;
 668   char *zErr = 0;
 669
 670   sqlite3_mutex_enter(db->mutex);
 671   if( !db->pVtabCtx || !(pTab = db->pVtabCtx->pTab) ){
 672     sqlite3Error(db, SQLITE_MISUSE, 0);
 673     sqlite3_mutex_leave(db->mutex);
 674     return SQLITE_MISUSE_BKPT;
 675   }
 676   assert( (pTab->tabFlags & TF_Virtual)!=0 );
 677
 678   pParse = sqlite3StackAllocZero(db, sizeof(*pParse));
 679   if( pParse==0 ){
 680     rc = SQLITE_NOMEM;
 681   }else{
 682     pParse->declareVtab = 1;
 683     pParse->db = db;
 684     pParse->nQueryLoop = 1;
 685
 686     if( SQLITE_OK==sqlite3RunParser(pParse, zCreateTable, &zErr)
 687      && pParse->pNewTable
 688      && !db->mallocFailed
 689      && !pParse->pNewTable->pSelect
 690      && (pParse->pNewTable->tabFlags & TF_Virtual)==0
 691     ){
 692       if( !pTab->aCol ){
 693         pTab->aCol = pParse->pNewTable->aCol;
 694         pTab->nCol = pParse->pNewTable->nCol;
 695         pParse->pNewTable->nCol = 0;
 696         pParse->pNewTable->aCol = 0;
 697       }
 698       db->pVtabCtx->pTab = 0;
 699     }else{
 700       sqlite3Error(db, SQLITE_ERROR, (zErr ? "%s" : 0), zErr);
 701       sqlite3DbFree(db, zErr);
 702       rc = SQLITE_ERROR;
 703     }
 704     pParse->declareVtab = 0;
 705
 706     if( pParse->pVdbe ){
 707       sqlite3VdbeFinalize(pParse->pVdbe);
 708     }
 709     sqlite3DeleteTable(db, pParse->pNewTable);
 710     sqlite3StackFree(db, pParse);
 711   }
 712
 713   assert( (rc&0xff)==rc );
 714   rc = sqlite3ApiExit(db, rc);
 715   sqlite3_mutex_leave(db->mutex);
 716   return rc;
 717 }
 718
 719 /*
 720 ** This function is invoked by the vdbe to call the xDestroy method
 721 ** of the virtual table named zTab in database iDb. This occurs
 722 ** when a DROP TABLE is mentioned.
 723 **
 724 ** This call is a no-op if zTab is not a virtual table.
 725 */
 726 int sqlite3VtabCallDestroy(sqlite3 *db, int iDb, const char *zTab){
 727   int rc = SQLITE_OK;
 728   Table *pTab;
 729
 730   pTab = sqlite3FindTable(db, zTab, db->aDb[iDb].zName);
 731   if( ALWAYS(pTab!=0 && pTab->pVTable!=0) ){
 732     VTable *p = vtabDisconnectAll(db, pTab);
 733
 734     assert( rc==SQLITE_OK );
 735     rc = p->pMod->pModule->xDestroy(p->pVtab);
 736
 737     /* Remove the sqlite3_vtab* from the aVTrans[] array, if applicable */
 738     if( rc==SQLITE_OK ){
 739       assert( pTab->pVTable==p && p->pNext==0 );
 740       p->pVtab = 0;
 741       pTab->pVTable = 0;
 742       sqlite3VtabUnlock(p);
 743     }
 744   }
 745
 746   return rc;
 747 }
 748
 749 /*
 750 ** This function invokes either the xRollback or xCommit method
 751 ** of each of the virtual tables in the sqlite3.aVTrans array. The method
 752 ** called is identified by the second argument, "offset", which is
 753 ** the offset of the method to call in the sqlite3_module structure.
 754 **
 755 ** The array is cleared after invoking the callbacks.
 756 */
 757 static void callFinaliser(sqlite3 *db, int offset){
 758   int i;
 759   if( db->aVTrans ){
 760     for(i=0; i<db->nVTrans; i++){
 761       VTable *pVTab = db->aVTrans[i];
 762       sqlite3_vtab *p = pVTab->pVtab;
 763       if( p ){
 764         int (*x)(sqlite3_vtab *);
 765         x = *(int (**)(sqlite3_vtab *))((char *)p->pModule + offset);
 766         if( x ) x(p);
 767       }
 768       pVTab->iSavepoint = 0;
 769       sqlite3VtabUnlock(pVTab);
 770     }
 771     sqlite3DbFree(db, db->aVTrans);
 772     db->nVTrans = 0;
 773     db->aVTrans = 0;
 774   }
 775 }
 776
 777 /*
 778 ** Invoke the xSync method of all virtual tables in the sqlite3.aVTrans
 779 ** array. Return the error code for the first error that occurs, or
 780 ** SQLITE_OK if all xSync operations are successful.
 781 **
 782 ** Set *pzErrmsg to point to a buffer that should be released using
 783 ** sqlite3DbFree() containing an error message, if one is available.
 784 */
 785 int sqlite3VtabSync(sqlite3 *db, char **pzErrmsg){
 786   int i;
 787   int rc = SQLITE_OK;
 788   VTable **aVTrans = db->aVTrans;
 789
 790   db->aVTrans = 0;
 791   for(i=0; rc==SQLITE_OK && i<db->nVTrans; i++){
 792     int (*x)(sqlite3_vtab *);
 793     sqlite3_vtab *pVtab = aVTrans[i]->pVtab;
 794     if( pVtab && (x = pVtab->pModule->xSync)!=0 ){
 795       rc = x(pVtab);
 796       sqlite3DbFree(db, *pzErrmsg);
 797       *pzErrmsg = sqlite3DbStrDup(db, pVtab->zErrMsg);
 798       sqlite3_free(pVtab->zErrMsg);
 799     }
 800   }
 801   db->aVTrans = aVTrans;
 802   return rc;
 803 }
 804
 805 /*
 806 ** Invoke the xRollback method of all virtual tables in the
 807 ** sqlite3.aVTrans array. Then clear the array itself.
 808 */
 809 int sqlite3VtabRollback(sqlite3 *db){
 810   callFinaliser(db, offsetof(sqlite3_module,xRollback));
 811   return SQLITE_OK;
 812 }
 813
 814 /*
 815 ** Invoke the xCommit method of all virtual tables in the
 816 ** sqlite3.aVTrans array. Then clear the array itself.
 817 */
 818 int sqlite3VtabCommit(sqlite3 *db){
 819   callFinaliser(db, offsetof(sqlite3_module,xCommit));
 820   return SQLITE_OK;
 821 }
 822
 823 /*
 824 ** If the virtual table pVtab supports the transaction interface
 825 ** (xBegin/xRollback/xCommit and optionally xSync) and a transaction is
 826 ** not currently open, invoke the xBegin method now.
 827 **
 828 ** If the xBegin call is successful, place the sqlite3_vtab pointer
 829 ** in the sqlite3.aVTrans array.
 830 */
 831 int sqlite3VtabBegin(sqlite3 *db, VTable *pVTab){
 832   int rc = SQLITE_OK;
 833   const sqlite3_module *pModule;
 834
 835   /* Special case: If db->aVTrans is NULL and db->nVTrans is greater
 836   ** than zero, then this function is being called from within a
 837   ** virtual module xSync() callback. It is illegal to write to
 838   ** virtual module tables in this case, so return SQLITE_LOCKED.
 839   */
 840   if( sqlite3VtabInSync(db) ){
 841     return SQLITE_LOCKED;
 842   }
 843   if( !pVTab ){
 844     return SQLITE_OK;
 845   }
 846   pModule = pVTab->pVtab->pModule;
 847
 848   if( pModule->xBegin ){
 849     int i;
 850
 851     /* If pVtab is already in the aVTrans array, return early */
 852     for(i=0; i<db->nVTrans; i++){
 853       if( db->aVTrans[i]==pVTab ){
 854         return SQLITE_OK;
 855       }
 856     }
 857
 858     /* Invoke the xBegin method. If successful, add the vtab to the
 859     ** sqlite3.aVTrans[] array. */
 860     rc = growVTrans(db);
 861     if( rc==SQLITE_OK ){
 862       rc = pModule->xBegin(pVTab->pVtab);
 863       if( rc==SQLITE_OK ){
 864         addToVTrans(db, pVTab);
 865       }
 866     }
 867   }
 868   return rc;
 869 }
 870
 871 /*
 872 ** Invoke either the xSavepoint, xRollbackTo or xRelease method of all
 873 ** virtual tables that currently have an open transaction. Pass iSavepoint
 874 ** as the second argument to the virtual table method invoked.
 875 **
 876 ** If op is SAVEPOINT_BEGIN, the xSavepoint method is invoked. If it is
 877 ** SAVEPOINT_ROLLBACK, the xRollbackTo method. Otherwise, if op is
 878 ** SAVEPOINT_RELEASE, then the xRelease method of each virtual table with
 879 ** an open transaction is invoked.
 880 **
 881 ** If any virtual table method returns an error code other than SQLITE_OK,
 882 ** processing is abandoned and the error returned to the caller of this
 883 ** function immediately. If all calls to virtual table methods are successful,
 884 ** SQLITE_OK is returned.
 885 */
 886 int sqlite3VtabSavepoint(sqlite3 *db, int op, int iSavepoint){
 887   int rc = SQLITE_OK;
 888
 889   assert( op==SAVEPOINT_RELEASE||op==SAVEPOINT_ROLLBACK||op==SAVEPOINT_BEGIN );
 890   assert( iSavepoint>=0 );
 891   if( db->aVTrans ){
 892     int i;
 893     for(i=0; rc==SQLITE_OK && i<db->nVTrans; i++){
 894       VTable *pVTab = db->aVTrans[i];
 895       const sqlite3_module *pMod = pVTab->pMod->pModule;
 896       if( pVTab->pVtab && pMod->iVersion>=2 ){
 897         int (*xMethod)(sqlite3_vtab *, int);
 898         switch( op ){
 899           case SAVEPOINT_BEGIN:
 900             xMethod = pMod->xSavepoint;
 901             pVTab->iSavepoint = iSavepoint+1;
 902             break;
 903           case SAVEPOINT_ROLLBACK:
 904             xMethod = pMod->xRollbackTo;
 905             break;
 906           default:
 907             xMethod = pMod->xRelease;
 908             break;
 909         }
 910         if( xMethod && pVTab->iSavepoint>iSavepoint ){
 911           rc = xMethod(pVTab->pVtab, iSavepoint);
 912         }
 913       }
 914     }
 915   }
 916   return rc;
 917 }
 918
 919 /*
 920 ** The first parameter (pDef) is a function implementation.  The
 921 ** second parameter (pExpr) is the first argument to this function.
 922 ** If pExpr is a column in a virtual table, then let the virtual
 923 ** table implementation have an opportunity to overload the function.
 924 **
 925 ** This routine is used to allow virtual table implementations to
 926 ** overload MATCH, LIKE, GLOB, and REGEXP operators.
 927 **
 928 ** Return either the pDef argument (indicating no change) or a
 929 ** new FuncDef structure that is marked as ephemeral using the
 930 ** SQLITE_FUNC_EPHEM flag.
 931 */
 932 FuncDef *sqlite3VtabOverloadFunction(
 933   sqlite3 *db,    /* Database connection for reporting malloc problems */
 934   FuncDef *pDef,  /* Function to possibly overload */
 935   int nArg,       /* Number of arguments to the function */
 936   Expr *pExpr     /* First argument to the function */
 937 ){
 938   Table *pTab;
 939   sqlite3_vtab *pVtab;
 940   sqlite3_module *pMod;
 941   void (*xFunc)(sqlite3_context*,int,sqlite3_value**) = 0;
 942   void *pArg = 0;
 943   FuncDef *pNew;
 944   int rc = 0;
 945   char *zLowerName;
 946   unsigned char *z;
 947
 948
 949   /* Check to see the left operand is a column in a virtual table */
 950   if( NEVER(pExpr==0) ) return pDef;
 951   if( pExpr->op!=TK_COLUMN ) return pDef;
 952   pTab = pExpr->pTab;
 953   if( NEVER(pTab==0) ) return pDef;
 954   if( (pTab->tabFlags & TF_Virtual)==0 ) return pDef;
 955   pVtab = sqlite3GetVTable(db, pTab)->pVtab;
 956   assert( pVtab!=0 );
 957   assert( pVtab->pModule!=0 );
 958   pMod = (sqlite3_module *)pVtab->pModule;
 959   if( pMod->xFindFunction==0 ) return pDef;
 960
 961   /* Call the xFindFunction method on the virtual table implementation
 962   ** to see if the implementation wants to overload this function
 963   */
 964   zLowerName = sqlite3DbStrDup(db, pDef->zName);
 965   if( zLowerName ){
 966     for(z=(unsigned char*)zLowerName; *z; z++){
 967       *z = sqlite3UpperToLower[*z];
 968     }
 969     rc = pMod->xFindFunction(pVtab, nArg, zLowerName, &xFunc, &pArg);
 970     sqlite3DbFree(db, zLowerName);
 971   }
 972   if( rc==0 ){
 973     return pDef;
 974   }
 975
 976   /* Create a new ephemeral function definition for the overloaded
 977   ** function */
 978   pNew = sqlite3DbMallocZero(db, sizeof(*pNew)
 979                              + sqlite3Strlen30(pDef->zName) + 1);
 980   if( pNew==0 ){
 981     return pDef;
 982   }
 983   *pNew = *pDef;
 984   pNew->zName = (char *)&pNew[1];
 985   memcpy(pNew->zName, pDef->zName, sqlite3Strlen30(pDef->zName)+1);
 986   pNew->xFunc = xFunc;
 987   pNew->pUserData = pArg;
 988   pNew->flags |= SQLITE_FUNC_EPHEM;
 989   return pNew;
 990 }
 991
 992 /*
 993 ** Make sure virtual table pTab is contained in the pParse->apVirtualLock[]
 994 ** array so that an OP_VBegin will get generated for it.  Add pTab to the
 995 ** array if it is missing.  If pTab is already in the array, this routine
 996 ** is a no-op.
 997 */
 998 void sqlite3VtabMakeWritable(Parse *pParse, Table *pTab){
 999   Parse *pToplevel = sqlite3ParseToplevel(pParse);
1000   int i, n;
1001   Table **apVtabLock;
1002
1003   assert( IsVirtual(pTab) );
1004   for(i=0; i<pToplevel->nVtabLock; i++){
1005     if( pTab==pToplevel->apVtabLock[i] ) return;
1006   }
1007   n = (pToplevel->nVtabLock+1)*sizeof(pToplevel->apVtabLock[0]);
1008   apVtabLock = sqlite3_realloc(pToplevel->apVtabLock, n);
1009   if( apVtabLock ){
1010     pToplevel->apVtabLock = apVtabLock;
1011     pToplevel->apVtabLock[pToplevel->nVtabLock++] = pTab;
1012   }else{
1013     pToplevel->db->mallocFailed = 1;
1014   }
1015 }
1016
1017 /*
1018 ** Return the ON CONFLICT resolution mode in effect for the virtual
1019 ** table update operation currently in progress.
1020 **
1021 ** The results of this routine are undefined unless it is called from
1022 ** within an xUpdate method.
1023 */
1024 int sqlite3_vtab_on_conflict(sqlite3 *db){
1025   static const unsigned char aMap[] = {
1026     SQLITE_ROLLBACK, SQLITE_ABORT, SQLITE_FAIL, SQLITE_IGNORE, SQLITE_REPLACE
1027   };
1028   assert( OE_Rollback==1 && OE_Abort==2 && OE_Fail==3 );
1029   assert( OE_Ignore==4 && OE_Replace==5 );
1030   assert( db->vtabOnConflict>=1 && db->vtabOnConflict<=5 );
1031   return (int)aMap[db->vtabOnConflict-1];
1032 }
1033
1034 /*
1035 ** Call from within the xCreate() or xConnect() methods to provide
1036 ** the SQLite core with additional information about the behavior
1037 ** of the virtual table being implemented.
1038 */
1039 int sqlite3_vtab_config(sqlite3 *db, int op, ...){
1040   va_list ap;
1041   int rc = SQLITE_OK;
1042
1043   sqlite3_mutex_enter(db->mutex);
1044
1045   va_start(ap, op);
1046   switch( op ){
1047     case SQLITE_VTAB_CONSTRAINT_SUPPORT: {
1048       VtabCtx *p = db->pVtabCtx;
1049       if( !p ){
1050         rc = SQLITE_MISUSE_BKPT;
1051       }else{
1052         assert( p->pTab==0 || (p->pTab->tabFlags & TF_Virtual)!=0 );
1053         p->pVTable->bConstraint = (u8)va_arg(ap, int);
1054       }
1055       break;
1056     }
1057     default:
1058       rc = SQLITE_MISUSE_BKPT;
1059       break;
1060   }
1061   va_end(ap);
1062
1063   if( rc!=SQLITE_OK ) sqlite3Error(db, rc, 0);
1064   sqlite3_mutex_leave(db->mutex);
1065   return rc;
1066 }
1067
1068 #endif /* SQLITE_OMIT_VIRTUALTABLE */