sl@0: /*
sl@0: ** 2006 June 10
sl@0: **
sl@0: ** The author disclaims copyright to this source code.  In place of
sl@0: ** a legal notice, here is a blessing:
sl@0: **
sl@0: **    May you do good and not evil.
sl@0: **    May you find forgiveness for yourself and forgive others.
sl@0: **    May you share freely, never taking more than you give.
sl@0: **
sl@0: *************************************************************************
sl@0: ** This file contains code used to help implement virtual tables.
sl@0: **
sl@0: ** $Id: vtab.c,v 1.76 2008/08/20 16:35:10 drh Exp $
sl@0: */
sl@0: #ifndef SQLITE_OMIT_VIRTUALTABLE
sl@0: #include "sqliteInt.h"
sl@0: 
sl@0: static int createModule(
sl@0:   sqlite3 *db,                    /* Database in which module is registered */
sl@0:   const char *zName,              /* Name assigned to this module */
sl@0:   const sqlite3_module *pModule,  /* The definition of the module */
sl@0:   void *pAux,                     /* Context pointer for xCreate/xConnect */
sl@0:   void (*xDestroy)(void *)        /* Module destructor function */
sl@0: ) {
sl@0:   int rc, nName;
sl@0:   Module *pMod;
sl@0: 
sl@0:   sqlite3_mutex_enter(db->mutex);
sl@0:   nName = strlen(zName);
sl@0:   pMod = (Module *)sqlite3DbMallocRaw(db, sizeof(Module) + nName + 1);
sl@0:   if( pMod ){
sl@0:     Module *pDel;
sl@0:     char *zCopy = (char *)(&pMod[1]);
sl@0:     memcpy(zCopy, zName, nName+1);
sl@0:     pMod->zName = zCopy;
sl@0:     pMod->pModule = pModule;
sl@0:     pMod->pAux = pAux;
sl@0:     pMod->xDestroy = xDestroy;
sl@0:     pDel = (Module *)sqlite3HashInsert(&db->aModule, zCopy, nName, (void*)pMod);
sl@0:     if( pDel && pDel->xDestroy ){
sl@0:       pDel->xDestroy(pDel->pAux);
sl@0:     }
sl@0:     sqlite3DbFree(db, pDel);
sl@0:     if( pDel==pMod ){
sl@0:       db->mallocFailed = 1;
sl@0:     }
sl@0:     sqlite3ResetInternalSchema(db, 0);
sl@0:   }
sl@0:   rc = sqlite3ApiExit(db, SQLITE_OK);
sl@0:   sqlite3_mutex_leave(db->mutex);
sl@0:   return rc;
sl@0: }
sl@0: 
sl@0: 
sl@0: /*
sl@0: ** External API function used to create a new virtual-table module.
sl@0: */
sl@0: int sqlite3_create_module(
sl@0:   sqlite3 *db,                    /* Database in which module is registered */
sl@0:   const char *zName,              /* Name assigned to this module */
sl@0:   const sqlite3_module *pModule,  /* The definition of the module */
sl@0:   void *pAux                      /* Context pointer for xCreate/xConnect */
sl@0: ){
sl@0:   return createModule(db, zName, pModule, pAux, 0);
sl@0: }
sl@0: 
sl@0: /*
sl@0: ** External API function used to create a new virtual-table module.
sl@0: */
sl@0: int sqlite3_create_module_v2(
sl@0:   sqlite3 *db,                    /* Database in which module is registered */
sl@0:   const char *zName,              /* Name assigned to this module */
sl@0:   const sqlite3_module *pModule,  /* The definition of the module */
sl@0:   void *pAux,                     /* Context pointer for xCreate/xConnect */
sl@0:   void (*xDestroy)(void *)        /* Module destructor function */
sl@0: ){
sl@0:   return createModule(db, zName, pModule, pAux, xDestroy);
sl@0: }
sl@0: 
sl@0: /*
sl@0: ** Lock the virtual table so that it cannot be disconnected.
sl@0: ** Locks nest.  Every lock should have a corresponding unlock.
sl@0: ** If an unlock is omitted, resources leaks will occur.  
sl@0: **
sl@0: ** If a disconnect is attempted while a virtual table is locked,
sl@0: ** the disconnect is deferred until all locks have been removed.
sl@0: */
sl@0: void sqlite3VtabLock(sqlite3_vtab *pVtab){
sl@0:   pVtab->nRef++;
sl@0: }
sl@0: 
sl@0: /*
sl@0: ** Unlock a virtual table.  When the last lock is removed,
sl@0: ** disconnect the virtual table.
sl@0: */
sl@0: void sqlite3VtabUnlock(sqlite3 *db, sqlite3_vtab *pVtab){
sl@0:   pVtab->nRef--;
sl@0:   assert(db);
sl@0:   assert( sqlite3SafetyCheckOk(db) );
sl@0:   if( pVtab->nRef==0 ){
sl@0:     if( db->magic==SQLITE_MAGIC_BUSY ){
sl@0:       (void)sqlite3SafetyOff(db);
sl@0:       pVtab->pModule->xDisconnect(pVtab);
sl@0:       (void)sqlite3SafetyOn(db);
sl@0:     } else {
sl@0:       pVtab->pModule->xDisconnect(pVtab);
sl@0:     }
sl@0:   }
sl@0: }
sl@0: 
sl@0: /*
sl@0: ** Clear any and all virtual-table information from the Table record.
sl@0: ** This routine is called, for example, just before deleting the Table
sl@0: ** record.
sl@0: */
sl@0: void sqlite3VtabClear(Table *p){
sl@0:   sqlite3_vtab *pVtab = p->pVtab;
sl@0:   sqlite3 *db = p->db;
sl@0:   if( pVtab ){
sl@0:     assert( p->pMod && p->pMod->pModule );
sl@0:     sqlite3VtabUnlock(db, pVtab);
sl@0:     p->pVtab = 0;
sl@0:   }
sl@0:   if( p->azModuleArg ){
sl@0:     int i;
sl@0:     for(i=0; i<p->nModuleArg; i++){
sl@0:       sqlite3DbFree(db, p->azModuleArg[i]);
sl@0:     }
sl@0:     sqlite3DbFree(db, p->azModuleArg);
sl@0:   }
sl@0: }
sl@0: 
sl@0: /*
sl@0: ** Add a new module argument to pTable->azModuleArg[].
sl@0: ** The string is not copied - the pointer is stored.  The
sl@0: ** string will be freed automatically when the table is
sl@0: ** deleted.
sl@0: */
sl@0: static void addModuleArgument(sqlite3 *db, Table *pTable, char *zArg){
sl@0:   int i = pTable->nModuleArg++;
sl@0:   int nBytes = sizeof(char *)*(1+pTable->nModuleArg);
sl@0:   char **azModuleArg;
sl@0:   azModuleArg = sqlite3DbRealloc(db, pTable->azModuleArg, nBytes);
sl@0:   if( azModuleArg==0 ){
sl@0:     int j;
sl@0:     for(j=0; j<i; j++){
sl@0:       sqlite3DbFree(db, pTable->azModuleArg[j]);
sl@0:     }
sl@0:     sqlite3DbFree(db, zArg);
sl@0:     sqlite3DbFree(db, pTable->azModuleArg);
sl@0:     pTable->nModuleArg = 0;
sl@0:   }else{
sl@0:     azModuleArg[i] = zArg;
sl@0:     azModuleArg[i+1] = 0;
sl@0:   }
sl@0:   pTable->azModuleArg = azModuleArg;
sl@0: }
sl@0: 
sl@0: /*
sl@0: ** The parser calls this routine when it first sees a CREATE VIRTUAL TABLE
sl@0: ** statement.  The module name has been parsed, but the optional list
sl@0: ** of parameters that follow the module name are still pending.
sl@0: */
sl@0: void sqlite3VtabBeginParse(
sl@0:   Parse *pParse,        /* Parsing context */
sl@0:   Token *pName1,        /* Name of new table, or database name */
sl@0:   Token *pName2,        /* Name of new table or NULL */
sl@0:   Token *pModuleName    /* Name of the module for the virtual table */
sl@0: ){
sl@0:   int iDb;              /* The database the table is being created in */
sl@0:   Table *pTable;        /* The new virtual table */
sl@0:   sqlite3 *db;          /* Database connection */
sl@0: 
sl@0:   if( pParse->db->flags & SQLITE_SharedCache ){
sl@0:     sqlite3ErrorMsg(pParse, "Cannot use virtual tables in shared-cache mode");
sl@0:     return;
sl@0:   }
sl@0: 
sl@0:   sqlite3StartTable(pParse, pName1, pName2, 0, 0, 1, 0);
sl@0:   pTable = pParse->pNewTable;
sl@0:   if( pTable==0 || pParse->nErr ) return;
sl@0:   assert( 0==pTable->pIndex );
sl@0: 
sl@0:   db = pParse->db;
sl@0:   iDb = sqlite3SchemaToIndex(db, pTable->pSchema);
sl@0:   assert( iDb>=0 );
sl@0: 
sl@0:   pTable->tabFlags |= TF_Virtual;
sl@0:   pTable->nModuleArg = 0;
sl@0:   addModuleArgument(db, pTable, sqlite3NameFromToken(db, pModuleName));
sl@0:   addModuleArgument(db, pTable, sqlite3DbStrDup(db, db->aDb[iDb].zName));
sl@0:   addModuleArgument(db, pTable, sqlite3DbStrDup(db, pTable->zName));
sl@0:   pParse->sNameToken.n = pModuleName->z + pModuleName->n - pName1->z;
sl@0: 
sl@0: #ifndef SQLITE_OMIT_AUTHORIZATION
sl@0:   /* Creating a virtual table invokes the authorization callback twice.
sl@0:   ** The first invocation, to obtain permission to INSERT a row into the
sl@0:   ** sqlite_master table, has already been made by sqlite3StartTable().
sl@0:   ** The second call, to obtain permission to create the table, is made now.
sl@0:   */
sl@0:   if( pTable->azModuleArg ){
sl@0:     sqlite3AuthCheck(pParse, SQLITE_CREATE_VTABLE, pTable->zName, 
sl@0:             pTable->azModuleArg[0], pParse->db->aDb[iDb].zName);
sl@0:   }
sl@0: #endif
sl@0: }
sl@0: 
sl@0: /*
sl@0: ** This routine takes the module argument that has been accumulating
sl@0: ** in pParse->zArg[] and appends it to the list of arguments on the
sl@0: ** virtual table currently under construction in pParse->pTable.
sl@0: */
sl@0: static void addArgumentToVtab(Parse *pParse){
sl@0:   if( pParse->sArg.z && pParse->pNewTable ){
sl@0:     const char *z = (const char*)pParse->sArg.z;
sl@0:     int n = pParse->sArg.n;
sl@0:     sqlite3 *db = pParse->db;
sl@0:     addModuleArgument(db, pParse->pNewTable, sqlite3DbStrNDup(db, z, n));
sl@0:   }
sl@0: }
sl@0: 
sl@0: /*
sl@0: ** The parser calls this routine after the CREATE VIRTUAL TABLE statement
sl@0: ** has been completely parsed.
sl@0: */
sl@0: void sqlite3VtabFinishParse(Parse *pParse, Token *pEnd){
sl@0:   Table *pTab;        /* The table being constructed */
sl@0:   sqlite3 *db;        /* The database connection */
sl@0:   char *zModule;      /* The module name of the table: USING modulename */
sl@0:   Module *pMod = 0;
sl@0: 
sl@0:   addArgumentToVtab(pParse);
sl@0:   pParse->sArg.z = 0;
sl@0: 
sl@0:   /* Lookup the module name. */
sl@0:   pTab = pParse->pNewTable;
sl@0:   if( pTab==0 ) return;
sl@0:   db = pParse->db;
sl@0:   if( pTab->nModuleArg<1 ) return;
sl@0:   zModule = pTab->azModuleArg[0];
sl@0:   pMod = (Module *)sqlite3HashFind(&db->aModule, zModule, strlen(zModule));
sl@0:   pTab->pMod = pMod;
sl@0:   
sl@0:   /* If the CREATE VIRTUAL TABLE statement is being entered for the
sl@0:   ** first time (in other words if the virtual table is actually being
sl@0:   ** created now instead of just being read out of sqlite_master) then
sl@0:   ** do additional initialization work and store the statement text
sl@0:   ** in the sqlite_master table.
sl@0:   */
sl@0:   if( !db->init.busy ){
sl@0:     char *zStmt;
sl@0:     char *zWhere;
sl@0:     int iDb;
sl@0:     Vdbe *v;
sl@0: 
sl@0:     /* Compute the complete text of the CREATE VIRTUAL TABLE statement */
sl@0:     if( pEnd ){
sl@0:       pParse->sNameToken.n = pEnd->z - pParse->sNameToken.z + pEnd->n;
sl@0:     }
sl@0:     zStmt = sqlite3MPrintf(db, "CREATE VIRTUAL TABLE %T", &pParse->sNameToken);
sl@0: 
sl@0:     /* A slot for the record has already been allocated in the 
sl@0:     ** SQLITE_MASTER table.  We just need to update that slot with all
sl@0:     ** the information we've collected.  
sl@0:     **
sl@0:     ** The VM register number pParse->regRowid holds the rowid of an
sl@0:     ** entry in the sqlite_master table tht was created for this vtab
sl@0:     ** by sqlite3StartTable().
sl@0:     */
sl@0:     iDb = sqlite3SchemaToIndex(db, pTab->pSchema);
sl@0:     sqlite3NestedParse(pParse,
sl@0:       "UPDATE %Q.%s "
sl@0:          "SET type='table', name=%Q, tbl_name=%Q, rootpage=0, sql=%Q "
sl@0:        "WHERE rowid=#%d",
sl@0:       db->aDb[iDb].zName, SCHEMA_TABLE(iDb),
sl@0:       pTab->zName,
sl@0:       pTab->zName,
sl@0:       zStmt,
sl@0:       pParse->regRowid
sl@0:     );
sl@0:     sqlite3DbFree(db, zStmt);
sl@0:     v = sqlite3GetVdbe(pParse);
sl@0:     sqlite3ChangeCookie(pParse, iDb);
sl@0: 
sl@0:     sqlite3VdbeAddOp2(v, OP_Expire, 0, 0);
sl@0:     zWhere = sqlite3MPrintf(db, "name='%q'", pTab->zName);
sl@0:     sqlite3VdbeAddOp4(v, OP_ParseSchema, iDb, 1, 0, zWhere, P4_DYNAMIC);
sl@0:     sqlite3VdbeAddOp4(v, OP_VCreate, iDb, 0, 0, 
sl@0:                          pTab->zName, strlen(pTab->zName) + 1);
sl@0:   }
sl@0: 
sl@0:   /* If we are rereading the sqlite_master table create the in-memory
sl@0:   ** record of the table. If the module has already been registered,
sl@0:   ** also call the xConnect method here.
sl@0:   */
sl@0:   else {
sl@0:     Table *pOld;
sl@0:     Schema *pSchema = pTab->pSchema;
sl@0:     const char *zName = pTab->zName;
sl@0:     int nName = strlen(zName) + 1;
sl@0:     pOld = sqlite3HashInsert(&pSchema->tblHash, zName, nName, pTab);
sl@0:     if( pOld ){
sl@0:       db->mallocFailed = 1;
sl@0:       assert( pTab==pOld );  /* Malloc must have failed inside HashInsert() */
sl@0:       return;
sl@0:     }
sl@0:     pSchema->db = pParse->db;
sl@0:     pParse->pNewTable = 0;
sl@0:   }
sl@0: }
sl@0: 
sl@0: /*
sl@0: ** The parser calls this routine when it sees the first token
sl@0: ** of an argument to the module name in a CREATE VIRTUAL TABLE statement.
sl@0: */
sl@0: void sqlite3VtabArgInit(Parse *pParse){
sl@0:   addArgumentToVtab(pParse);
sl@0:   pParse->sArg.z = 0;
sl@0:   pParse->sArg.n = 0;
sl@0: }
sl@0: 
sl@0: /*
sl@0: ** The parser calls this routine for each token after the first token
sl@0: ** in an argument to the module name in a CREATE VIRTUAL TABLE statement.
sl@0: */
sl@0: void sqlite3VtabArgExtend(Parse *pParse, Token *p){
sl@0:   Token *pArg = &pParse->sArg;
sl@0:   if( pArg->z==0 ){
sl@0:     pArg->z = p->z;
sl@0:     pArg->n = p->n;
sl@0:   }else{
sl@0:     assert(pArg->z < p->z);
sl@0:     pArg->n = (p->z + p->n - pArg->z);
sl@0:   }
sl@0: }
sl@0: 
sl@0: /*
sl@0: ** Invoke a virtual table constructor (either xCreate or xConnect). The
sl@0: ** pointer to the function to invoke is passed as the fourth parameter
sl@0: ** to this procedure.
sl@0: */
sl@0: static int vtabCallConstructor(
sl@0:   sqlite3 *db, 
sl@0:   Table *pTab,
sl@0:   Module *pMod,
sl@0:   int (*xConstruct)(sqlite3*,void*,int,const char*const*,sqlite3_vtab**,char**),
sl@0:   char **pzErr
sl@0: ){
sl@0:   int rc;
sl@0:   int rc2;
sl@0:   sqlite3_vtab *pVtab = 0;
sl@0:   const char *const*azArg = (const char *const*)pTab->azModuleArg;
sl@0:   int nArg = pTab->nModuleArg;
sl@0:   char *zErr = 0;
sl@0:   char *zModuleName = sqlite3MPrintf(db, "%s", pTab->zName);
sl@0: 
sl@0:   if( !zModuleName ){
sl@0:     return SQLITE_NOMEM;
sl@0:   }
sl@0: 
sl@0:   assert( !db->pVTab );
sl@0:   assert( xConstruct );
sl@0: 
sl@0:   db->pVTab = pTab;
sl@0:   rc = sqlite3SafetyOff(db);
sl@0:   assert( rc==SQLITE_OK );
sl@0:   rc = xConstruct(db, pMod->pAux, nArg, azArg, &pVtab, &zErr);
sl@0:   rc2 = sqlite3SafetyOn(db);
sl@0:   if( rc==SQLITE_OK && pVtab ){
sl@0:     pVtab->pModule = pMod->pModule;
sl@0:     pVtab->nRef = 1;
sl@0:     pTab->pVtab = pVtab;
sl@0:   }
sl@0: 
sl@0:   if( SQLITE_OK!=rc ){
sl@0:     if( zErr==0 ){
sl@0:       *pzErr = sqlite3MPrintf(db, "vtable constructor failed: %s", zModuleName);
sl@0:     }else {
sl@0:       *pzErr = sqlite3MPrintf(db, "%s", zErr);
sl@0:       sqlite3DbFree(db, zErr);
sl@0:     }
sl@0:   }else if( db->pVTab ){
sl@0:     const char *zFormat = "vtable constructor did not declare schema: %s";
sl@0:     *pzErr = sqlite3MPrintf(db, zFormat, pTab->zName);
sl@0:     rc = SQLITE_ERROR;
sl@0:   } 
sl@0:   if( rc==SQLITE_OK ){
sl@0:     rc = rc2;
sl@0:   }
sl@0:   db->pVTab = 0;
sl@0:   sqlite3DbFree(db, zModuleName);
sl@0: 
sl@0:   /* If everything went according to plan, loop through the columns
sl@0:   ** of the table to see if any of them contain the token "hidden".
sl@0:   ** If so, set the Column.isHidden flag and remove the token from
sl@0:   ** the type string.
sl@0:   */
sl@0:   if( rc==SQLITE_OK ){
sl@0:     int iCol;
sl@0:     for(iCol=0; iCol<pTab->nCol; iCol++){
sl@0:       char *zType = pTab->aCol[iCol].zType;
sl@0:       int nType;
sl@0:       int i = 0;
sl@0:       if( !zType ) continue;
sl@0:       nType = strlen(zType);
sl@0:       if( sqlite3StrNICmp("hidden", zType, 6) || (zType[6] && zType[6]!=' ') ){
sl@0:         for(i=0; i<nType; i++){
sl@0:           if( (0==sqlite3StrNICmp(" hidden", &zType[i], 7))
sl@0:            && (zType[i+7]=='\0' || zType[i+7]==' ')
sl@0:           ){
sl@0:             i++;
sl@0:             break;
sl@0:           }
sl@0:         }
sl@0:       }
sl@0:       if( i<nType ){
sl@0:         int j;
sl@0:         int nDel = 6 + (zType[i+6] ? 1 : 0);
sl@0:         for(j=i; (j+nDel)<=nType; j++){
sl@0:           zType[j] = zType[j+nDel];
sl@0:         }
sl@0:         if( zType[i]=='\0' && i>0 ){
sl@0:           assert(zType[i-1]==' ');
sl@0:           zType[i-1] = '\0';
sl@0:         }
sl@0:         pTab->aCol[iCol].isHidden = 1;
sl@0:       }
sl@0:     }
sl@0:   }
sl@0:   return rc;
sl@0: }
sl@0: 
sl@0: /*
sl@0: ** This function is invoked by the parser to call the xConnect() method
sl@0: ** of the virtual table pTab. If an error occurs, an error code is returned 
sl@0: ** and an error left in pParse.
sl@0: **
sl@0: ** This call is a no-op if table pTab is not a virtual table.
sl@0: */
sl@0: int sqlite3VtabCallConnect(Parse *pParse, Table *pTab){
sl@0:   Module *pMod;
sl@0:   int rc = SQLITE_OK;
sl@0: 
sl@0:   if( !pTab || (pTab->tabFlags & TF_Virtual)==0 || pTab->pVtab ){
sl@0:     return SQLITE_OK;
sl@0:   }
sl@0: 
sl@0:   pMod = pTab->pMod;
sl@0:   if( !pMod ){
sl@0:     const char *zModule = pTab->azModuleArg[0];
sl@0:     sqlite3ErrorMsg(pParse, "no such module: %s", zModule);
sl@0:     rc = SQLITE_ERROR;
sl@0:   } else {
sl@0:     char *zErr = 0;
sl@0:     sqlite3 *db = pParse->db;
sl@0:     rc = vtabCallConstructor(db, pTab, pMod, pMod->pModule->xConnect, &zErr);
sl@0:     if( rc!=SQLITE_OK ){
sl@0:       sqlite3ErrorMsg(pParse, "%s", zErr);
sl@0:     }
sl@0:     sqlite3DbFree(db, zErr);
sl@0:   }
sl@0: 
sl@0:   return rc;
sl@0: }
sl@0: 
sl@0: /*
sl@0: ** Add the virtual table pVtab to the array sqlite3.aVTrans[].
sl@0: */
sl@0: static int addToVTrans(sqlite3 *db, sqlite3_vtab *pVtab){
sl@0:   const int ARRAY_INCR = 5;
sl@0: 
sl@0:   /* Grow the sqlite3.aVTrans array if required */
sl@0:   if( (db->nVTrans%ARRAY_INCR)==0 ){
sl@0:     sqlite3_vtab **aVTrans;
sl@0:     int nBytes = sizeof(sqlite3_vtab *) * (db->nVTrans + ARRAY_INCR);
sl@0:     aVTrans = sqlite3DbRealloc(db, (void *)db->aVTrans, nBytes);
sl@0:     if( !aVTrans ){
sl@0:       return SQLITE_NOMEM;
sl@0:     }
sl@0:     memset(&aVTrans[db->nVTrans], 0, sizeof(sqlite3_vtab *)*ARRAY_INCR);
sl@0:     db->aVTrans = aVTrans;
sl@0:   }
sl@0: 
sl@0:   /* Add pVtab to the end of sqlite3.aVTrans */
sl@0:   db->aVTrans[db->nVTrans++] = pVtab;
sl@0:   sqlite3VtabLock(pVtab);
sl@0:   return SQLITE_OK;
sl@0: }
sl@0: 
sl@0: /*
sl@0: ** This function is invoked by the vdbe to call the xCreate method
sl@0: ** of the virtual table named zTab in database iDb. 
sl@0: **
sl@0: ** If an error occurs, *pzErr is set to point an an English language
sl@0: ** description of the error and an SQLITE_XXX error code is returned.
sl@0: ** In this case the caller must call sqlite3DbFree(db, ) on *pzErr.
sl@0: */
sl@0: int sqlite3VtabCallCreate(sqlite3 *db, int iDb, const char *zTab, char **pzErr){
sl@0:   int rc = SQLITE_OK;
sl@0:   Table *pTab;
sl@0:   Module *pMod;
sl@0:   const char *zModule;
sl@0: 
sl@0:   pTab = sqlite3FindTable(db, zTab, db->aDb[iDb].zName);
sl@0:   assert(pTab && (pTab->tabFlags & TF_Virtual)!=0 && !pTab->pVtab);
sl@0:   pMod = pTab->pMod;
sl@0:   zModule = pTab->azModuleArg[0];
sl@0: 
sl@0:   /* If the module has been registered and includes a Create method, 
sl@0:   ** invoke it now. If the module has not been registered, return an 
sl@0:   ** error. Otherwise, do nothing.
sl@0:   */
sl@0:   if( !pMod ){
sl@0:     *pzErr = sqlite3MPrintf(db, "no such module: %s", zModule);
sl@0:     rc = SQLITE_ERROR;
sl@0:   }else{
sl@0:     rc = vtabCallConstructor(db, pTab, pMod, pMod->pModule->xCreate, pzErr);
sl@0:   }
sl@0: 
sl@0:   if( rc==SQLITE_OK && pTab->pVtab ){
sl@0:       rc = addToVTrans(db, pTab->pVtab);
sl@0:   }
sl@0: 
sl@0:   return rc;
sl@0: }
sl@0: 
sl@0: /*
sl@0: ** This function is used to set the schema of a virtual table.  It is only
sl@0: ** valid to call this function from within the xCreate() or xConnect() of a
sl@0: ** virtual table module.
sl@0: */
sl@0: int sqlite3_declare_vtab(sqlite3 *db, const char *zCreateTable){
sl@0:   Parse sParse;
sl@0: 
sl@0:   int rc = SQLITE_OK;
sl@0:   Table *pTab;
sl@0:   char *zErr = 0;
sl@0: 
sl@0:   sqlite3_mutex_enter(db->mutex);
sl@0:   pTab = db->pVTab;
sl@0:   if( !pTab ){
sl@0:     sqlite3Error(db, SQLITE_MISUSE, 0);
sl@0:     sqlite3_mutex_leave(db->mutex);
sl@0:     return SQLITE_MISUSE;
sl@0:   }
sl@0:   assert((pTab->tabFlags & TF_Virtual)!=0 && pTab->nCol==0 && pTab->aCol==0);
sl@0: 
sl@0:   memset(&sParse, 0, sizeof(Parse));
sl@0:   sParse.declareVtab = 1;
sl@0:   sParse.db = db;
sl@0: 
sl@0:   if( 
sl@0:       SQLITE_OK == sqlite3RunParser(&sParse, zCreateTable, &zErr) && 
sl@0:       sParse.pNewTable && 
sl@0:       !sParse.pNewTable->pSelect && 
sl@0:       (sParse.pNewTable->tabFlags & TF_Virtual)==0
sl@0:   ){
sl@0:     pTab->aCol = sParse.pNewTable->aCol;
sl@0:     pTab->nCol = sParse.pNewTable->nCol;
sl@0:     sParse.pNewTable->nCol = 0;
sl@0:     sParse.pNewTable->aCol = 0;
sl@0:     db->pVTab = 0;
sl@0:   } else {
sl@0:     sqlite3Error(db, SQLITE_ERROR, zErr);
sl@0:     sqlite3DbFree(db, zErr);
sl@0:     rc = SQLITE_ERROR;
sl@0:   }
sl@0:   sParse.declareVtab = 0;
sl@0: 
sl@0:   sqlite3_finalize((sqlite3_stmt*)sParse.pVdbe);
sl@0:   sqlite3DeleteTable(sParse.pNewTable);
sl@0:   sParse.pNewTable = 0;
sl@0: 
sl@0:   assert( (rc&0xff)==rc );
sl@0:   rc = sqlite3ApiExit(db, rc);
sl@0:   sqlite3_mutex_leave(db->mutex);
sl@0:   return rc;
sl@0: }
sl@0: 
sl@0: /*
sl@0: ** This function is invoked by the vdbe to call the xDestroy method
sl@0: ** of the virtual table named zTab in database iDb. This occurs
sl@0: ** when a DROP TABLE is mentioned.
sl@0: **
sl@0: ** This call is a no-op if zTab is not a virtual table.
sl@0: */
sl@0: int sqlite3VtabCallDestroy(sqlite3 *db, int iDb, const char *zTab)
sl@0: {
sl@0:   int rc = SQLITE_OK;
sl@0:   Table *pTab;
sl@0: 
sl@0:   pTab = sqlite3FindTable(db, zTab, db->aDb[iDb].zName);
sl@0:   assert(pTab);
sl@0:   if( pTab->pVtab ){
sl@0:     int (*xDestroy)(sqlite3_vtab *pVTab) = pTab->pMod->pModule->xDestroy;
sl@0:     rc = sqlite3SafetyOff(db);
sl@0:     assert( rc==SQLITE_OK );
sl@0:     if( xDestroy ){
sl@0:       rc = xDestroy(pTab->pVtab);
sl@0:     }
sl@0:     (void)sqlite3SafetyOn(db);
sl@0:     if( rc==SQLITE_OK ){
sl@0:       int i;
sl@0:       for(i=0; i<db->nVTrans; i++){
sl@0:         if( db->aVTrans[i]==pTab->pVtab ){
sl@0:           db->aVTrans[i] = db->aVTrans[--db->nVTrans];
sl@0:           break;
sl@0:         }
sl@0:       }
sl@0:       pTab->pVtab = 0;
sl@0:     }
sl@0:   }
sl@0: 
sl@0:   return rc;
sl@0: }
sl@0: 
sl@0: /*
sl@0: ** This function invokes either the xRollback or xCommit method
sl@0: ** of each of the virtual tables in the sqlite3.aVTrans array. The method
sl@0: ** called is identified by the second argument, "offset", which is
sl@0: ** the offset of the method to call in the sqlite3_module structure.
sl@0: **
sl@0: ** The array is cleared after invoking the callbacks. 
sl@0: */
sl@0: static void callFinaliser(sqlite3 *db, int offset){
sl@0:   int i;
sl@0:   if( db->aVTrans ){
sl@0:     for(i=0; i<db->nVTrans && db->aVTrans[i]; i++){
sl@0:       sqlite3_vtab *pVtab = db->aVTrans[i];
sl@0:       int (*x)(sqlite3_vtab *);
sl@0:       x = *(int (**)(sqlite3_vtab *))((char *)pVtab->pModule + offset);
sl@0:       if( x ) x(pVtab);
sl@0:       sqlite3VtabUnlock(db, pVtab);
sl@0:     }
sl@0:     sqlite3DbFree(db, db->aVTrans);
sl@0:     db->nVTrans = 0;
sl@0:     db->aVTrans = 0;
sl@0:   }
sl@0: }
sl@0: 
sl@0: /*
sl@0: ** Invoke the xSync method of all virtual tables in the sqlite3.aVTrans
sl@0: ** array. Return the error code for the first error that occurs, or
sl@0: ** SQLITE_OK if all xSync operations are successful.
sl@0: **
sl@0: ** Set *pzErrmsg to point to a buffer that should be released using 
sl@0: ** sqlite3DbFree() containing an error message, if one is available.
sl@0: */
sl@0: int sqlite3VtabSync(sqlite3 *db, char **pzErrmsg){
sl@0:   int i;
sl@0:   int rc = SQLITE_OK;
sl@0:   int rcsafety;
sl@0:   sqlite3_vtab **aVTrans = db->aVTrans;
sl@0: 
sl@0:   rc = sqlite3SafetyOff(db);
sl@0:   db->aVTrans = 0;
sl@0:   for(i=0; rc==SQLITE_OK && i<db->nVTrans && aVTrans[i]; i++){
sl@0:     sqlite3_vtab *pVtab = aVTrans[i];
sl@0:     int (*x)(sqlite3_vtab *);
sl@0:     x = pVtab->pModule->xSync;
sl@0:     if( x ){
sl@0:       rc = x(pVtab);
sl@0:       sqlite3DbFree(db, *pzErrmsg);
sl@0:       *pzErrmsg = pVtab->zErrMsg;
sl@0:       pVtab->zErrMsg = 0;
sl@0:     }
sl@0:   }
sl@0:   db->aVTrans = aVTrans;
sl@0:   rcsafety = sqlite3SafetyOn(db);
sl@0: 
sl@0:   if( rc==SQLITE_OK ){
sl@0:     rc = rcsafety;
sl@0:   }
sl@0:   return rc;
sl@0: }
sl@0: 
sl@0: /*
sl@0: ** Invoke the xRollback method of all virtual tables in the 
sl@0: ** sqlite3.aVTrans array. Then clear the array itself.
sl@0: */
sl@0: int sqlite3VtabRollback(sqlite3 *db){
sl@0:   callFinaliser(db, offsetof(sqlite3_module,xRollback));
sl@0:   return SQLITE_OK;
sl@0: }
sl@0: 
sl@0: /*
sl@0: ** Invoke the xCommit method of all virtual tables in the 
sl@0: ** sqlite3.aVTrans array. Then clear the array itself.
sl@0: */
sl@0: int sqlite3VtabCommit(sqlite3 *db){
sl@0:   callFinaliser(db, offsetof(sqlite3_module,xCommit));
sl@0:   return SQLITE_OK;
sl@0: }
sl@0: 
sl@0: /*
sl@0: ** If the virtual table pVtab supports the transaction interface
sl@0: ** (xBegin/xRollback/xCommit and optionally xSync) and a transaction is
sl@0: ** not currently open, invoke the xBegin method now.
sl@0: **
sl@0: ** If the xBegin call is successful, place the sqlite3_vtab pointer
sl@0: ** in the sqlite3.aVTrans array.
sl@0: */
sl@0: int sqlite3VtabBegin(sqlite3 *db, sqlite3_vtab *pVtab){
sl@0:   int rc = SQLITE_OK;
sl@0:   const sqlite3_module *pModule;
sl@0: 
sl@0:   /* Special case: If db->aVTrans is NULL and db->nVTrans is greater
sl@0:   ** than zero, then this function is being called from within a
sl@0:   ** virtual module xSync() callback. It is illegal to write to 
sl@0:   ** virtual module tables in this case, so return SQLITE_LOCKED.
sl@0:   */
sl@0:   if( 0==db->aVTrans && db->nVTrans>0 ){
sl@0:     return SQLITE_LOCKED;
sl@0:   }
sl@0:   if( !pVtab ){
sl@0:     return SQLITE_OK;
sl@0:   } 
sl@0:   pModule = pVtab->pModule;
sl@0: 
sl@0:   if( pModule->xBegin ){
sl@0:     int i;
sl@0: 
sl@0: 
sl@0:     /* If pVtab is already in the aVTrans array, return early */
sl@0:     for(i=0; (i<db->nVTrans) && 0!=db->aVTrans[i]; i++){
sl@0:       if( db->aVTrans[i]==pVtab ){
sl@0:         return SQLITE_OK;
sl@0:       }
sl@0:     }
sl@0: 
sl@0:     /* Invoke the xBegin method */
sl@0:     rc = pModule->xBegin(pVtab);
sl@0:     if( rc==SQLITE_OK ){
sl@0:       rc = addToVTrans(db, pVtab);
sl@0:     }
sl@0:   }
sl@0:   return rc;
sl@0: }
sl@0: 
sl@0: /*
sl@0: ** The first parameter (pDef) is a function implementation.  The
sl@0: ** second parameter (pExpr) is the first argument to this function.
sl@0: ** If pExpr is a column in a virtual table, then let the virtual
sl@0: ** table implementation have an opportunity to overload the function.
sl@0: **
sl@0: ** This routine is used to allow virtual table implementations to
sl@0: ** overload MATCH, LIKE, GLOB, and REGEXP operators.
sl@0: **
sl@0: ** Return either the pDef argument (indicating no change) or a 
sl@0: ** new FuncDef structure that is marked as ephemeral using the
sl@0: ** SQLITE_FUNC_EPHEM flag.
sl@0: */
sl@0: FuncDef *sqlite3VtabOverloadFunction(
sl@0:   sqlite3 *db,    /* Database connection for reporting malloc problems */
sl@0:   FuncDef *pDef,  /* Function to possibly overload */
sl@0:   int nArg,       /* Number of arguments to the function */
sl@0:   Expr *pExpr     /* First argument to the function */
sl@0: ){
sl@0:   Table *pTab;
sl@0:   sqlite3_vtab *pVtab;
sl@0:   sqlite3_module *pMod;
sl@0:   void (*xFunc)(sqlite3_context*,int,sqlite3_value**);
sl@0:   void *pArg;
sl@0:   FuncDef *pNew;
sl@0:   int rc = 0;
sl@0:   char *zLowerName;
sl@0:   unsigned char *z;
sl@0: 
sl@0: 
sl@0:   /* Check to see the left operand is a column in a virtual table */
sl@0:   if( pExpr==0 ) return pDef;
sl@0:   if( pExpr->op!=TK_COLUMN ) return pDef;
sl@0:   pTab = pExpr->pTab;
sl@0:   if( pTab==0 ) return pDef;
sl@0:   if( (pTab->tabFlags & TF_Virtual)==0 ) return pDef;
sl@0:   pVtab = pTab->pVtab;
sl@0:   assert( pVtab!=0 );
sl@0:   assert( pVtab->pModule!=0 );
sl@0:   pMod = (sqlite3_module *)pVtab->pModule;
sl@0:   if( pMod->xFindFunction==0 ) return pDef;
sl@0:  
sl@0:   /* Call the xFindFunction method on the virtual table implementation
sl@0:   ** to see if the implementation wants to overload this function 
sl@0:   */
sl@0:   zLowerName = sqlite3DbStrDup(db, pDef->zName);
sl@0:   if( zLowerName ){
sl@0:     for(z=(unsigned char*)zLowerName; *z; z++){
sl@0:       *z = sqlite3UpperToLower[*z];
sl@0:     }
sl@0:     rc = pMod->xFindFunction(pVtab, nArg, zLowerName, &xFunc, &pArg);
sl@0:     sqlite3DbFree(db, zLowerName);
sl@0:     if( pVtab->zErrMsg ){
sl@0:       sqlite3Error(db, rc, "%s", pVtab->zErrMsg);
sl@0:       sqlite3DbFree(db, pVtab->zErrMsg);
sl@0:       pVtab->zErrMsg = 0;
sl@0:     }
sl@0:   }
sl@0:   if( rc==0 ){
sl@0:     return pDef;
sl@0:   }
sl@0: 
sl@0:   /* Create a new ephemeral function definition for the overloaded
sl@0:   ** function */
sl@0:   pNew = sqlite3DbMallocZero(db, sizeof(*pNew) + strlen(pDef->zName) );
sl@0:   if( pNew==0 ){
sl@0:     return pDef;
sl@0:   }
sl@0:   *pNew = *pDef;
sl@0:   pNew->zName = (char *)&pNew[1];
sl@0:   memcpy(pNew->zName, pDef->zName, strlen(pDef->zName)+1);
sl@0:   pNew->xFunc = xFunc;
sl@0:   pNew->pUserData = pArg;
sl@0:   pNew->flags |= SQLITE_FUNC_EPHEM;
sl@0:   return pNew;
sl@0: }
sl@0: 
sl@0: /*
sl@0: ** Make sure virtual table pTab is contained in the pParse->apVirtualLock[]
sl@0: ** array so that an OP_VBegin will get generated for it.  Add pTab to the
sl@0: ** array if it is missing.  If pTab is already in the array, this routine
sl@0: ** is a no-op.
sl@0: */
sl@0: void sqlite3VtabMakeWritable(Parse *pParse, Table *pTab){
sl@0:   int i, n;
sl@0:   assert( IsVirtual(pTab) );
sl@0:   for(i=0; i<pParse->nVtabLock; i++){
sl@0:     if( pTab==pParse->apVtabLock[i] ) return;
sl@0:   }
sl@0:   n = (pParse->nVtabLock+1)*sizeof(pParse->apVtabLock[0]);
sl@0:   pParse->apVtabLock = sqlite3_realloc(pParse->apVtabLock, n);
sl@0:   if( pParse->apVtabLock ){
sl@0:     pParse->apVtabLock[pParse->nVtabLock++] = pTab;
sl@0:   }else{
sl@0:     pParse->db->mallocFailed = 1;
sl@0:   }
sl@0: }
sl@0: 
sl@0: #endif /* SQLITE_OMIT_VIRTUALTABLE */