cdsa/cdsa_utilities/Database.h

   1 /*
   2  * Copyright (c) 2000-2001 Apple Computer, Inc. All Rights Reserved.
   3  *
   4  * The contents of this file constitute Original Code as defined in and are
   5  * subject to the Apple Public Source License Version 1.2 (the 'License').
   6  * You may not use this file except in compliance with the License. Please obtain
   7  * a copy of the License at http://www.apple.com/publicsource and read it before
   8  * using this file.
   9  *
  10  * This Original Code and all software distributed under the License are
  11  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS
  12  * OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, INCLUDING WITHOUT
  13  * LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
  14  * PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. Please see the License for the
  15  * specific language governing rights and limitations under the License.
  16  */
  17
  18
  19 #ifndef _DATABASE_H_
  20 #define _DATABASE_H_  1
  21
  22 #include <Security/cssmacl.h>
  23 #include <Security/threading.h>
  24 #include <Security/DbName.h>
  25 #include <list>
  26 #include <map>
  27 #include <set>
  28
  29 #ifdef _CPP_DATABASE
  30 # pragma export on
  31 #endif
  32
  33 // @@@ Should not use using in headers.
  34 using namespace std;
  35
  36 namespace Security
  37 {
  38
  39 class Database;
  40 class DatabaseFactory;
  41 class DatabaseSession;
  42 class DbContext;
  43
  44 /* DatabaseManager class.  */
  45 class DatabaseManager
  46 {
  47         NOCOPY(DatabaseManager)
  48 public:
  49     DatabaseManager ();
  50     virtual ~DatabaseManager ();
  51
  52     // Create and return a new DbContext instance which is owned by us and must be discared by calling dbClose.
  53     virtual DbContext &dbOpen(DatabaseSession &inDatabaseSession,
  54                               const DbName &inDbName,
  55                               CSSM_DB_ACCESS_TYPE inAccessRequest,
  56                               const AccessCredentials *inAccessCred,
  57                               const void *inOpenParameters);
  58     virtual DbContext &dbCreate(DatabaseSession &inDatabaseSession,
  59                                 const DbName &inDbName,
  60                                 const CSSM_DBINFO &inDBInfo,
  61                                 CSSM_DB_ACCESS_TYPE inAccessRequest,
  62                                 const CSSM_RESOURCE_CONTROL_CONTEXT *inCredAndAclEntry,
  63                                 const void *inOpenParameters);
  64
  65     // Delete a DbContext instance created by calling dbOpen or dbCreate.
  66     virtual void dbClose(DbContext &inDbContext);
  67
  68     // Delete a database.
  69     virtual void dbDelete(DatabaseSession &inDatabaseSession,
  70                           const DbName &inDbName,
  71                           const AccessCredentials *inAccessCred);
  72
  73     // List all available databases.
  74     virtual CSSM_NAME_LIST_PTR getDbNames(DatabaseSession &inDatabaseSession);
  75     virtual void freeNameList(DatabaseSession &inDatabaseSession,
  76                               CSSM_NAME_LIST &inNameList);
  77 protected:
  78     virtual void removeIfUnused(Database &inDatabase);
  79     virtual Database *get (const DbName &inDbName); // Get existing instance or make a new one.
  80     virtual Database *make (const DbName &inDbName) = 0; // Create a new database instance subclass must implement.
  81 private:
  82     typedef map<DbName, Database *> DatabaseMap;
  83     DatabaseMap mDatabaseMap;
  84     Mutex mDatabaseMapLock;
  85 };
  86
  87
  88 /* Database is an abstract class.  Each Database subclass should implement all the
  89    pure virtual methods listed below.  The constructor for a particular Database
  90    subclass should create the Database object.  A subsequent call to dBOpen or
  91    dBCreate should be is made.  This returns a DbContext.  All other methods take
  92    a DbContext as an argument.
  93  */
  94 class Database
  95 {
  96 public:
  97     virtual void
  98     dbCreate (DbContext &inDbContext, const CSSM_DBINFO &inDBInfo,
  99               const CSSM_ACL_ENTRY_INPUT *inInitialAclEntry) = 0;
 100
 101     // Don't override this method in subclasses.
 102     virtual DbContext &
 103     _dbCreate(DatabaseSession &inDatabaseSession,
 104              const CSSM_DBINFO &inDBInfo,
 105              CSSM_DB_ACCESS_TYPE inAccessRequest,
 106              const CSSM_RESOURCE_CONTROL_CONTEXT *inCredAndAclEntry,
 107              const void *inOpenParameters);
 108
 109     virtual void
 110     dbOpen (DbContext &inDbContext) = 0;
 111
 112     // Don't override this method in subclasses.
 113     virtual DbContext &
 114     _dbOpen (DatabaseSession &inDatabaseSession,
 115             CSSM_DB_ACCESS_TYPE inAccessRequest,
 116             const AccessCredentials *inAccessCred,
 117             const void *inOpenParameters);
 118
 119     virtual void
 120     dbClose () = 0;
 121
 122     // Don't override this method in subclasses.
 123     virtual void
 124     _dbClose (DbContext &dbContext);
 125
 126     virtual void
 127     dbDelete(DatabaseSession &inDatabaseSession,
 128              const AccessCredentials *inAccessCred) = 0;
 129
 130     virtual void
 131     createRelation (DbContext &dbContext,
 132                     CSSM_DB_RECORDTYPE inRelationID,
 133                     const char *inRelationName,
 134                     uint32 inNumberOfAttributes,
 135                     const CSSM_DB_SCHEMA_ATTRIBUTE_INFO &inAttributeInfo,
 136                     uint32 inNumberOfIndexes,
 137                     const CSSM_DB_SCHEMA_INDEX_INFO &inIndexInfo) = 0;
 138
 139     virtual void
 140     destroyRelation (DbContext &dbContext,
 141                      CSSM_DB_RECORDTYPE inRelationID) = 0;
 142
 143     virtual void
 144     authenticate(DbContext &dbContext,
 145                  CSSM_DB_ACCESS_TYPE inAccessRequest,
 146                  const AccessCredentials &inAccessCred) = 0;
 147
 148     virtual void
 149     getDbAcl(DbContext &dbContext,
 150              const CSSM_STRING *inSelectionTag,
 151              uint32 &outNumberOfAclInfos,
 152              CSSM_ACL_ENTRY_INFO_PTR &outAclInfos) = 0;
 153
 154     virtual void
 155     changeDbAcl(DbContext &dbContext,
 156                 const AccessCredentials &inAccessCred,
 157                 const CSSM_ACL_EDIT &inAclEdit) = 0;
 158
 159     virtual void
 160     getDbOwner(DbContext &dbContext, CSSM_ACL_OWNER_PROTOTYPE &outOwner) = 0;
 161
 162     virtual void
 163     changeDbOwner(DbContext &dbContext,
 164                   const AccessCredentials &inAccessCred,
 165                   const CSSM_ACL_OWNER_PROTOTYPE &inNewOwner) = 0;
 166
 167     virtual char *
 168     getDbNameFromHandle (const DbContext &dbContext) const = 0;
 169
 170     virtual CSSM_DB_UNIQUE_RECORD_PTR
 171     dataInsert (DbContext &dbContext,
 172                 CSSM_DB_RECORDTYPE RecordType,
 173                 const CSSM_DB_RECORD_ATTRIBUTE_DATA *inAttributes,
 174                 const CssmData *inData) = 0;
 175
 176     virtual void
 177     dataDelete (DbContext &dbContext,
 178                 const CSSM_DB_UNIQUE_RECORD &inUniqueRecordIdentifier) = 0;
 179
 180     virtual void
 181     dataModify (DbContext &dbContext,
 182                 CSSM_DB_RECORDTYPE RecordType,
 183                 CSSM_DB_UNIQUE_RECORD &inoutUniqueRecordIdentifier,
 184                 const CSSM_DB_RECORD_ATTRIBUTE_DATA *inAttributesToBeModified,
 185                 const CssmData *inDataToBeModified,
 186                 CSSM_DB_MODIFY_MODE ModifyMode) = 0;
 187
 188     virtual CSSM_HANDLE
 189     dataGetFirst (DbContext &dbContext,
 190                   const DLQuery *inQuery,
 191                   CSSM_DB_RECORD_ATTRIBUTE_DATA_PTR inoutAttributes,
 192                   CssmData *inoutData,
 193                   CSSM_DB_UNIQUE_RECORD_PTR &outUniqueRecord) = 0;
 194
 195     virtual bool
 196     dataGetNext (DbContext &dbContext,
 197                  CSSM_HANDLE inResultsHandle,
 198                  CSSM_DB_RECORD_ATTRIBUTE_DATA_PTR inoutAttributes,
 199                  CssmData *inoutData,
 200                  CSSM_DB_UNIQUE_RECORD_PTR &outUniqueRecord) = 0;
 201
 202     virtual void
 203     dataAbortQuery (DbContext &dbContext,
 204                     CSSM_HANDLE inResultsHandle) = 0;
 205
 206     virtual void
 207     dataGetFromUniqueRecordId (DbContext &dbContext,
 208                                const CSSM_DB_UNIQUE_RECORD &inUniqueRecord,
 209                                CSSM_DB_RECORD_ATTRIBUTE_DATA_PTR inoutAttributes,
 210                                CssmData *inoutData) = 0;
 211
 212     virtual void
 213     freeUniqueRecord (DbContext &dbContext,
 214                       CSSM_DB_UNIQUE_RECORD &inUniqueRecord) = 0;
 215
 216         virtual void
 217         passThrough(DbContext &dbContext,
 218                                 uint32 passThroughId,
 219                                 const void *inputParams,
 220                                 void **outputParams) = 0;
 221
 222     Database (const DbName &inDbName);
 223     virtual ~Database ();
 224
 225     virtual bool hasDbContexts();
 226
 227     // XXX @@@ Think about consequences of race conditions between DbOpen/DbCreate/DbDelete/DbClose
 228     // on databases with the same name at the same time.
 229     //virtual DbContext &insertDbContext();
 230     //virtual void removeDbContext(DbContext &inDbContext);
 231
 232     const DbName mDbName;
 233 protected:
 234     // Subclasses must implement this method.
 235     virtual DbContext *makeDbContext(DatabaseSession &inDatabaseSession,
 236                                      CSSM_DB_ACCESS_TYPE inAccessRequest,
 237                                      const AccessCredentials *inAccessCred,
 238                                      const void *inOpenParameters) = 0;
 239 private:
 240     typedef set<DbContext *> DbContextSet;
 241     DbContextSet mDbContextSet;
 242     Mutex mDbContextSetLock;
 243 };
 244
 245 } // end namespace Security
 246
 247 #ifdef _CPP_DATABASE
 248 # pragma export off
 249 #endif
 250
 251 #endif //_DATABASE_H_