SFSmartStore Class Reference

Inherits from	NSObject
Declared in	SFSmartStore.h

Overview

The columns of a soup table

Other Methods

`)`

The name of this store.

@property (nonatomic, readonly, strong) NSString *NS_SWIFT_NAME ( name )

Declared In

SFSmartStore.h

`lastExplainQueryPlan`

Dictionary with results of last explain query plan

@property (nonatomic, strong) NSDictionary *lastExplainQueryPlan

Declared In

SFSmartStore.h

`allStoreNames`

All of the store names for the current user from this app.

@property (nonatomic, class, readonly) NSArray<NSString*> *allStoreNames

Declared In

SFSmartStore.h

`allGlobalStoreNames`

All of the the global store names from this app.

@property (nonatomic, class, readonly) NSArray<NSString*> *allGlobalStoreNames

Declared In

SFSmartStore.h

`encryptionKeyGenerator`

Block used to generate the encryption key. Salesforce recommends using the default encryption key derivation.

@property (nonatomic, class, readonly) SFSmartStoreEncryptionKeyGenerator encryptionKeyGenerator

Declared In

SFSmartStore.h

`encryptionSaltBlock`

Block used to generate the salt. The salt is maintained in the keychain. Used only when database needs to be shared between apps.

@property (nonatomic, class, readonly) SFSmartStoreEncryptionSaltBlock encryptionSaltBlock

Declared In

SFSmartStore.h

`+ sharedStoreWithName:`

Use this method to obtain a shared store instance with a particular name for the current user.

+ (nullable instancetype)sharedStoreWithName:(NSString *)storeName

Parameters

`storeName`	The name of the store. If in doubt, use kDefaultSmartStoreName.

Return Value

A shared instance of a store with the given name.

Declared In

SFSmartStore.h

`+ sharedGlobalStoreWithName:`

Use this method to obtain a shared global store instance with the given name. This store will not be specific to a particular user.

+ (instancetype)sharedGlobalStoreWithName:(NSString *)storeName

Parameters

`storeName`	The name of the global store to retrieve.

Declared In

SFSmartStore.h

`+ removeSharedStoreWithName:`

You may use this method to completely remove a persistent shared store with the given name for the current user.

+ (void)removeSharedStoreWithName:(NSString *)storeName

Parameters

`storeName`	The name of the store.

Declared In

SFSmartStore.h

`+ removeSharedStoreWithName:forUser:`

You may use this method to completely remove a persisted shared store with the given name for the given user.

+ (void)removeSharedStoreWithName:(NSString *)storeName forUser:(SFUserAccount *)user

Parameters

`storeName`	The name of the store to remove.
`user`	The User Account associated with the store.

Declared In

SFSmartStore.h

`+ removeSharedGlobalStoreWithName:`

You may use this method to completely remove a persisted global store with the given name.

+ (void)removeSharedGlobalStoreWithName:(NSString *)storeName

Parameters

`storeName`	The name of the global store to remove.

Declared In

SFSmartStore.h

`+ removeAllStores`

Removes all of the stores for the current user from this app.

+ (void)removeAllStores

Declared In

SFSmartStore.h

`user`	The user associated with the stores to remove.

`+ removeAllGlobalStores`

Removes all of the global stores from this app.

+ (void)removeAllGlobalStores

Declared In

SFSmartStore.h

`+ setEncryptionKeyGenerator:`

Sets a custom block for deriving the encryption key used to encrypt stores.

+ (void)setEncryptionKeyGenerator:(SFSmartStoreEncryptionKeyGenerator)newEncryptionKeyGenerator

Parameters

`newEncryptionKeyGenerator`	The new encryption key derivation block to use with SmartStore.

Discussion

WARNING: If you choose to override the encryption key derivation, you must set this value before opening any stores. Setting the value after stores have been opened will result in the corruption and loss of existing data. Also, SmartStore does not use initialization vectors. WARNING

Declared In

SFSmartStore.h

`– indicesForSoup:`

Name of the soup.

- (NSArray<SFSoupIndex*> *)indicesForSoup:(NSString *)soupName

Parameters

`soupName`	Name of the soup.

Return Value

NSArray of SFSoupIndex for the given soup.

Declared In

SFSmartStore.h

`– soupExists:`

Name of the soup.

- (BOOL)soupExists:(NSString *)soupName

Parameters

`soupName`	Name of the soup.

Return Value

YES if a soup with the given name already exists.

Declared In

SFSmartStore.h

`– registerSoup:withIndexSpecs:error:`

Creates a new soup or confirms the existence of an existing soup.

- (BOOL)registerSoup:(NSString *)soupName withIndexSpecs:(NSArray<SFSoupIndex*> *)indexSpecs error:(NSError **)error

Parameters

`soupName`	Name of the soup to register.
`indexSpecs`	Array of one or more SFSoupIndex objects.
`error`	Sets/returns any error generated as part of the process.

Return Value

YES if the soup is registered or already exists.

Declared In

SFSmartStore.h

`– countWithQuerySpec:error:`

Get the number of entries that would be returned with the given query spec

- (NSNumber *__nullable)countWithQuerySpec:(SFQuerySpec *)querySpec error:(NSError **)error

Parameters

`querySpec`	A native query spec.
`error`	Sets/returns any error generated as part of the process.

Declared In

SFSmartStore.h

`– queryWithQuerySpec:pageIndex:error:`

Search for entries matching the given query spec.

- (NSArray *__nullable)queryWithQuerySpec:(SFQuerySpec *)querySpec pageIndex:(NSUInteger)pageIndex error:(NSError **)error

Parameters

`querySpec`	A native query spec.
`pageIndex`	The page index to start the entries at (this supports paging).
`error`	Sets/returns any error generated as part of the process.

Return Value

A set of entries given the pageSize provided in the querySpec.

Declared In

SFSmartStore.h

`– queryWithQuerySpec:pageIndex:whereArgs:error:`

Search for entries matching the given query spec with optional “where args” (i.e. bind args) Provided bind args will be substituted to the ? found in the query NB: Bind args are only supported for smart queries

- (NSArray *__nullable)queryWithQuerySpec:(SFQuerySpec *)querySpec pageIndex:(NSUInteger)pageIndex whereArgs:(NSArray *__nullable)whereArgs error:(NSError **)error

Parameters

`querySpec`	A native query spec.
`pageIndex`	The page index to start the entries at (this supports paging).
`whereArgs`	The bind args (optional - only supported for smart queries).
`error`	Sets/returns any error generated as part of the process.

Return Value

A set of entries given the pageSize provided in the querySpec.

Declared In

SFSmartStore.h

`– queryAsString:querySpec:pageIndex:error:`

Search for entries matching the given query spec without deserializing any JSON

- (BOOL)queryAsString:(NSMutableString *)resultString querySpec:(SFQuerySpec *)querySpec pageIndex:(NSUInteger)pageIndex error:(NSError **)error

Parameters

`resultString`	A mutable string to which the result (serialized) is appended
`querySpec`	A native query spec.
`pageIndex`	The page index to start the entries at (this supports paging).
`error`	Sets/returns any error generated as part of the process.

Return Value

YES if successful

Declared In

SFSmartStore.h

`jsonSerializationCheckEnabled`

Experimental flag to do additional checks when reading back soup entries that use external storage It could be dropped in a future release. Use only if you know what you are doing.

@property (class, nonatomic, assign, getter=isJsonSerializationCheckEnabled) BOOL jsonSerializationCheckEnabled

Declared In

SFSmartStore.h

`– retrieveEntries:fromSoup:`

Search soup for entries exactly matching the soup entry IDs.

- (NSArray<NSDictionary*> *)retrieveEntries:(NSArray<NSNumber*> *)soupEntryIds fromSoup:(NSString *)soupName

Parameters

`soupEntryIds`	An array of opaque soup entry IDs.
`soupName`	The name of the soup to query.

Return Value

An array with zero or more entries matching the input IDs. Order is not guaranteed.

Declared In

SFSmartStore.h

`– upsertEntries:toSoup:`

Insert/update entries to the soup. Insert vs. update will be determined by the internal soup entry ID generated from intial entry. If you want to specify a different identifier for determining existing entries, use upsertEntries:toSoup:withExternalIdPath:

- (NSArray<NSDictionary*> *)upsertEntries:(NSArray<NSDictionary*> *)entries toSoup:(NSString *)soupName

Parameters

`entries`	The entries to insert or update.
`soupName`	The name of the soup to update.

Return Value

The array of updated entries in the soup.

Declared In

SFSmartStore.h

`– upsertEntries:toSoup:withExternalIdPath:error:`

Insert/update entries to the soup. Insert vs. update will be determined by the specified external ID path argument.

- (NSArray *_Nullable)upsertEntries:(NSArray *)entries toSoup:(NSString *)soupName withExternalIdPath:(NSString *)externalIdPath error:(NSError **)error

Parameters

`entries`	The entries to insert or update.
`soupName`	The name of the soup to update.
`externalIdPath`	The user-defined query spec path used to determine insert vs. update.
`error`	Sets/returns any error generated as part of the process.

Return Value

The array of updated entries in the soup.

Declared In

SFSmartStore.h

`– lookupSoupEntryIdForSoupName:forFieldPath:fieldValue:error:`

Look up the ID for an entry in a soup.

- (NSNumber *__nullable)lookupSoupEntryIdForSoupName:(NSString *)soupName forFieldPath:(NSString *)fieldPath fieldValue:(NSString *)fieldValue error:(NSError **)error

Parameters

`soupName`	Soup name.
`fieldPath`	Field path.
`fieldValue`	Field value.
`error`	Sets/returns any error generated as part of the process.

Return Value

The ID of the specified soup entry.

Declared In

SFSmartStore.h

`– removeEntries:fromSoup:error:`

Remove soup entries exactly matching the soup entry IDs.

- (BOOL)removeEntries:(NSArray<NSNumber*> *)entryIds fromSoup:(NSString *)soupName error:(NSError **)error

Parameters

`entryIds`	An array of opaque soup entry IDs from _soupEntryId.
`soupName`	The name of the soup from which to remove the soup entries.
`error`	Sets/returns any error generated as part of the process.

Return Value

YES if no error occurs

Declared In

SFSmartStore.h

`– removeEntries:fromSoup:`

Remove soup entries exactly matching the soup entry IDs.

- (void)removeEntries:(NSArray<NSNumber*> *)entryIds fromSoup:(NSString *)soupName

Parameters

`entryIds`	An array of opaque soup entry IDs from _soupEntryId.
`soupName`	The name of the soup from which to remove the soup entries.

Declared In

SFSmartStore.h

`– removeEntriesByQuery:fromSoup:error:`

Remove soup entries returned by the given query spec. NB: A single SQL call is executed to improve performance.

- (BOOL)removeEntriesByQuery:(SFQuerySpec *)querySpec fromSoup:(NSString *)soupName error:(NSError **)error

Parameters

`querySpec`	Query returning entries to delete (if querySpec uses smartSQL, it must select soup entry ids).
`soupName`	The name of the soup from which to remove the soup entries.
`error`	Sets/returns any error generated as part of the process.

Return Value

YES if no error occurs

Declared In

SFSmartStore.h

`– removeEntriesByQuery:fromSoup:`

Remove soup entries returned by the given query spec. NB: A single SQL call is executed to improve performance.

- (void)removeEntriesByQuery:(SFQuerySpec *)querySpec fromSoup:(NSString *)soupName

Parameters

`querySpec`	Query returning entries to delete (if querySpec uses smartSQL, it must select soup entry ids).
`soupName`	The name of the soup from which to remove the soup entries.

Declared In

SFSmartStore.h

`– clearSoup:`

Remove all elements from soup.

- (void)clearSoup:(NSString *)soupName

Parameters

`soupName`	The name of the soup to clear.

Declared In

SFSmartStore.h

`– removeSoup:`

Remove soup completely from the store.

- (void)removeSoup:(NSString *)soupName

Parameters

`soupName`	The name of the soup to remove from the store.

Declared In

SFSmartStore.h

`– removeAllSoups`

Remove all soups from the store.

- (void)removeAllSoups

Declared In

SFSmartStore.h

`– getDatabaseSize`

Return database file size.

- (unsigned long long)getDatabaseSize

Return Value

Database size, in bytes.

Declared In

SFSmartStore.h

`– alterSoup:withIndexSpecs:reIndexData:`

Alter soup indexes.

- (BOOL)alterSoup:(NSString *)soupName withIndexSpecs:(NSArray<SFSoupIndex*> *)indexSpecs reIndexData:(BOOL)reIndexData

Parameters

`soupName`	The name of the soup to alter.
`indexSpecs`	Array of one ore more SFSoupIndex objects to replace existing index specs.
`reIndexData`	pass true if you want existing records to be re-indexed for new index specs.

Return Value

YES if the soup was altered successfully.

Declared In

SFSmartStore.h

`– reIndexSoup:withIndexPaths:`

Reindex a soup.

- (BOOL)reIndexSoup:(NSString *)soupName withIndexPaths:(NSArray<NSString*> *)indexPaths

Parameters

`soupName`	The name of the soup to alter.
`indexPaths`	Array of on ore more paths to be reindexed.

Return Value

YES if soup reindexing succeeded.

Declared In

SFSmartStore.h

`– getRuntimeSettings`

Return SQLCipher runtime settings

- (NSArray *)getRuntimeSettings

Return Value

An array with all the compile options used to build SQL Cipher.

Declared In

SFSmartStore.h

`– getCompileOptions`

Return SQLCipher compile options

- (NSArray *)getCompileOptions

Return Value

An array with all the compile options used to build SQL Cipher.

Declared In

SFSmartStore.h

`– getSQLCipherVersion`

Return SQLCipher version

- (NSString *)getSQLCipherVersion

Return Value

The version of SQL Cipher in use.

Declared In

SFSmartStore.h

`– resumeLongOperations`

Complete long operations that were interrupted.

- (void)resumeLongOperations

Declared In

SFSmartStore.h

`– isFileDataProtectionActive`

This property is updated when notifications are received for UIApplicationProtectedDataDidBecomeAvailable and UIApplicationProtectedDataWillBecomeUnavailable events. Note that on the simulator currently, data protection is NEVER active.

- (BOOL)isFileDataProtectionActive

Return Value

YES if file data protection (full passcode-based encryption) is available.

Declared In

SFSmartStore.h

`– allSoupNames`

Return all soup names.

- (NSArray<NSString*> *)allSoupNames

Return Value

Array containing all soup names.

Declared In

SFSmartStore.h

`+ dateFromLastModifiedValue:`

Creates a date object from the last modified date column value, which is numeric.

+ (NSDate *)dateFromLastModifiedValue:(NSNumber *)lastModifiedValue

Parameters

`lastModifiedValue`	The numeric value of the date stored in the soup entry.

Return Value

The NSDate representation of the last modified date.

Declared In

SFSmartStore.h

Extension Methods

`storeQueue`

@property (nonatomic, strong) FMDatabaseQueue *storeQueue

`dbMgr`

@property (nonatomic, strong) SFSmartStoreDatabaseManager *dbMgr

`isGlobal`

@property (nonatomic, assign) BOOL isGlobal

`ftsExtension`

@property (nonatomic, assign) SFSmartStoreFtsExtension ftsExtension

`– openStoreDatabase`

Simply open the db file.

- (BOOL)openStoreDatabase

Return Value

YES if we were able to open the DB file.

Declared In

SFSmartStore+Internal.h

`– createMetaTables`

Create soup index map table to keep track of soups' index specs (SOUP_INDEX_MAP_TABLE) Create soup attributes table to keep track of soups' attributes specs (e.g. external blobs storage) and maps arbitrary soup names to soup table names (SOUP_ATTRS_TABLE)

- (BOOL)createMetaTables

Return Value

YES if we were able to create the meta tables, NO otherwise.

Declared In

SFSmartStore+Internal.h

`– createLongOperationsStatusTable`

Create long operations status table (LONG_OPERATIONS_STATUS_TABLE)

- (BOOL)createLongOperationsStatusTable

Return Value

YES if we were able to create the table, NO otherwise.

Declared In

SFSmartStore+Internal.h

`– registerSoupWithName:withIndexSpecs:withSoupTableName:withDb:`

- (void)registerSoupWithName:(NSString *)soupName withIndexSpecs:(NSArray *)indexSpecs withSoupTableName:(NSString *)soupTableName withDb:(FMDatabase *)db

Parameters

`soupName`	The name of the soup to register
`indexSpecs`	Array of one ore more IndexSpec objects as dictionaries
`soupTableName`	The name of the table to use for the soup
`db`	This method is expected to be called from [fmdbqueue inDatabase:^(){ … }]

Declared In

SFSmartStore+Internal.h

`– tableNameForSoup:withDb:`

This method is expected to be called from [fmdbqueue inDatabase:^(){ … }]

- (NSString *)tableNameForSoup:(NSString *)soupName withDb:(FMDatabase *)db

Parameters

`db`	This method is expected to be called from [fmdbqueue inDatabase:^(){ … }]

Return Value

The soup table name from SOUP_ATTRS_TABLE, based on soup name.

Declared In

SFSmartStore+Internal.h

`– indicesForSoup:withDb:`

the name of the soup

- (NSArray *)indicesForSoup:(NSString *)soupName withDb:(FMDatabase *)db

Parameters

`soupName`	the name of the soup
`db`	This method is expected to be called from [fmdbqueue inDatabase:^(){ … }]

Return Value

NSArray of SFSoupIndex for the given soup

Declared In

SFSmartStore+Internal.h

`– reIndexSoup:withIndexPaths:withDb:`

Helper method re-index a soup.

- (BOOL)reIndexSoup:(NSString *)soupName withIndexPaths:(NSArray *)indexPaths withDb:(FMDatabase *)db

Parameters

`soupName`	The soup to re-index
`indexPaths`	Array of one ore more IndexSpec objects as dictionaries
`db`	This method is expected to be called from [fmdbqueue inDatabase:^(){ … }]

Return Value

YES if the insert was successful, NO otherwise.

Declared In

SFSmartStore+Internal.h

`– insertIntoTable:values:withDb:`

Helper method to insert values into an arbitrary table.

- (void)insertIntoTable:(NSString *)tableName values:(NSDictionary *)map withDb:(FMDatabase *)db

Parameters

`tableName`	The table to insert the data into.
`map`	A dictionary of key-value pairs to be inserted into table.
`db`	This method is expected to be called from [fmdbqueue inDatabase:^(){ … }]

Declared In

SFSmartStore+Internal.h

`– updateTable:values:entryId:idCol:withDb:`

Helper method to update existing values in a table.

- (void)updateTable:(NSString *)tableName values:(NSDictionary *)map entryId:(NSNumber *)entryId idCol:(NSString *)idCol withDb:(FMDatabase *)db

Parameters

`tableName`	The name of the table to update.
`map`	The column name/value mapping to update.
`entryId`	The ID value used to determine what to update.
`idCol`	The name of the ID column
`db`	This method is expected to be called from [fmdbqueue inDatabase:^(){ … }]

Declared In

SFSmartStore+Internal.h

`– queryTable:forColumns:orderBy:limit:whereClause:whereArgs:withDb:`

Helper to query table

- (FMResultSet *)queryTable:(NSString *)table forColumns:(NSArray *)columns orderBy:(NSString *)orderBy limit:(NSString *)limit whereClause:(NSString *)whereClause whereArgs:(NSArray *)whereArgs withDb:(FMDatabase *)db

Parameters

`table`	Table
`columns`	Column names
`orderBy`	Order by column
`limit`	Limit
`whereClause`	Where clause
`whereArgs`	Arguments to where clause
`db`	This method is expected to be called from [fmdbqueue inDatabase:^(){ … }]

Return Value

FMResultSet

Declared In

SFSmartStore+Internal.h

`– columnNameForPath:inSoup:withDb:`

Path of interest

- (NSString *)columnNameForPath:(NSString *)path inSoup:(NSString *)soupName withDb:(FMDatabase *)db

Parameters

`path`	Path of interest
`soupName`	name of the soup
`db`	This method is expected to be called from [fmdbqueue inDatabase:^(){ … }]

Return Value

The column name for the given path if indexed or nil otherwise.

Declared In

SFSmartStore+Internal.h

`– hasIndexForPath:inSoup:withDb:`

Path of interest

- (BOOL)hasIndexForPath:(NSString *)path inSoup:(NSString *)soupName withDb:(FMDatabase *)db

Parameters

`path`	Path of interest
`soupName`	name of the soup
`db`	This method is expected to be called from [fmdbqueue inDatabase:^(){ … }]

Return Value

YES if the given path is indexed or NO otherwise.

Declared In

SFSmartStore+Internal.h

`– currentTimeInMilliseconds`

Similar to System.currentTimeMillis: time in ms since Jan 1 1970 Used for timestamping created and modified times.

- (NSNumber *)currentTimeInMilliseconds

Return Value

The current number of milliseconds since 1/1/1970.

Declared In

SFSmartStore+Internal.h

`+ encKey`

The key used to encrypt the store.

+ (NSString *)encKey

Return Value

The key used to encrypt the store.

Declared In

SFSmartStore+Internal.h

`+ salt`

The key used to encrypt the store for shared mode. Sqlite headers are maintained in plain text for database.

+ (NSString *)salt

Return Value

The key used to encrypt the store for shared mode. Sqlite headers are maintained in plain text for database.

Declared In

SFSmartStore+Internal.h

`+ clearSharedStoreMemoryState`

FOR UNIT TESTING. Removes all of the shared smart store objects from memory (persisted stores remain).

+ (void)clearSharedStoreMemoryState

Declared In

SFSmartStore+Internal.h

`+ stringFromInputStream:`

FOR UNIT TESTING.

+ (NSString *)stringFromInputStream:(NSInputStream *)inputStream

Return Value

string decoded from the specified input stream

Declared In

SFSmartStore+Internal.h

`– convertSmartSql:`

Convert smart sql to sql.

- (NSString *)convertSmartSql:(NSString *)smartSql

Parameters

`smartSql`	The smart sql to convert.

Return Value

The sql.

Declared In

SFSmartStore+Internal.h

`– removeFromCache:`

Remove soup from cache

- (void)removeFromCache:(NSString *)soupName

Parameters

`soupName`	The name of the soup to remove

Declared In

SFSmartStore+Internal.h

`– getLongOperations`

unfinished long operations

- (NSArray *)getLongOperations

Return Value

unfinished long operations

Declared In

SFSmartStore+Internal.h

`– executeQueryThrows:withDb:`

Execute query Log errors and throw exception in case of error

- (FMResultSet *)executeQueryThrows:(NSString *)sql withDb:(FMDatabase *)db

Declared In

SFSmartStore+Internal.h

`– executeQueryThrows:withArgumentsInArray:withDb:`

Execute query Log errors and throw exception in case of error

- (FMResultSet *)executeQueryThrows:(NSString *)sql withArgumentsInArray:(NSArray *)arguments withDb:(FMDatabase *)db

Declared In

SFSmartStore+Internal.h

`– executeUpdateThrows:withDb:`

Execute update Log errors and throw exception in case of error

- (void)executeUpdateThrows:(NSString *)sql withDb:(FMDatabase *)db

Declared In

SFSmartStore+Internal.h

`– executeUpdateThrows:withArgumentsInArray:withDb:`

Execute update Log errors and throw exception in case of error

- (void)executeUpdateThrows:(NSString *)sql withArgumentsInArray:(NSArray *)arguments withDb:(FMDatabase *)db

Declared In

SFSmartStore+Internal.h

`– checkRawJson:fromMethod:`

Check that the given raw JSON string represents valid JSON. Note: If the jsonSerializationCheckEnabled property is set to NO, this method will always return YES (i.e. that the result is valid).

- (BOOL)checkRawJson:(NSString *)rawJson fromMethod:(NSString *)fromMethod

Parameters

`rawJson`	The raw JSON string to validate.
`fromMethod`	The method making the call (for logging purposes on failure).

Return Value

YES if the JSON string is valid JSON, NO otherwise.

Declared In

SFSmartStore+Internal.h