In many scenarios on the client, key-value storage meets requirements. In most cases, we use NSUserDefaults. However, NSUserDefaults does not support encryption and is slow for data persistence.
In the unified storage component, the key-value storage provides interfaces for storage. PList objects of the NSInteger, long long (the same as NSInteger in 64-bit system), BOOL, double, and NSString types are supported. NSCoding objects are supported. Objective-C objects that can be converted to JSON objects through reflection are also supported. This greatly simplifies object persistence on the client.
For descriptions on most of the interfaces of key-value storage, see the method description in the header file APSharedPreferences.h
.
Basic storage types
The unified storage component provides the following types of interfaces for storage:
- (NSInteger)integerForKey:(NSString*)key business:(NSString*)business;
- (NSInteger)integerForKey:(NSString*)key business:(NSString*)business defaultValue:(NSInteger)defaultValue; // Return the default value when the data does not exist.
- (void)setInteger:(NSInteger)value forKey:(NSString*)key business:(NSString*)business;
- (long long)longLongForKey:(NSString*)key business:(NSString*)business;
- (long long)longLongForKey:(NSString*)key business:(NSString*)business defaultValue:(long long)defaultValue; // Return the default value when the data does not exist.
- (void)setLongLong:(long long)value forKey:(NSString*)key business:(NSString*)business;
- (BOOL)boolForKey:(NSString*)key business:(NSString*)business;
- (BOOL)boolForKey:(NSString*)key business:(NSString*)business defaultValue:(BOOL)defaultValue; // Return the default value when the data does not exist.
- (void)setBool:(BOOL)value forKey:(NSString*)key business:(NSString*)business;
- (double)doubleForKey:(NSString*)key business:(NSString*)business;
- (double)doubleForKey:(NSString*)key business:(NSString*)business defaultValue:(double)defaultValue; // Return the default value when the data does not exist.
- (void)setDouble:(double)value forKey:(NSString*)key business:(NSString*)business;
The defaultValue
returns the default value when the data does not exist.
Store Objective-C objects
Interface description
The unified storage component provides the following interfaces for storing Objective-C objects:
- (NSString*)stringForKey:(NSString*)key business:(NSString*)business;
- (NSString*)stringForKey:(NSString*)key business:(NSString*)business extension:(APDataCrypt*)extension;
- (void)setString:(NSString*)string forKey:(NSString*)key business:(NSString*)business;
- (void)setString:(NSString*)string forKey:(NSString*)key business:(NSString*)business extension:(APDataCrypt*)extension;
- (id)objectForKey:(NSString*)key business:(NSString*)business;
- (id)objectForKey:(NSString*)key business:(NSString*)business extension:(APDataCrypt*)extension;
- (void)setObject:(id)object forKey:(NSString*)key business:(NSString*)business;
- (void)setObject:(id)object forKey:(NSString*)key business:(NSString*)business extension:(APDataCrypt*)extension;
- (BOOL)setObject:(id)object forKey:(NSString*)key business:(NSString*)business extension:(APDataCrypt*)extension options:(APDataOptions)options;
- (void)archiveObject:(id)object forKey:(NSString*)key business:(NSString*)business;
- (void)archiveObject:(id)object forKey:(NSString*)key business:(NSString*)business extension:(APDataCrypt*)extension;
- (BOOL)archiveObject:(id)object forKey:(NSString*)key business:(NSString*)business extension:(APDataCrypt*)extension options:(APDataOptions)options;
- (void)saveJsonObject:(id)object forKey:(NSString*)key business:(NSString*)business;
- (void)saveJsonObject:(id)object forKey:(NSString*)key business:(NSString*)business extension:(APDataCrypt*)extension;
- (BOOL)saveJsonObject:(id)object forKey:(NSString*)key business:(NSString*)business extension:(APDataCrypt*)extension options:(APDataOptions)options;
setString & stringForKey
When you store NSString objects, setString
and stringForKey
interfaces is recommended, as the names are more explanatory.
If the data is not encrypted, strings stored by using this interface can be viewed in the SQLite DB viewer. Strings saved in the setObject
interface are firstly converted to NSData by using the Property List object and then stored in the database.
setObject
When you store Property List objects, we recommend that you use the setObject
interface is recommended for it’s highest efficiency.
Property List objects include NSNumber, NSString, NSData, NSDate, NSArray, and NSDictionary objects. The subobjects in NSArray and NSDictionary must also be PList objects.
If you use the setObject
interface to store Property List objects, the objects obtained by using the objectForKey
interface are mutable. In the following code, the obtained savedArray
objects are of the NSMutableArray
class.
NSArray* array = [[NSArray alloc] initWithObjects:@"str", nil];
[APCommonPreferences setObject:array forKey:@"array" business:@"biz"];
NSArray* savedArray = [APCommonPreferences objectForKey:@"array" business:@"biz"];
archiveObject
For an Objective-C object that supports the NSCoding protocol, the unified storage component calls the NSKeyedArchiver
method in the system to convert the object into an NSData object for persistence.
Property List objects can also use this interface, but with a lower efficiency and thus not recommended.
saveJsonObject
When an Objective-C object is neither a Property List object nor an NSCoding-supporting one, this method can be utilized for persistence storage.
This method maps the Objective-C object to a JSON string by performing runtime dynamic reflection. However, not all Objective-C objects can be stored in this method. For example, exceptions include Objective-C objects with the C structure pointer, Objective-C objects that are mutually referenced, and Objective-C objects with dictionaries or arrays.
objectForKey
When the unified storage component stores the data of Objective-C objects, it also records the archiving methods. The objects are all obtained in the objectForKey
method.
setString
method must be obtained in the stringForKey
method. Data encryption
Using default encryption
Interfaces with extension
support encryption and pass in the APDataCrypt
structure.
APDefaultEncrypt
is the default encryption method. It is AES encryption.
APDefaultDecrypt
is the default decryption method. It uses the same key with APDefaultEncrypt
.
In most cases, use the default encryption method provided by the unified storage component. The following code shows an example.
[APUserPreferences setObject:aObject forKey:@"key" business:@"biz" extension:APDefaultEncrypt()];
id obj = [APUserPreferences objectForKey:@"key" business:@"biz" extension:APDefaultDecrypt()];
// or
id obj = [APUserPreferences objectForKey:@"key" business:@"biz"];
The default encryption method is used. Therefore, the data acquisition interface can ignore the extension
parameter.
Use a custom encryption method
If your business has higher encryption security requirements, you can customize an APDataCrypt
structure and specify function pointers for encryption and decryption. But please ensure that the encryption and decryption methods are matched to save and recover data correctly.
Encrypt primary types
To encrypt BOOL, NSInteger, double, and long long objects for storage, you can convert them into strings or put them into the NSNumber class, and then call the setString
or setObject
interface.
Specify options
typedef NS_OPTIONS (unsigned int, APDataOptions)
{
// Do not use these two options in the interface. They identify the encryption attributes of the data. Use the extension parameter to pass the encryption method.
APDataOptionDefaultEncrypted = 1 << 0, // Do not pass this option, because this option will not be used. The unified storage component uses the extension parameter instead of options in the interface to specify encryption.
APDataOptionCustomEncrypted = 1 << 1, // Do not pass this option, because this option will not be used. The unified storage component uses the extension parameter instead of options in the interface to specify encryption.
// Indicate that the data can be cleared during cache clearance. In this example, unsinged int is used to forcibly transcode 1. For under some compiling options, 1<<31 on the right cannot be calculated by using unsigned int, leading to value assignment failure.
APDataOptionPurgeable = (unsigned int)1 << 31,
};
You can specify options in the setObject
, archiveObject
, or saveJsonObject
method.
APDataOptionPurgeable
indicates that the data can be automatically cleared during data clearance. For more information, see Data clearence.