org.researchstack.backbone

Class StorageAccess

java.lang.Object

org.researchstack.backbone.StorageAccess

public class StorageAccess
extends java.lang.Object

This class is responsible for providing access to the pin-protected file storage and database. Before calling getFileAccess() or getAppDatabase(), make sure to call register(org.researchstack.backbone.storage.file.StorageAccessListener) and requestStorageAccess(android.content.Context). Once StorageAccessListener.onDataReady() is called, then you may call these methods and read/write your data.

If StorageAccessListener.onDataAuth() is called, then you must prompt the user for their pin and authenticate using authenticate(android.content.Context, java.lang.String).

PinCodeActivity handles almost all of this for you, including presenting the pin code screen to the user. PinCodeActivity should be used, extended, or it's fuctionality copied to your application's own base Activity. Make sure to delay any data access until PinCodeActivity.onDataReady() has been called.

Method Summary

Modifier and Type	Method and Description
void	authenticate(android.content.Context context, java.lang.String pin) Attempts authenticating with the provided pin.
void	changePinCode(android.content.Context context, java.lang.String oldPin, java.lang.String newPin) Changes the pin code if the provided old pin matches, otherwise throws a StorageAccessException.
void	createPinCode(android.content.Context context, java.lang.String pin) Creates a master key encrypted by the pin code provided.
AppDatabase	getAppDatabase() Returns the AppDatabase singleton for this application.
FileAccess	getFileAccess() Returns the FileAccess singleton for this application.
static StorageAccess	getInstance() Returns the singleton instance of this class.
PinCodeConfig	getPinCodeConfig() Returns the pin code configuration for the app
boolean	hasPinCode(android.content.Context context) Returns whether the user has created a pin code or not
void	init(PinCodeConfig pinCodeConfig, EncryptionProvider encryptionProvider, FileAccess fileAccess, AppDatabase appDatabase) Initializes the storage access singleton with the provided dependencies.
void	logAccessTime() Logs the last access time in order to time out the pin code after the amount of time set in the PinCodeConfig.
void	register(StorageAccessListener storageAccessListener) Registers a listener.
void	requestStorageAccess(android.content.Context context) Checks and inits storage access.
void	unregister(StorageAccessListener storageAccessListener) Guess what this does.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

init

public void init(PinCodeConfig pinCodeConfig,
                 EncryptionProvider encryptionProvider,
                 FileAccess fileAccess,
                 AppDatabase appDatabase)

Initializes the storage access singleton with the provided dependencies. It is best to call this method inside your Application.onCreate() method.

Parameters:

pinCodeConfig - an instance of the pin code configuration for your app

encryptionProvider - an encryption provider

fileAccess - an implementation of FileAccess

appDatabase - an implementation of AppDatabase

getInstance

public static StorageAccess getInstance()

Returns the singleton instance of this class.

Returns:

the singleton instance of this class

getFileAccess

public FileAccess getFileAccess()

Returns the FileAccess singleton for this application. Should only be called after StorageAccessListener.onDataReady().

Returns:

the FileAccess singleton

getAppDatabase

public AppDatabase getAppDatabase()

Returns the AppDatabase singleton for this application. Should only be called after StorageAccessListener.onDataReady().

Returns:

the AppDatabase singleton

getPinCodeConfig

public PinCodeConfig getPinCodeConfig()

Returns the pin code configuration for the app

Returns:

the pin code configuration

hasPinCode

public boolean hasPinCode(android.content.Context context)

Returns whether the user has created a pin code or not

Parameters:

context - android context

Returns:

a boolean indicating if the user has created a pin code

requestStorageAccess

@MainThread
public void requestStorageAccess(android.content.Context context)

Checks and inits storage access. Once storage access is ready, registered listeners will be notified via the StorageAccessListener. This is true whether there is an auth flow or if the system is already prepared. The callback will happen on the main thread looper, after all scheduled events, which will include (in the standard case) onCreate/onStart/onResume, and the equivalent Fragment callbacks. This is to ensure one path, and reduce edge case race conditions.

Parameters:

context - Calling context. If you are calling from an Activity, its best to send it and not the application context, because we may want to start new activities, and the application context can only do so with a new task, which will possibly complicate the back stack. We won't do anything weird that causes memory leaks. Promise ;)

register

@MainThread
public final void register(StorageAccessListener storageAccessListener)

Registers a listener. If you want to read/write data, you'll need to implement this to know when file access is ready.

Parameters:

storageAccessListener -

unregister

@MainThread
public final void unregister(StorageAccessListener storageAccessListener)

Guess what this does. Yes, you'll need to call it if you called register or you'll have memory leaks and possibly crashes on callbacks to dead clients.

Parameters:

storageAccessListener -

logAccessTime

public void logAccessTime()

Logs the last access time in order to time out the pin code after the amount of time set in the PinCodeConfig.

An example of how this should be used is in PinCodeActivity.onPause(). This will ensure that it updates frequently while the user is still inside of the app so as not to trigger a reset, but will reset if the user has been outside of the app for too long.

authenticate

public void authenticate(android.content.Context context,
                         java.lang.String pin)

Attempts authenticating with the provided pin. On an invalid pin, it will throw StorageAccessException.

Parameters:

context - android context

pin - string of the pin to attempt authentication

Throws:

StorageAccessException

createPinCode

public void createPinCode(android.content.Context context,
                          java.lang.String pin)

Creates a master key encrypted by the pin code provided. This can only happen once and will throw a StorageAccessException on subsequent calls.

Parameters:

context - android context

pin - the user's pin, this should already be validated (enter + confirm)

Throws:

StorageAccessException - if there is already a pin code

changePinCode

public void changePinCode(android.content.Context context,
                          java.lang.String oldPin,
                          java.lang.String newPin)

Changes the pin code if the provided old pin matches, otherwise throws a StorageAccessException.

Parameters:

context - android context

oldPin - the old pin

newPin - the new pin, which should already be validated (enter + confirm)

Throws:

StorageAccessException