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 */