Class adobeDPS-EncryptedStorageService

If changePassword() is called with the retainPassword option set, and this results in a password being stored when none was previously, then the signal will fire as a result of isPasswordAvailable changing state; otherwise changePassword does not generate a state change that can be detected by the application.

An application may register a handler for this signal in order to track the state of the store. When the handler is invoked the state attributes of the EncryptedStorageService can be examined to determine what changed. There is currenly no automatic mechanism to determine what changed; the application is responsible for examining the state and determining the change. The signal is fired only after any callbacks from the provoking function are called.

If retainPassword in the options argument is true, then the password supplied to the next call to open() or changePassword() will be stored in the native secure password store (the KeyChain in iOS) for subsequent use; if the device does not support secure password storage, then errorCB() will be called with the error STORAGE_NO_SECURE_PASSWORD_STORE. Whenever a encrypted storage password is stored it will overwrite any other encrypted storage password that exists there.

Support for secure password storage can be determined by examining the hasSecurePasswordStorage field in the EncryptedStorageService class.

If retainPassword in the options argument is false, then the password will not be saved to the secure password store, and any password stored there will be removed.

If closeOnBackgrounding in the options argument is true, then the encrypted store will automatically be closed when the Viewer is sent to the background and open() will need to be called again to access its contents; otherwise, no such automatic closing is performed.

If no errors are encountered then successCB() is called with no arguments.

The password argument may be null or empty. If so, then an attempt to retrieve the password from the native secure password store is made. If the password does not exist there, or secure password storage is not supported, then errorCB() will be called with the error STORAGE_PASSWORD_NOT_AVAILABLE.

If the password obtained in either way does not successfully decrypt the store, then errorCB() will be called with the error STORAGE_DECRYPTION_ERROR.

If this is the first usage of the encrypted store on the device, or if the encrypted store has been reset, then this function will set the initial password. Once the encrypted store is closed, this same password must be supplied either from the password argument of open(), or from the device's secure password store, in order to access the contents of the store. The password may be changed with the changePassword() function.

If the encrypted store is opened without problems then successCB() will be called without any arguments.

The options argument to setSessionOptions() determines the behavior of open() with respect to password retention and application background behavior.

If the password is changed without problems then successCB() is called without any arguments.

The options argument to setSessionOptions() determines the behavior of changePassword() with respect to password retention. If the retainPassword field of the options argument is set to true, then the password passed to changePassword() will be saved into the native secure password store; if the value is false, then the password is not retained and will have to specified when calling open().

The options argument to setSessionOptions() provides the option to close the encrypted store whenever the application is sent to the background. If closeOnBackgrounding in the options argument is true, then the store will automatically be closed whenever the application is sent to the background, and open() will need to be called again to access its contents.

Calling this method should not normally be needed, but it may be useful during application development, or if storage I/O errors or other external problems affect the stability or integrity of the persistent storage. successCB() is called without any arguments if the service is successfully reset.

EncryptedStorageService itself does not define any error codes for this API entry, but the error callback may be called with OS-specific error codes generated from OS file operations.

The key must be a regular, printable JavaScript string with a maximum of 64 characters. A null or empty string is not allowed. The following special characters encoded with escape notation are not allowed: \' \" \\ \n \r \v \t \b \f. These are the single quote, double quote, backslash, new line, carriage return, vertical tab, tab, backspace, and form feed characters. If the key does not conform to these rules then errorCB() is called with the error STORAGE_INVALID_KEY. This check is performed before any other operation.

If the key already exists in the store then the new value will overwrite the old value. If the encrypted store is not open, then errorCB() will be called with the error STORAGE_NOT_OPEN.

Unlike the JavaScript localStorage API, the specified value may be any JavaScript object, including null, but it must not be undefined. The object is subjected to JSON serialization before passing it over the bridge to the native side, and is deserialized upon return with getItem(). Note that if the value contains binary data, then that binary data it must be encoded into text in order to be serialized into JSON and pass over the JavaScript bridge successfully.

The size of the value object is computed as the length of the JSON representation of the object in characters. It is limited to 16 million characters (1024*1024*16). If the value is larger than this limit, then errorCB() will be called with the error STORAGE_VALUE_SIZE_EXCEEDED.

If setItem() succeeds, then successCB() is called back with the key used to store the value.