utilities/src/SecDb.h

   1 //
   2 //  SecDb.h
   3 //  utilities
   4 //
   5 //  Created by Michael Brouwer on 11/12/12.
   6 //  Copyright (c) 2012 Apple Inc. All rights reserved.
   7 //
   8
   9 #ifndef _UTILITIES_SECDB_H_
  10 #define _UTILITIES_SECDB_H_
  11
  12 #include <CoreFoundation/CoreFoundation.h>
  13 #include <sqlite3.h>
  14
  15 __BEGIN_DECLS
  16
  17 // MARK: SecDbRef and SecDbConnectionRef forward declarations
  18 typedef struct __OpaqueSecDb *SecDbRef;
  19 typedef struct __OpaqueSecDbConnection *SecDbConnectionRef;
  20 typedef struct __OpaqueSecDbStatement *SecDbStatementRef;
  21
  22 // MARK: Configuration values, not used by clients directly.
  23 // TODO: Move this section to a private header
  24 enum {
  25     kSecDbMaxReaders = 4,
  26     kSecDbMaxWriters = 1,
  27     kSecDbMaxIdleHandles = 3,
  28 };
  29
  30 // MARK: SecDbTransactionType
  31 enum {
  32     kSecDbNoneTransactionType = 0,
  33     kSecDbImmediateTransactionType,
  34     kSecDbExclusiveTransactionType,
  35     kSecDbNormalTransactionType
  36 };
  37 typedef uint32_t SecDbTransactionType;
  38
  39 // MARK: --
  40 // MARK: Error creation helpers.
  41
  42 // SQLITE3 errors are in this domain
  43 extern CFStringRef kSecDbErrorDomain;
  44
  45 bool SecDbError(int sql_code, CFErrorRef *error, CFStringRef format, ...);
  46 bool SecDbErrorWithDb(int sql_code, sqlite3 *db, CFErrorRef *error, CFStringRef format, ...);
  47 bool SecDbErrorWithStmt(int sql_code, sqlite3_stmt *stmt, CFErrorRef *error, CFStringRef format, ...);
  48
  49 // MARK: mark -
  50 // MARK: mark SecDbRef
  51
  52 CFTypeID SecDbGetTypeID(void);
  53
  54 SecDbRef SecDbCreate(CFStringRef dbName, bool (^opened)(SecDbConnectionRef dbconn, bool did_create, CFErrorRef *error));
  55
  56 // Read only connections go to the end of the queue, writeable
  57 // connections go to the start of the queue.  Use SecDbPerformRead() and SecDbPerformWrite() if you
  58 // can to avoid leaks.
  59 SecDbConnectionRef SecDbConnectionAquire(SecDbRef db, bool readOnly, CFErrorRef *error);
  60 void SecDbConnectionRelease(SecDbConnectionRef dbconn);
  61
  62 // Perform a database read operation,
  63 bool SecDbPerformRead(SecDbRef db, CFErrorRef *error, void (^perform)(SecDbConnectionRef dbconn));
  64 bool SecDbPerformWrite(SecDbRef db, CFErrorRef *error, void (^perform)(SecDbConnectionRef dbconn));
  65
  66 // TODO: DEBUG only -> Private header
  67 CFIndex SecDbIdleConnectionCount(SecDbRef db);
  68
  69 // MARK: -
  70 // MARK: SecDbConectionRef
  71
  72 CFTypeID SecDbConnectionGetTypeID(void);
  73
  74 bool SecDbPrepare(SecDbConnectionRef dbconn, CFStringRef sql, CFErrorRef *error, void(^exec)(sqlite3_stmt *stmt));
  75
  76 bool SecDbStep(SecDbConnectionRef dbconn, sqlite3_stmt *stmt, CFErrorRef *error, void (^row)(bool *stop));
  77
  78 bool SecDbExec(SecDbConnectionRef dbconn, CFStringRef sql, CFErrorRef *error);
  79
  80 bool SecDbCheckpoint(SecDbConnectionRef dbconn, CFErrorRef *error);
  81
  82 bool SecDbTransaction(SecDbConnectionRef dbconn, SecDbTransactionType ttype, CFErrorRef *error,
  83                       void (^transaction)(bool *commit));
  84
  85 sqlite3 *SecDbHandle(SecDbConnectionRef dbconn);
  86
  87 // MARK: -
  88 // MARK: Bind helpers
  89
  90 #if 0
  91 bool SecDbBindNull(sqlite3_stmt *stmt, int param, CFErrorRef *error);
  92 #endif
  93 bool SecDbBindBlob(sqlite3_stmt *stmt, int param, const void *zData, size_t n, void(*xDel)(void*), CFErrorRef *error);
  94 bool SecDbBindText(sqlite3_stmt *stmt, int param, const char *zData, size_t n, void(*xDel)(void*), CFErrorRef *error);
  95 bool SecDbBindDouble(sqlite3_stmt *stmt, int param, double value, CFErrorRef *error);
  96 bool SecDbBindInt(sqlite3_stmt *stmt, int param, int value, CFErrorRef *error);
  97 bool SecDbBindInt64(sqlite3_stmt *stmt, int param, sqlite3_int64 value, CFErrorRef *error);
  98 bool SecDbBindObject(sqlite3_stmt *stmt, int param, CFTypeRef value, CFErrorRef *error);
  99
 100 // MARK: -
 101 // MARK: SecDbStatementRef
 102
 103 bool SecDbReset(sqlite3_stmt *stmt, CFErrorRef *error);
 104 bool SecDbClearBindings(sqlite3_stmt *stmt, CFErrorRef *error);
 105 bool SecDbFinalize(sqlite3_stmt *stmt, CFErrorRef *error);
 106 sqlite3_stmt *SecDbPrepareV2(SecDbConnectionRef dbconn, const char *sql, size_t sqlLen, const char **sqlTail, CFErrorRef *error);
 107 sqlite3_stmt *SecDbCopyStmt(SecDbConnectionRef dbconn, CFStringRef sql, CFStringRef *tail, CFErrorRef *error);
 108 bool SecDbReleaseCachedStmt(SecDbConnectionRef dbconn, CFStringRef sql, sqlite3_stmt *stmt, CFErrorRef *error);
 109 bool SecDbWithSQL(SecDbConnectionRef dbconn, CFStringRef sql, CFErrorRef *error, bool(^perform)(sqlite3_stmt *stmt));
 110 bool SecDbForEach(sqlite3_stmt *stmt, CFErrorRef *error, bool(^row)(int row_index));
 111
 112 // Mark the database as corrupted.
 113 void SecDbCorrupt(SecDbConnectionRef dbconn);
 114
 115 __END_DECLS
 116
 117 #endif /* !_UTILITIES_SECDB_H_ */