Added in API level 30

Session


open class Session : Closeable
kotlin.Any
   ↳ android.app.blob.BlobStoreManager.Session

Represents an ongoing session of a blob's contribution to the blob store managed by the system.

Clients that want to contribute a blob need to first create a Session using createSession(android.app.blob.BlobHandle) and once the session is created, clients can open and close this session multiple times using openSession(long) and android.app.blob.BlobStoreManager.Session#close() before committing it using Session#commit(Executor, Consumer), at which point system will take ownership of the blob and the client can no longer make any modifications to the blob's content.

Summary

Public methods
open Unit

Abandon this session and delete any data that was written to this session so far.

open Unit
allowPackageAccess(packageName: String, certificate: ByteArray)

Allow packageName with a particular signing certificate to access this blob data once it is committed using a BlobHandle representing the blob.

open Unit

Allow any app on the device to access this blob data once it is committed using a BlobHandle representing the blob.

open Unit

Allow packages which are signed with the same certificate as the caller to access this blob data once it is committed using a BlobHandle representing the blob.

open Unit

Close this session.

open Unit
commit(executor: Executor, resultCallback: Consumer<Int!>)

Commit the file that was written so far to this session to the blob store maintained by the system.

open Long

Gets the size of the blob file that was written to the session so far.

open Boolean
isPackageAccessAllowed(packageName: String, certificate: ByteArray)

Returns true if access has been allowed for a packageName using either allowPackageAccess(java.lang.String,byte[]).

open Boolean

Returns true if public access has been allowed by using allowPublicAccess().

open Boolean

Returns true if access has been allowed for packages signed with the same certificate as the caller by using allowSameSignatureAccess().

open ParcelFileDescriptor

Opens a file descriptor to read the blob content already written into this session.

open ParcelFileDescriptor
openWrite(offsetBytes: Long, lengthBytes: Long)

Opens a file descriptor to write a blob into the session.

Public methods

abandon

Added in API level 30
open fun abandon(): Unit

Abandon this session and delete any data that was written to this session so far.

Exceptions
java.io.IOException when there is an I/O error while abandoning the session.
java.lang.SecurityException when the caller is not the owner of the session.
java.lang.IllegalStateException when the caller tries to abandon a session which was already finalized.

allowPackageAccess

Added in API level 30
open fun allowPackageAccess(
    packageName: String,
    certificate: ByteArray
): Unit

Allow packageName with a particular signing certificate to access this blob data once it is committed using a BlobHandle representing the blob.

This needs to be called before committing the blob using commit(java.util.concurrent.Executor,java.util.function.Consumer).

Parameters
packageName String: the name of the package which should be allowed to access the blob. This value cannot be null.
certificate ByteArray: the input bytes representing a certificate of type android.content.pm.PackageManager#CERT_INPUT_SHA256. This value cannot be null.
Exceptions
java.io.IOException when there is an I/O error while changing the access.
java.lang.SecurityException when the caller is not the owner of the session.
java.lang.IllegalStateException when the caller tries to change access for a blob which is already committed.
android.os.LimitExceededException when the caller tries to explicitly allow too many packages using this API.

allowPublicAccess

Added in API level 30
open fun allowPublicAccess(): Unit

Allow any app on the device to access this blob data once it is committed using a BlobHandle representing the blob.

Note: This is only meant to be used from libraries and SDKs where the apps which we want to allow access is not known ahead of time. If a blob is being committed to be shared with a particular set of apps, it is highly recommended to use allowPackageAccess(java.lang.String,byte[]) instead.

This needs to be called before committing the blob using commit(java.util.concurrent.Executor,java.util.function.Consumer).

Exceptions
java.io.IOException when there is an I/O error while changing the access.
java.lang.SecurityException when the caller is not the owner of the session.
java.lang.IllegalStateException when the caller tries to change access for a blob which is already committed.

allowSameSignatureAccess

Added in API level 30
open fun allowSameSignatureAccess(): Unit

Allow packages which are signed with the same certificate as the caller to access this blob data once it is committed using a BlobHandle representing the blob.

This needs to be called before committing the blob using commit(java.util.concurrent.Executor,java.util.function.Consumer).

Exceptions
java.io.IOException when there is an I/O error while changing the access.
java.lang.SecurityException when the caller is not the owner of the session.
java.lang.IllegalStateException when the caller tries to change access for a blob which is already committed.

close

Added in API level 30
open fun close(): Unit

Close this session. It can be re-opened for writing/reading if it has not been abandoned (using abandon) or committed (using commit).

Exceptions
java.lang.Exception if this resource cannot be closed
java.io.IOException when there is an I/O error while closing the session.
java.lang.SecurityException when the caller is not the owner of the session.

commit

Added in API level 30
open fun commit(
    executor: Executor,
    resultCallback: Consumer<Int!>
): Unit

Commit the file that was written so far to this session to the blob store maintained by the system.

Once this method is called, the session is finalized and no additional mutations can be performed on the session. If the device reboots before the session has been finalized, you may commit the session again.

Note that this commit operation will fail if the hash of the data written so far to this session does not match with the one used for BlobHandle#createWithSha256(byte[], CharSequence, long, String) BlobHandle} associated with this session.

Committing the same data more than once will result in replacing the corresponding access mode (via calling one of allowPackageAccess(java.lang.String,byte[]), allowSameSignatureAccess(), etc) with the latest one.

Parameters
executor Executor: the executor on which result callback will be invoked. This value cannot be null. Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.
resultCallback Consumer<Int!>: a callback to receive the commit result. when the result is 0, it indicates success. Otherwise, failure. This value cannot be null.
Exceptions
java.io.IOException when there is an I/O error while committing the session.
java.lang.SecurityException when the caller is not the owner of the session.
java.lang.IllegalArgumentException when the passed parameters are not valid.
java.lang.IllegalStateException when the caller tries to commit a session which was already finalized.

getSize

Added in API level 30
open fun getSize(): Long

Gets the size of the blob file that was written to the session so far.
Value is a non-negative number of bytes.

Return
Long the size of the blob file so far. Value is a non-negative number of bytes.
Exceptions
java.io.IOException when there is an I/O error while opening the file to read.
java.lang.SecurityException when the caller is not the owner of the session.
java.lang.IllegalStateException when the caller tries to get the file size after it is abandoned (using abandon()) or closed (using #close()).

isPackageAccessAllowed

Added in API level 30
open fun isPackageAccessAllowed(
    packageName: String,
    certificate: ByteArray
): Boolean

Returns true if access has been allowed for a packageName using either allowPackageAccess(java.lang.String,byte[]). Otherwise, false.

Parameters
packageName String: the name of the package to check the access for. This value cannot be null.
certificate ByteArray: the input bytes representing a certificate of type android.content.pm.PackageManager#CERT_INPUT_SHA256. This value cannot be null.
Exceptions
java.io.IOException when there is an I/O error while getting the access type.
java.lang.IllegalStateException when the caller tries to get access type from a session which is closed or abandoned.

isPublicAccessAllowed

Added in API level 30
open fun isPublicAccessAllowed(): Boolean

Returns true if public access has been allowed by using allowPublicAccess(). Otherwise, false.

Exceptions
java.io.IOException when there is an I/O error while getting the access type.
java.lang.IllegalStateException when the caller tries to get access type from a session which is closed or abandoned.

isSameSignatureAccessAllowed

Added in API level 30
open fun isSameSignatureAccessAllowed(): Boolean

Returns true if access has been allowed for packages signed with the same certificate as the caller by using allowSameSignatureAccess(). Otherwise, false.

Exceptions
java.io.IOException when there is an I/O error while getting the access type.
java.lang.IllegalStateException when the caller tries to get access type from a session which is closed or abandoned.

openRead

Added in API level 30
open fun openRead(): ParcelFileDescriptor

Opens a file descriptor to read the blob content already written into this session.

Return
ParcelFileDescriptor a ParcelFileDescriptor for reading from the blob file. This value cannot be null.
Exceptions
java.io.IOException when there is an I/O error while opening the file to read.
java.lang.SecurityException when the caller is not the owner of the session.
java.lang.IllegalStateException when the caller tries to read the file after it is abandoned (using abandon()) or closed (using #close()).

openWrite

Added in API level 30
open fun openWrite(
    offsetBytes: Long,
    lengthBytes: Long
): ParcelFileDescriptor

Opens a file descriptor to write a blob into the session.

The returned file descriptor will start writing data at the requested offset in the underlying file, which can be used to resume a partially written file. If a valid file length is specified, the system will preallocate the underlying disk space to optimize placement on disk. It is strongly recommended to provide a valid file length when known.

Parameters
offsetBytes Long: offset into the file to begin writing at, or 0 to start at the beginning of the file. Value is a non-negative number of bytes.
lengthBytes Long: total size of the file being written, used to preallocate the underlying disk space, or -1 if unknown. The system may clear various caches as needed to allocate this space. Value is a non-negative number of bytes.
Return
ParcelFileDescriptor a ParcelFileDescriptor for writing to the blob file. This value cannot be null.
Exceptions
java.io.IOException when there is an I/O error while opening the file to write.
java.lang.SecurityException when the caller is not the owner of the session.
java.lang.IllegalStateException when the caller tries to write to the file after it is abandoned (using abandon()) or committed (using commit) or closed (using #close()).