Security/utilities/src/SecDb.h

   1 /*
   2  * Copyright (c) 2012-2014 Apple Inc. All Rights Reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  */
  23
  24
  25 #ifndef _UTILITIES_SECDB_H_
  26 #define _UTILITIES_SECDB_H_
  27
  28 #include <CoreFoundation/CoreFoundation.h>
  29 #include <sqlite3.h>
  30
  31 __BEGIN_DECLS
  32
  33 // MARK: SecDbRef and SecDbConnectionRef forward declarations
  34 typedef struct __OpaqueSecDb *SecDbRef;
  35 typedef struct __OpaqueSecDbConnection *SecDbConnectionRef;
  36 typedef struct __OpaqueSecDbStatement *SecDbStatementRef;
  37 struct SOSDigestVector;
  38
  39 // MARK: Configuration values, not used by clients directly.
  40 // TODO: Move this section to a private header
  41 enum {
  42     kSecDbMaxReaders = 4,
  43     kSecDbMaxWriters = 1,
  44     kSecDbMaxIdleHandles = 3,
  45 };
  46
  47 // MARK: SecDbTransactionType
  48 enum {
  49     kSecDbNoneTransactionType = 0,
  50     kSecDbImmediateTransactionType,
  51     kSecDbExclusiveTransactionType,
  52     kSecDbNormalTransactionType,
  53     kSecDbExclusiveRemoteTransactionType,
  54 };
  55 typedef CFOptionFlags SecDbTransactionType;
  56
  57 enum SecDbTransactionPhase {
  58     kSecDbTransactionDidRollback = 0,       // A transaction just got rolled back
  59     kSecDbTransactionWillCommit,        // A transaction is about to commit.
  60     kSecDbTransactionDidCommit,         // A transnaction sucessfully committed.
  61 };
  62 typedef CFOptionFlags SecDbTransactionPhase;
  63
  64 enum SecDbTransactionSource {
  65     kSecDbSOSTransaction,        // A remotely initated transaction.
  66     kSecDbAPITransaction,        // A user initated transaction.
  67 };
  68 typedef CFOptionFlags SecDbTransactionSource;
  69
  70 // MARK: --
  71 // MARK: Error creation helpers.
  72
  73 // SQLITE3 errors are in this domain
  74 extern CFStringRef kSecDbErrorDomain;
  75
  76 bool SecDbError(int sql_code, CFErrorRef *error, CFStringRef format, ...);
  77 bool SecDbErrorWithDb(int sql_code, sqlite3 *db, CFErrorRef *error, CFStringRef format, ...);
  78 bool SecDbErrorWithStmt(int sql_code, sqlite3_stmt *stmt, CFErrorRef *error, CFStringRef format, ...);
  79
  80 // MARK: mark -
  81 // MARK: mark SecDbRef
  82
  83 typedef void (^SecDBNotifyBlock)(SecDbConnectionRef dbconn, SecDbTransactionPhase phase, SecDbTransactionSource source, struct SOSDigestVector *removals, struct SOSDigestVector *additions);
  84
  85 CFTypeID SecDbGetTypeID(void);
  86
  87 SecDbRef SecDbCreate(CFStringRef dbName, bool (^opened)(SecDbConnectionRef dbconn, bool did_create, CFErrorRef *error));
  88
  89 void SecDbSetNotifyPhaseBlock(SecDbRef db, SecDBNotifyBlock notifyPhase);
  90
  91 // Read only connections go to the end of the queue, writeable
  92 // connections go to the start of the queue.  Use SecDbPerformRead() and SecDbPerformWrite() if you
  93 // can to avoid leaks.
  94 SecDbConnectionRef SecDbConnectionAquire(SecDbRef db, bool readOnly, CFErrorRef *error);
  95 void SecDbConnectionRelease(SecDbConnectionRef dbconn);
  96
  97 // Perform a database read operation,
  98 bool SecDbPerformRead(SecDbRef db, CFErrorRef *error, void (^perform)(SecDbConnectionRef dbconn));
  99 bool SecDbPerformWrite(SecDbRef db, CFErrorRef *error, void (^perform)(SecDbConnectionRef dbconn));
 100
 101 // TODO: DEBUG only -> Private header
 102 CFIndex SecDbIdleConnectionCount(SecDbRef db);
 103
 104 CFStringRef SecDbGetPath(SecDbRef db);
 105
 106 // MARK: -
 107 // MARK: SecDbConectionRef
 108
 109 CFTypeID SecDbConnectionGetTypeID(void);
 110
 111 bool SecDbPrepare(SecDbConnectionRef dbconn, CFStringRef sql, CFErrorRef *error, void(^exec)(sqlite3_stmt *stmt));
 112
 113 bool SecDbStep(SecDbConnectionRef dbconn, sqlite3_stmt *stmt, CFErrorRef *error, void (^row)(bool *stop));
 114
 115 bool SecDbExec(SecDbConnectionRef dbconn, CFStringRef sql, CFErrorRef *error);
 116
 117 bool SecDbCheckpoint(SecDbConnectionRef dbconn, CFErrorRef *error);
 118
 119 bool SecDbTransaction(SecDbConnectionRef dbconn, SecDbTransactionType ttype, CFErrorRef *error,
 120                       void (^transaction)(bool *commit));
 121
 122 sqlite3 *SecDbHandle(SecDbConnectionRef dbconn);
 123
 124 // Do not call this unless you are SecDbItem!
 125 void SecDbRecordChange(SecDbConnectionRef dbconn, CFDataRef deleted, CFDataRef inserted);
 126
 127 // MARK: -
 128 // MARK: Bind helpers
 129
 130 #if 0
 131 bool SecDbBindNull(sqlite3_stmt *stmt, int param, CFErrorRef *error);
 132 #endif
 133 bool SecDbBindBlob(sqlite3_stmt *stmt, int param, const void *zData, size_t n, void(*xDel)(void*), CFErrorRef *error);
 134 bool SecDbBindText(sqlite3_stmt *stmt, int param, const char *zData, size_t n, void(*xDel)(void*), CFErrorRef *error);
 135 bool SecDbBindDouble(sqlite3_stmt *stmt, int param, double value, CFErrorRef *error);
 136 bool SecDbBindInt(sqlite3_stmt *stmt, int param, int value, CFErrorRef *error);
 137 bool SecDbBindInt64(sqlite3_stmt *stmt, int param, sqlite3_int64 value, CFErrorRef *error);
 138 bool SecDbBindObject(sqlite3_stmt *stmt, int param, CFTypeRef value, CFErrorRef *error);
 139
 140 // MARK: -
 141 // MARK: SecDbStatementRef
 142
 143 bool SecDbReset(sqlite3_stmt *stmt, CFErrorRef *error);
 144 bool SecDbClearBindings(sqlite3_stmt *stmt, CFErrorRef *error);
 145 bool SecDbFinalize(sqlite3_stmt *stmt, CFErrorRef *error);
 146 sqlite3_stmt *SecDbPrepareV2(SecDbConnectionRef dbconn, const char *sql, size_t sqlLen, const char **sqlTail, CFErrorRef *error);
 147 sqlite3_stmt *SecDbCopyStmt(SecDbConnectionRef dbconn, CFStringRef sql, CFStringRef *tail, CFErrorRef *error);
 148 bool SecDbReleaseCachedStmt(SecDbConnectionRef dbconn, CFStringRef sql, sqlite3_stmt *stmt, CFErrorRef *error);
 149 bool SecDbWithSQL(SecDbConnectionRef dbconn, CFStringRef sql, CFErrorRef *error, bool(^perform)(sqlite3_stmt *stmt));
 150 bool SecDbForEach(sqlite3_stmt *stmt, CFErrorRef *error, bool(^row)(int row_index));
 151
 152 // Mark the database as corrupted.
 153 void SecDbCorrupt(SecDbConnectionRef dbconn);
 154
 155 __END_DECLS
 156
 157 #endif /* !_UTILITIES_SECDB_H_ */