Analytics/SQLite/SFSQLite.h

   1 /*
   2  * Copyright (c) 2017 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 // Header exposed for unit testing only
  25
  26 #ifndef SECURITY_SFSQL_H
  27 #define SECURITY_SFSQL_H 1
  28
  29 #if __OBJC2__
  30
  31 #import <Foundation/Foundation.h>
  32 #import <sqlite3.h>
  33
  34 @class SFSQLiteStatement;
  35
  36 typedef SInt64 SFSQLiteRowID;
  37 @class SFSQLite;
  38
  39 NSArray *SFSQLiteJournalSuffixes(void);
  40
  41 typedef NS_ENUM(NSInteger, SFSQLiteSynchronousMode) {
  42     SFSQLiteSynchronousModeOff = 0,
  43     SFSQLiteSynchronousModeNormal = 1, // default
  44     SFSQLiteSynchronousModeFull = 2
  45 };
  46
  47 @protocol SFSQLiteDelegate <NSObject>
  48 @property (nonatomic, readonly) SInt32 userVersion;
  49
  50 - (BOOL)migrateDatabase:(SFSQLite *)db fromVersion:(SInt32)version;
  51 @end
  52
  53 // Wrapper around the SQLite API. Typically subclassed to add table accessor methods.
  54 @interface SFSQLite : NSObject {
  55 @private
  56     id<SFSQLiteDelegate> _delegate;
  57     NSString* _path;
  58     NSString* _schema;
  59     NSString* _schemaVersion;
  60     NSMutableDictionary* _statementsBySQL;
  61     NSString* _objectClassPrefix;
  62     SFSQLiteSynchronousMode _synchronousMode;
  63     SInt32 _userVersion;
  64     sqlite3* _db;
  65     NSUInteger _openCount;
  66     NSDateFormatter* _dateFormatter;
  67 #if DEBUG
  68     NSMutableDictionary* _unitTestOverrides;
  69 #endif
  70     BOOL _hasMigrated;
  71     BOOL _corrupt;
  72     BOOL _traced;
  73 }
  74
  75 - (instancetype)initWithPath:(NSString *)path schema:(NSString *)schema;
  76
  77 @property (nonatomic, readonly, strong) NSString   *path;
  78 @property (nonatomic, readonly, strong) NSString   *schema;
  79 @property (nonatomic, readonly, strong) NSString   *schemaVersion;
  80 @property (nonatomic, strong)           NSString   *objectClassPrefix;
  81 @property (nonatomic, assign)           SInt32     userVersion;
  82 @property (nonatomic, assign)           SFSQLiteSynchronousMode synchronousMode;
  83 @property (nonatomic, readonly)         BOOL       isOpen;
  84 @property (nonatomic, readonly)         BOOL       hasMigrated;
  85 @property (nonatomic, assign)           BOOL       traced;
  86
  87 @property (nonatomic, strong) id<SFSQLiteDelegate> delegate;
  88
  89 #if DEBUG
  90 @property (nonatomic, strong) NSDictionary* unitTestOverrides;
  91 #endif
  92
  93 // Open/close the underlying database file read/write. Initially, the database is closed.
  94 - (void)open;
  95 - (BOOL)openWithError:(NSError **)error;
  96 - (void)close;
  97
  98 // Remove the database file.
  99 - (void)remove;
 100
 101 // Database exclusive transaction operations.
 102 - (void)begin;
 103 - (void)end;
 104 - (void)rollback;
 105
 106 // Database maintenance.
 107 - (void)analyze;
 108 - (void)vacuum;
 109
 110 // The rowID assigned to the last record inserted into the database.
 111 - (SFSQLiteRowID)lastInsertRowID;
 112
 113 // returns the number of rows modified, inserted or deleted by the most recently completed INSERT, UPDATE or DELETE statement on the database connection
 114 - (int)changes;
 115
 116 // Execute one-or-more queries. Use prepared statements for anything performance critical.
 117 - (BOOL)executeSQL:(NSString *)format, ... NS_FORMAT_FUNCTION(1, 2);
 118 - (BOOL)executeSQL:(NSString *)format arguments:(va_list)args NS_FORMAT_FUNCTION(1, 0);
 119
 120 // Prepared statement pool accessors. Statements must be reset after they're used.
 121 - (SFSQLiteStatement *)statementForSQL:(NSString *)SQL;
 122 - (void)removeAllStatements;
 123
 124 // Accessors for all the tables created in the database.
 125 - (NSArray *)allTableNames;
 126 - (void)dropAllTables;
 127
 128 // Generic key/value properties set in the database.
 129 - (NSString *)propertyForKey:(NSString *)key;
 130 - (void)setProperty:(NSString *)value forKey:(NSString *)key;
 131 - (NSDate *)datePropertyForKey:(NSString *)key;
 132 - (void)setDateProperty:(NSDate *)value forKey:(NSString *)key;
 133 - (void)removePropertyForKey:(NSString *)key;
 134
 135 // Date the cache was created.
 136 - (NSDate *)creationDate;
 137
 138 // Convience calls that generate and execute statements.
 139 - (NSArray *)selectAllFrom:(NSString *)tableName where:(NSString *)whereSQL bindings:(NSArray *)bindings;
 140 - (NSArray *)select:(NSArray *)columns from:(NSString *)tableName;
 141 - (NSArray *)select:(NSArray *)columns from:(NSString *)tableName where:(NSString *)whereSQL bindings:(NSArray *)bindings;
 142 - (void)select:(NSArray *)columns from:(NSString *)tableName where:(NSString *)whereSQL bindings:(NSArray *)bindings orderBy:(NSArray *)orderBy limit:(NSNumber *)limit block:(void (^)(NSDictionary *resultDictionary, BOOL *stop))block;
 143 - (void)selectFrom:(NSString *)tableName where:(NSString *)whereSQL bindings:(NSArray *)bindings orderBy:(NSArray *)orderBy limit:(NSNumber *)limit block:(void (^)(NSDictionary *resultDictionary, BOOL *stop))block;
 144 - (NSUInteger)selectCountFrom:(NSString *)tableName  where:(NSString *)whereSQL bindings:(NSArray *)bindings;
 145 - (SFSQLiteRowID)insertOrReplaceInto:(NSString *)tableName values:(NSDictionary *)valuesByColumnName;
 146 - (void)deleteFrom:(NSString *)tableName where:(NSString *)whereSQL bindings:(NSArray *)bindings;
 147 - (void)update:(NSString *)tableName set:(NSString *)setSQL where:(NSString *)whereSQL bindings:(NSArray *)whereBindings limit:(NSNumber *)limit;
 148 - (void)deleteFrom:(NSString *)tableName matchingValues:(NSDictionary *)valuesByColumnName;
 149 - (NSSet<NSString*> *)columnNamesForTable:(NSString*)tableName;
 150
 151 - (SInt32)dbUserVersion;
 152
 153 @end
 154
 155 #endif /* __OBJC2__ */
 156 #endif /* SECURITY_SFSQL_H */