1  /*
  2   * Copyright (c) 2012-2016 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: SecDbTransactionType
 40  enum {
 41      kSecDbNoneTransactionType = 0,
 42      kSecDbImmediateTransactionType,
 43      kSecDbExclusiveTransactionType,
 44      kSecDbNormalTransactionType,
 45      kSecDbExclusiveRemoteSOSTransactionType,
 46      kSecDbExclusiveRemoteCKKSTransactionType,
 47  };
 48  typedef CFOptionFlags SecDbTransactionType;
 49  
 50  enum SecDbTransactionPhase {
 51      kSecDbTransactionDidRollback = 0,       // A transaction just got rolled back
 52      kSecDbTransactionWillCommit,        // A transaction is about to commit.
 53      kSecDbTransactionDidCommit,         // A transnaction successfully committed.
 54  };
 55  typedef CFOptionFlags SecDbTransactionPhase;
 56  
 57  enum SecDbTransactionSource {
 58      kSecDbSOSTransaction = 0,        // A remotely initated transaction (via SOS)
 59      kSecDbCKKSTransaction = 3,       // A transaction initiated by CKKS (either via remote notification or queue processing)
 60      kSecDbAPITransaction = 1,        // A user initated transaction.
 61      kSecDbInvalidTransaction = 2,    // An invalid transaction source (used for initialization)
 62  
 63  };
 64  typedef CFOptionFlags SecDbTransactionSource;
 65  
 66  // MARK: --
 67  // MARK: Error creation helpers.
 68  
 69  // SQLITE3 errors are in this domain
 70  extern CFStringRef kSecDbErrorDomain;
 71  
 72  typedef CFTypeRef SecDbEntryRef;
 73  
 74  bool SecDbError(int sql_code, CFErrorRef *error, CFStringRef format, ...) CF_FORMAT_FUNCTION(3, 4);
 75  bool SecDbErrorWithDb(int sql_code, sqlite3 *db, CFErrorRef *error, CFStringRef format, ...) CF_FORMAT_FUNCTION(4, 5);
 76  bool SecDbErrorWithStmt(int sql_code, sqlite3_stmt *stmt, CFErrorRef *error, CFStringRef format, ...) CF_FORMAT_FUNCTION(4, 5);
 77  
 78  // MARK: mark -
 79  // MARK: mark SecDbRef
 80  
 81  void _SecDbServerSetup(void);
 82  
 83  typedef CFTypeRef SecDbEventRef;
 84  
 85  SecDbEventRef SecDbEventCreateWithComponents(CFTypeRef deleted, CFTypeRef inserted);
 86  void SecDbEventTranslateComponents(SecDbEventRef item, CFTypeRef* deleted, CFTypeRef* inserted);
 87  
 88  // Return deleted and inserted for a given changes entry, both are optional
 89  bool SecDbEventGetComponents(SecDbEventRef event, CFTypeRef *deleted, CFTypeRef *inserted, CFErrorRef *error);
 90  
 91  // changes is an array of SecDbEventRef
 92  typedef void (^SecDBNotifyBlock)(SecDbConnectionRef dbconn, SecDbTransactionPhase phase, SecDbTransactionSource source, CFArrayRef changes);
 93  
 94  CFTypeID SecDbGetTypeID(void);
 95  
 96  // Database creation
 97  SecDbRef
 98  SecDbCreate(CFStringRef dbName, mode_t mode,
 99              bool readWrite, bool allowRepair, bool useWAL, bool useRobotVacuum, uint8_t maxIdleHandles,
100              bool (^opened)(SecDbRef db, SecDbConnectionRef dbconn, bool didCreate, bool *callMeAgainForNextConnection, CFErrorRef *error));
101  
102  void SecDbAddNotifyPhaseBlock(SecDbRef db, SecDBNotifyBlock notifyPhase);
103  void SecDbSetCorruptionReset(SecDbRef db, void (^corruptionReset)(void));
104  
105  // Read only connections go to the end of the queue, writeable
106  // connections go to the start of the queue.  Use SecDbPerformRead() and SecDbPerformWrite() if you
107  // can to avoid leaks.
108  SecDbConnectionRef SecDbConnectionAcquire(SecDbRef db, bool readOnly, CFErrorRef *error);
109  bool SecDbConnectionAcquireRefMigrationSafe(SecDbRef db, bool readOnly, SecDbConnectionRef* dbconnRef, CFErrorRef *error);
110  void SecDbConnectionRelease(SecDbConnectionRef dbconn);
111  
112  // Perform a database read operation,
113  bool SecDbPerformRead(SecDbRef db, CFErrorRef *error, void (^perform)(SecDbConnectionRef dbconn));
114  bool SecDbPerformWrite(SecDbRef db, CFErrorRef *error, void (^perform)(SecDbConnectionRef dbconn));
115  
116  // TODO: DEBUG only -> Private header
117  CFIndex SecDbIdleConnectionCount(SecDbRef db);
118  void SecDbReleaseAllConnections(SecDbRef db);
119  
120  void SecDbForceClose(SecDbRef db);
121  
122  CFStringRef SecDbGetPath(SecDbRef db);
123  
124  // MARK: -
125  // MARK: SecDbConectionRef
126  
127  CFTypeID SecDbConnectionGetTypeID(void);
128  
129  bool SecDbPrepare(SecDbConnectionRef dbconn, CFStringRef sql, CFErrorRef *error, void(^exec)(sqlite3_stmt *stmt));
130  
131  bool SecDbStep(SecDbConnectionRef dbconn, sqlite3_stmt *stmt, CFErrorRef *error, void (^row)(bool *stop));
132  
133  bool SecDbExec(SecDbConnectionRef dbconn, CFStringRef sql, CFErrorRef *error);
134  
135  bool SecDbCheckpoint(SecDbConnectionRef dbconn, CFErrorRef *error);
136  
137  bool SecDbTransaction(SecDbConnectionRef dbconn, SecDbTransactionType ttype, CFErrorRef *error,
138                        void (^transaction)(bool *commit));
139  
140  sqlite3 *SecDbHandle(SecDbConnectionRef dbconn);
141  
142  bool SecDbConnectionIsReadOnly(SecDbConnectionRef dbconn);
143  
144  // Do not call this unless you are SecDbItem!
145  void SecDbRecordChange(SecDbConnectionRef dbconn, CFTypeRef deleted, CFTypeRef inserted);
146  
147  void SecDbPerformOnCommitQueue(SecDbConnectionRef dbconn, bool barrier, dispatch_block_t perform);
148  void SecDBManagementTasks(SecDbConnectionRef dbconn);
149  
150  // MARK: -
151  // MARK: Bind helpers
152  
153  bool SecDbBindBlob(sqlite3_stmt *stmt, int param, const void *zData, size_t n, void(*xDel)(void*), CFErrorRef *error);
154  bool SecDbBindText(sqlite3_stmt *stmt, int param, const char *zData, size_t n, void(*xDel)(void*), CFErrorRef *error);
155  bool SecDbBindDouble(sqlite3_stmt *stmt, int param, double value, CFErrorRef *error);
156  bool SecDbBindInt(sqlite3_stmt *stmt, int param, int value, CFErrorRef *error);
157  bool SecDbBindInt64(sqlite3_stmt *stmt, int param, sqlite3_int64 value, CFErrorRef *error);
158  bool SecDbBindObject(sqlite3_stmt *stmt, int param, CFTypeRef value, CFErrorRef *error);
159  
160  // MARK: -
161  // MARK: SecDbStatementRef
162  
163  bool SecDbReset(sqlite3_stmt *stmt, CFErrorRef *error);
164  bool SecDbClearBindings(sqlite3_stmt *stmt, CFErrorRef *error);
165  bool SecDbFinalize(sqlite3_stmt *stmt, CFErrorRef *error);
166  sqlite3_stmt *SecDbPrepareV2(SecDbConnectionRef dbconn, const char *sql, size_t sqlLen, const char **sqlTail, CFErrorRef *error);
167  sqlite3_stmt *SecDbCopyStmt(SecDbConnectionRef dbconn, CFStringRef sql, CFStringRef *tail, CFErrorRef *error);
168  bool SecDbReleaseCachedStmt(SecDbConnectionRef dbconn, CFStringRef sql, sqlite3_stmt *stmt, CFErrorRef *error);
169  bool SecDbWithSQL(SecDbConnectionRef dbconn, CFStringRef sql, CFErrorRef *error, bool(^perform)(sqlite3_stmt *stmt));
170  bool SecDbForEach(SecDbConnectionRef dbconn, sqlite3_stmt *stmt, CFErrorRef *error, bool(^row)(int row_index));
171  
172  // Mark the database as corrupted.
173  void SecDbCorrupt(SecDbConnectionRef dbconn, CFErrorRef error);
174  
175  // Testing only. Normally this calls exit() so make it do something more test-friendly instead
176  extern void (*SecDbCorruptionExitHandler)(void);
177  void SecDbResetCorruptionExitHandler(void);
178  __END_DECLS
179  
180  #endif /* !_UTILITIES_SECDB_H_ */