# Print output for @column tags ?> PackageInstaller.Session - Android SDK | Android Developers

Most visited

Recently visited

PackageInstaller.Session

public static class PackageInstaller.Session
extends Object implements Closeable

java.lang.Object
   ↳ android.content.pm.PackageInstaller.Session


An installation that is being actively staged. For an install to succeed, all existing and new packages must have identical package names, version codes, and signing certificates.

A session may contain any number of split packages. If the application does not yet exist, this session must include a base package.

If an APK included in this session is already defined by the existing installation (for example, the same split name), the APK in this session will replace the existing APK.

In such a case that multiple packages need to be committed simultaneously, multiple sessions can be referenced by a single multi-package session. This session is created with no package name and calling SessionParams#setMultiPackage(). The individual session IDs can be added with addChildSessionId(int) and commit of the multi-package session will result in all child sessions being committed atomically.

Summary

Public methods

void abandon()

Completely abandon this session, destroying all staged data and rendering it invalid.

void addChildSessionId(int sessionId)

Adds a session ID to the set of sessions that will be committed atomically when this session is committed.

void close()

Release this session object.

void commit(IntentSender statusReceiver)

Attempt to commit everything staged in this session.

void fsync(OutputStream out)

Ensure that any outstanding data for given stream has been committed to disk.

int[] getChildSessionIds()
String[] getNames()

Return all APK names contained in this session.

int getParentSessionId()
boolean isMultiPackage()
boolean isStaged()
InputStream openRead(String name)

Open a stream to read an APK file from the session.

OutputStream openWrite(String name, long offsetBytes, long lengthBytes)

Open a stream to write an APK file into the session.

void removeChildSessionId(int sessionId)

Removes a session ID from the set of sessions that will be committed atomically when this session is committed.

void removeSplit(String splitName)

Removes a split.

void setChecksums(String name, List<Checksum> checksums, byte[] signature)

This method is deprecated. do not use installer-provided checksums, use platform-enforced checksums e.g. Checksum#TYPE_WHOLE_MERKLE_ROOT_4K_SHA256 in PackageManager#requestChecksums.

void setStagingProgress(float progress)

Set current progress of staging this session.

void transfer(String packageName)

Transfer the session to a new owner.

Inherited methods

Public methods

abandon

public void abandon ()

Completely abandon this session, destroying all staged data and rendering it invalid. Abandoned sessions will be reported to SessionCallback listeners as failures. This is equivalent to PackageInstaller.abandonSession(int).

If the parent is abandoned, all children will also be abandoned. Any written data would be destroyed and the created Session information will be discarded.

addChildSessionId

public void addChildSessionId (int sessionId)

Adds a session ID to the set of sessions that will be committed atomically when this session is committed.

If the parent is staged or has rollback enabled, all children must have the same properties.

If the parent is abandoned, all children will also be abandoned.

Parameters
sessionId int: the session ID to add to this multi-package session.

close

public void close ()

Release this session object. You can open the session again if it hasn't been finalized.

commit

public void commit (IntentSender statusReceiver)

Attempt to commit everything staged in this session. This may require user intervention, and so it may not happen immediately. The final result of the commit will be reported through the given callback.

Once this method is called, the session is sealed and no additional mutations may be performed on the session. In case of device reboot or data loader transient failure before the session has been finalized, you may commit the session again.

If the installer is the device owner or the affiliated profile owner, there will be no user intervention.

Parameters
statusReceiver IntentSender: Called when the state of the session changes. Intents sent to this receiver contain PackageInstaller.EXTRA_STATUS. Refer to the individual status codes on how to handle them. This value cannot be null.

Throws
SecurityException if streams opened through openWrite(java.lang.String, long, long) are still open.

See also:

fsync

public void fsync (OutputStream out)

Ensure that any outstanding data for given stream has been committed to disk. This is only valid for streams returned from openWrite(java.lang.String, long, long).

Parameters
out OutputStream: This value cannot be null.

Throws
IOException

getChildSessionIds

public int[] getChildSessionIds ()

Returns
int[] the set of session IDs that will be committed atomically when this session is committed if this is a multi-package session or null if none exist.

getNames

public String[] getNames ()

Return all APK names contained in this session.

This returns all names which have been previously written through openWrite(java.lang.String, long, long) as part of this session.

Returns
String[] This value cannot be null.

Throws
SecurityException if called after the session has been committed or abandoned.
IOException

getParentSessionId

public int getParentSessionId ()

Returns
int the session ID of the multi-package session that this belongs to or SessionInfo#INVALID_ID if it does not belong to a multi-package session.

isMultiPackage

public boolean isMultiPackage ()

Returns
boolean true if this session will commit more than one package when it is committed.

isStaged

public boolean isStaged ()

Returns
boolean true if this session will be staged and applied at next reboot.

openRead

public InputStream openRead (String name)

Open a stream to read an APK file from the session.

This is only valid for names which have been previously written through openWrite(java.lang.String, long, long) as part of this session. For example, this stream may be used to calculate a MessageDigest of a written APK before committing.

Parameters
name String: This value cannot be null.

Returns
InputStream This value cannot be null.

Throws
SecurityException if called after the session has been committed or abandoned.
IOException

openWrite

public OutputStream openWrite (String name, 
                long offsetBytes, 
                long lengthBytes)

Open a stream to write an APK file into the session.

The returned stream 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's strongly recommended to provide a valid file length when known.

You can write data into the returned stream, optionally call fsync(java.io.OutputStream) as needed to ensure bytes have been persisted to disk, and then close when finished. All streams must be closed before calling commit(android.content.IntentSender).

Parameters
name String: arbitrary, unique name of your choosing to identify the APK being written. You can open a file again for additional writes (such as after a reboot) by using the same name. This name is only meaningful within the context of a single install session. This value cannot be null.

offsetBytes long: offset into the file to begin writing at, or 0 to start at the beginning of the file.

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.

Returns
OutputStream This value cannot be null.

Throws
IOException if trouble opening the file for writing, such as lack of disk space or unavailable media.
SecurityException if called after the session has been sealed or abandoned

removeChildSessionId

public void removeChildSessionId (int sessionId)

Removes a session ID from the set of sessions that will be committed atomically when this session is committed.

Parameters
sessionId int: the session ID to remove from this multi-package session.

removeSplit

public void removeSplit (String splitName)

Removes a split.

Split removals occur prior to adding new APKs. If upgrading a feature split, it is not expected nor desirable to remove the split prior to upgrading.

When split removal is bundled with new APKs, the packageName must be identical.

Parameters
splitName String: This value cannot be null.

Throws
IOException

setChecksums

public void setChecksums (String name, 
                List<Checksum> checksums, 
                byte[] signature)

This method is deprecated.
do not use installer-provided checksums, use platform-enforced checksums e.g. Checksum#TYPE_WHOLE_MERKLE_ROOT_4K_SHA256 in PackageManager#requestChecksums.

Sets installer-provided checksums for the APK file in session.

Parameters
name String: previously written as part of this session. openWrite(String, long, long) This value cannot be null.

checksums List: installer intends to make available via PackageManager#requestChecksums. This value cannot be null.

signature byte: DER PKCS#7 detached signature bytes over binary serialized checksums to enable integrity checking for the checksums or null for no integrity checking. PackageManager#requestChecksums will return the certificate used to create signature. Binary format for checksums:
DataOutputStream dos;
                  dos.writeInt(checksum.getType());
                  dos.writeInt(checksum.getValue().length);
                  dos.write(checksum.getValue());
If using openssl cms, make sure to specify -binary -nosmimecap. This value may be null.

Throws
SecurityException if called after the session has been committed or abandoned.
IllegalStateException if checksums for this file have already been added.
IOException

See also:

setStagingProgress

public void setStagingProgress (float progress)

Set current progress of staging this session. Valid values are anywhere between 0 and 1.

Note that this progress may not directly correspond to the value reported by SessionCallback#onProgressChanged(int, float), as the system may carve out a portion of the overall progress to represent its own internal installation work.

Parameters
progress float

transfer

public void transfer (String packageName)

Transfer the session to a new owner.

Only sessions that update the installing app can be transferred.

After the transfer to a package with a different uid all method calls on the session will cause SecurityExceptions.

Once this method is called, the session is sealed and no additional mutations beside committing it may be performed on the session.

Parameters
packageName String: The package of the new owner. Needs to hold the INSTALL_PACKAGES permission. This value cannot be null.

Throws
PackageManager.NameNotFoundException if the new owner could not be found.
SecurityException if called after the session has been committed or abandoned.
IllegalStateException if streams opened through {@link #openWrite(java.lang.String,long,long) are still open.
IllegalArgumentException if packageName is invalid.