java.lang.Object | |
↳ | android.content.pm.PackageInstaller |
Offers the ability to install, upgrade, and remove applications on the device. This includes support for apps packaged either as a single "monolithic" APK, or apps packaged as multiple "split" APKs.
An app is delivered for installation through a
PackageInstaller.Session
, which any app can create. Once the session
is created, the installer can stream one or more APKs into place until it
decides to either commit or destroy the session. Committing may require user
intervention to complete the installation.
Sessions can install brand new apps, upgrade existing apps, or add new splits into an existing app.
Apps packaged as multiple split APKs always consist of a single "base" APK
(with a null
split name) and zero or more "split" APKs (with unique
split names). Any subset of these APKs can be installed together, as long as
the following constraints are met:
Nested Classes | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
PackageInstaller.Session | An installation that is being actively staged. | ||||||||||
PackageInstaller.SessionCallback | Events for observing session lifecycle. | ||||||||||
PackageInstaller.SessionInfo | Details for an active install session. | ||||||||||
PackageInstaller.SessionParams |
Parameters for creating a new PackageInstaller.Session .
|
Constants | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
String | ACTION_SESSION_DETAILS | Activity Action: Show details about a particular install session. | |||||||||
String | EXTRA_OTHER_PACKAGE_NAME | Another package name relevant to a status. | |||||||||
String | EXTRA_PACKAGE_NAME | Package name that an operation is working with. | |||||||||
String | EXTRA_SESSION_ID | An integer session ID that an operation is working with. | |||||||||
String | EXTRA_STATUS | Current status of an operation. | |||||||||
String | EXTRA_STATUS_MESSAGE | Detailed string representation of the status, including raw details that are useful for debugging. | |||||||||
String | EXTRA_STORAGE_PATH | Storage path relevant to a status. | |||||||||
int | STATUS_FAILURE | The operation failed in a generic way. | |||||||||
int | STATUS_FAILURE_ABORTED | The operation failed because it was actively aborted. | |||||||||
int | STATUS_FAILURE_BLOCKED | The operation failed because it was blocked. | |||||||||
int | STATUS_FAILURE_CONFLICT | The operation failed because it conflicts (or is inconsistent with) with another package already installed on the device. | |||||||||
int | STATUS_FAILURE_INCOMPATIBLE | The operation failed because it is fundamentally incompatible with this device. | |||||||||
int | STATUS_FAILURE_INVALID | The operation failed because one or more of the APKs was invalid. | |||||||||
int | STATUS_FAILURE_STORAGE | The operation failed because of storage issues. | |||||||||
int | STATUS_PENDING_USER_ACTION | User action is currently required to proceed. | |||||||||
int | STATUS_SUCCESS | The operation succeeded. |
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Completely abandon the given session, destroying all staged data and
rendering it invalid.
| |||||||||||
Create a new session using the given parameters, returning a unique ID
that represents the session.
| |||||||||||
Return list of all known install sessions, regardless of the installer.
| |||||||||||
Return list of all known install sessions owned by the calling app.
| |||||||||||
Return details for a specific session.
| |||||||||||
Open an existing session to actively perform work.
| |||||||||||
Register to watch for session lifecycle events.
| |||||||||||
Register to watch for session lifecycle events.
| |||||||||||
Uninstall the given package, removing it completely from the device.
| |||||||||||
Unregister a previously registered callback.
| |||||||||||
Update the icon representing the app being installed in a specific
session.
| |||||||||||
Update the label representing the app being installed in a specific
session.
|
[Expand]
Inherited Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
java.lang.Object
|
Activity Action: Show details about a particular install session. This may surface actions such as pause, resume, or cancel.
This should always be scoped to the installer package that owns the
session. Clients should use createDetailsIntent()
to
build this intent correctly.
In some cases, a matching Activity may not exist, so ensure you safeguard against this.
The session to show details for is defined in EXTRA_SESSION_ID
.
Another package name relevant to a status. This is typically the package responsible for causing an operation failure.
Package name that an operation is working with.
An integer session ID that an operation is working with.
Current status of an operation. Will be one of
STATUS_PENDING_USER_ACTION
, STATUS_SUCCESS
,
STATUS_FAILURE
, STATUS_FAILURE_ABORTED
,
STATUS_FAILURE_BLOCKED
, STATUS_FAILURE_CONFLICT
,
STATUS_FAILURE_INCOMPATIBLE
, STATUS_FAILURE_INVALID
, or
STATUS_FAILURE_STORAGE
.
More information about a status may be available through additional extras; see the individual status documentation for details.
Detailed string representation of the status, including raw details that are useful for debugging.
Storage path relevant to a status.
The operation failed in a generic way. The system will always try to provide a more specific failure reason, but in some rare cases this may be delivered.
The operation failed because it was actively aborted. For example, the user actively declined requested permissions, or the session was abandoned.
The operation failed because it was blocked. For example, a device policy may be blocking the operation, a package verifier may have blocked the operation, or the app may be required for core system operation.
The result may also contain EXTRA_OTHER_PACKAGE_NAME
with the
specific package blocking the install.
The operation failed because it conflicts (or is inconsistent with) with another package already installed on the device. For example, an existing permission, incompatible certificates, etc. The user may be able to uninstall another app to fix the issue.
The result may also contain EXTRA_OTHER_PACKAGE_NAME
with the
specific package identified as the cause of the conflict.
The operation failed because it is fundamentally incompatible with this device. For example, the app may require a hardware feature that doesn't exist, it may be missing native code for the ABIs supported by the device, or it requires a newer SDK version, etc.
The operation failed because one or more of the APKs was invalid. For example, they might be malformed, corrupt, incorrectly signed, mismatched, etc.
The operation failed because of storage issues. For example, the device may be running low on space, or external media may be unavailable. The user may be able to help free space or insert different external media.
The result may also contain EXTRA_STORAGE_PATH
with the path to
the storage device that caused the failure.
User action is currently required to proceed. You can launch the intent
activity described by EXTRA_INTENT
to involve the user and
continue.
You may choose to immediately launch the intent if the user is actively using your app. Otherwise, you should use a notification to guide the user back into your app before launching.
The operation succeeded.
Completely abandon the given session, destroying all staged data and
rendering it invalid. Abandoned sessions will be reported to
PackageInstaller.SessionCallback
listeners as failures. This is equivalent to
opening the session and calling abandon()
.
SecurityException | when the caller does not own the session, or the session is invalid. |
---|
Create a new session using the given parameters, returning a unique ID that represents the session. Once created, the session can be opened multiple times across multiple device boots.
The system may automatically destroy sessions that have not been finalized (either committed or abandoned) within a reasonable period of time, typically on the order of a day.
IOException | if parameters were unsatisfiable, such as lack of disk space or unavailable media. |
---|---|
SecurityException | when installation services are unavailable, such as when called from a restricted user. |
IllegalArgumentException | when PackageInstaller.SessionParams is invalid. |
Return list of all known install sessions, regardless of the installer.
Return list of all known install sessions owned by the calling app.
Return details for a specific session. No special permissions are required to retrieve these details.
null
if the session
does not exist.
Open an existing session to actively perform work. To succeed, the caller must be the owner of the install session.
IOException | if parameters were unsatisfiable, such as lack of disk space or unavailable media. |
---|---|
SecurityException | when the caller does not own the session, or the session is invalid. |
Register to watch for session lifecycle events. No special permissions are required to watch for these events.
handler | to dispatch callback events through, otherwise uses calling thread. |
---|
Register to watch for session lifecycle events. No special permissions are required to watch for these events.
Uninstall the given package, removing it completely from the device. This method is only available to the current "installer of record" for the package.
Unregister a previously registered callback.
Update the icon representing the app being installed in a specific
session. This should be roughly
getLauncherLargeIconSize()
in both dimensions.
SecurityException | when the caller does not own the session, or the session is invalid. |
---|
Update the label representing the app being installed in a specific session.
SecurityException | when the caller does not own the session, or the session is invalid. |
---|