public class PackageInstaller extends Object
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:
Modifier and Type | Class and Description |
---|---|
static class |
PackageInstaller.Session
An installation that is being actively staged.
|
static class |
PackageInstaller.SessionCallback
Events for observing session lifecycle.
|
static class |
PackageInstaller.SessionInfo
Details for an active install session.
|
static class |
PackageInstaller.SessionParams
Parameters for creating a new
PackageInstaller.Session . |
Modifier and Type | Field and Description |
---|---|
static String |
ACTION_CONFIRM_PERMISSIONS |
static String |
ACTION_SESSION_DETAILS
Activity Action: Show details about a particular install session.
|
static String |
EXTRA_CALLBACK |
static String |
EXTRA_LEGACY_BUNDLE |
static String |
EXTRA_LEGACY_STATUS |
static String |
EXTRA_OTHER_PACKAGE_NAME
Another package name relevant to a status.
|
static String |
EXTRA_PACKAGE_NAME
Package name that an operation is working with.
|
static String |
EXTRA_PACKAGE_NAMES
Deprecated.
|
static String |
EXTRA_SESSION_ID
An integer session ID that an operation is working with.
|
static String |
EXTRA_STATUS
Current status of an operation.
|
static String |
EXTRA_STATUS_MESSAGE
Detailed string representation of the status, including raw details that
are useful for debugging.
|
static String |
EXTRA_STORAGE_PATH
Storage path relevant to a status.
|
static int |
STATUS_FAILURE
The operation failed in a generic way.
|
static int |
STATUS_FAILURE_ABORTED
The operation failed because it was actively aborted.
|
static int |
STATUS_FAILURE_BLOCKED
The operation failed because it was blocked.
|
static int |
STATUS_FAILURE_CONFLICT
The operation failed because it conflicts (or is inconsistent with) with
another package already installed on the device.
|
static int |
STATUS_FAILURE_INCOMPATIBLE
The operation failed because it is fundamentally incompatible with this
device.
|
static int |
STATUS_FAILURE_INVALID
The operation failed because one or more of the APKs was invalid.
|
static int |
STATUS_FAILURE_STORAGE
The operation failed because of storage issues.
|
static int |
STATUS_PENDING_USER_ACTION
User action is currently required to proceed.
|
static int |
STATUS_SUCCESS
The operation succeeded.
|
Constructor and Description |
---|
PackageInstaller(Context context,
PackageManager pm,
IPackageInstaller installer,
String installerPackageName,
int userId) |
Modifier and Type | Method and Description |
---|---|
void |
abandonSession(int sessionId)
Completely abandon the given session, destroying all staged data and
rendering it invalid.
|
void |
addSessionCallback(PackageInstaller.SessionCallback callback)
Deprecated.
|
void |
addSessionCallback(PackageInstaller.SessionCallback callback,
Handler handler)
Deprecated.
|
int |
createSession(PackageInstaller.SessionParams params)
Create a new session using the given parameters, returning a unique ID
that represents the session.
|
List<PackageInstaller.SessionInfo> |
getAllSessions()
Return list of all known install sessions, regardless of the installer.
|
List<PackageInstaller.SessionInfo> |
getMySessions()
Return list of all known install sessions owned by the calling app.
|
PackageInstaller.SessionInfo |
getSessionInfo(int sessionId)
Return details for a specific session.
|
PackageInstaller.Session |
openSession(int sessionId)
Open an existing session to actively perform work.
|
void |
registerSessionCallback(PackageInstaller.SessionCallback callback)
Register to watch for session lifecycle events.
|
void |
registerSessionCallback(PackageInstaller.SessionCallback callback,
Handler handler)
Register to watch for session lifecycle events.
|
void |
removeSessionCallback(PackageInstaller.SessionCallback callback)
Deprecated.
|
void |
setPermissionsResult(int sessionId,
boolean accepted) |
void |
uninstall(String packageName,
IntentSender statusReceiver)
Uninstall the given package, removing it completely from the device.
|
void |
unregisterSessionCallback(PackageInstaller.SessionCallback callback)
Unregister a previously registered callback.
|
void |
updateSessionAppIcon(int sessionId,
Bitmap appIcon)
Update the icon representing the app being installed in a specific
session.
|
void |
updateSessionAppLabel(int sessionId,
CharSequence appLabel)
Update the label representing the app being installed in a specific
session.
|
public static final String ACTION_SESSION_DETAILS
This should always be scoped to the installer package that owns the
session. Clients should use PackageInstaller.SessionInfo.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
.
public static final String ACTION_CONFIRM_PERMISSIONS
public static final String EXTRA_SESSION_ID
public static final String EXTRA_PACKAGE_NAME
public static final String EXTRA_STATUS
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.
public static final String EXTRA_STATUS_MESSAGE
public static final String EXTRA_OTHER_PACKAGE_NAME
public static final String EXTRA_STORAGE_PATH
@Deprecated public static final String EXTRA_PACKAGE_NAMES
public static final String EXTRA_LEGACY_STATUS
public static final String EXTRA_LEGACY_BUNDLE
public static final String EXTRA_CALLBACK
public static final int STATUS_PENDING_USER_ACTION
Intent.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.
public static final int STATUS_SUCCESS
public static final int STATUS_FAILURE
EXTRA_STATUS_MESSAGE
,
Constant Field Valuespublic static final int STATUS_FAILURE_BLOCKED
The result may also contain EXTRA_OTHER_PACKAGE_NAME
with the
specific package blocking the install.
public static final int STATUS_FAILURE_ABORTED
EXTRA_STATUS_MESSAGE
,
Constant Field Valuespublic static final int STATUS_FAILURE_INVALID
EXTRA_STATUS_MESSAGE
,
Constant Field Valuespublic static final int STATUS_FAILURE_CONFLICT
The result may also contain EXTRA_OTHER_PACKAGE_NAME
with the
specific package identified as the cause of the conflict.
public static final int STATUS_FAILURE_STORAGE
The result may also contain EXTRA_STORAGE_PATH
with the path to
the storage device that caused the failure.
public static final int STATUS_FAILURE_INCOMPATIBLE
EXTRA_STATUS_MESSAGE
,
Constant Field Valuespublic PackageInstaller(Context context, PackageManager pm, IPackageInstaller installer, String installerPackageName, int userId)
public int createSession(PackageInstaller.SessionParams params) throws IOException
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.public PackageInstaller.Session openSession(int sessionId) throws IOException
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.public void updateSessionAppIcon(int sessionId, Bitmap appIcon)
ActivityManager.getLauncherLargeIconSize()
in both dimensions.SecurityException
- when the caller does not own the session, or
the session is invalid.public void updateSessionAppLabel(int sessionId, CharSequence appLabel)
SecurityException
- when the caller does not own the session, or
the session is invalid.public void abandonSession(int sessionId)
PackageInstaller.SessionCallback
listeners as failures. This is equivalent to
opening the session and calling PackageInstaller.Session.abandon()
.SecurityException
- when the caller does not own the session, or
the session is invalid.public PackageInstaller.SessionInfo getSessionInfo(int sessionId)
null
if the session
does not exist.public List<PackageInstaller.SessionInfo> getAllSessions()
public List<PackageInstaller.SessionInfo> getMySessions()
public void uninstall(String packageName, IntentSender statusReceiver)
public void setPermissionsResult(int sessionId, boolean accepted)
@Deprecated public void addSessionCallback(PackageInstaller.SessionCallback callback)
public void registerSessionCallback(PackageInstaller.SessionCallback callback)
@Deprecated public void addSessionCallback(PackageInstaller.SessionCallback callback, Handler handler)
public void registerSessionCallback(PackageInstaller.SessionCallback callback, Handler handler)
handler
- to dispatch callback events through, otherwise uses
calling thread.@Deprecated public void removeSessionCallback(PackageInstaller.SessionCallback callback)
public void unregisterSessionCallback(PackageInstaller.SessionCallback callback)