SessionParams
open class SessionParams : Parcelable
kotlin.Any | |
↳ | android.content.pm.PackageInstaller.SessionParams |
Parameters for creating a new PackageInstaller.Session
.
Summary
Constants | |
---|---|
static Int |
Mode for an install session whose staged APKs should fully replace any existing APKs for the target app. |
static Int |
Mode for an install session that should inherit any existing APKs for the target app, unless they have been explicitly overridden (based on split name) by the session. |
static Int |
Value is passed by the installer to |
static Int |
Value is passed by the installer to |
static Int |
Value is passed by the installer to |
static Int |
This value is passed by the installer to |
static Int |
This value is passed by the installer to |
static Int |
This value is passed by the installer to |
Inherited constants | |
---|---|
Public constructors | |
---|---|
SessionParams(mode: Int) Construct parameters for a new package install session. |
Public methods | |
---|---|
open Int | |
open Unit |
setAppIcon(appIcon: Bitmap?) Optionally set an icon representing the app being installed. |
open Unit |
setAppLabel(appLabel: CharSequence?) Optionally set a label representing the app being installed. |
open Unit |
setAppPackageName(appPackageName: String?) Optionally set the package name of the app being installed. |
open Unit |
Request to keep the original application enabled setting. |
open Unit |
setAutoRevokePermissionsMode(shouldAutoRevoke: Boolean) Sets whether permissions should be auto-revoked if this package is unused for an extended periodd of time. |
open Unit |
setDontKillApp(dontKillApp: Boolean) Requests that the system not kill any of the package's running processes as part of a |
open Unit |
setInstallLocation(installLocation: Int) Provide value of |
open Unit |
setInstallReason(installReason: Int) Set the reason for installing this package. |
open Unit |
setInstallScenario(installScenario: Int) Sets the install scenario for this session, which describes the expected user journey. |
open Unit |
setInstallerPackageName(installerPackageName: String?) Set the installer package for the app. |
open Unit |
Set this session to be the parent of a multi-package install. |
open Unit |
setOriginatingUid(originatingUid: Int) Sets the UID that initiated the package installation. |
open Unit |
setOriginatingUri(originatingUri: Uri?) Optionally set the URI where this package was downloaded from. |
open Unit |
setPackageSource(packageSource: Int) Optionally indicate the package source of the app being installed. |
open PackageInstaller.SessionParams |
setPermissionState(permissionName: String, state: Int) Sets the state of permissions for the package at installation. |
open Unit |
setReferrerUri(referrerUri: Uri?) Optionally set the URI that referred you to install this package. |
open Unit |
setRequestUpdateOwnership(enable: Boolean) Optionally indicate whether the package being installed needs the update ownership enforcement. |
open Unit |
setRequireUserAction(requireUserAction: Int) Optionally indicate whether user action should be required when the session is committed. |
open Unit |
Optionally indicate the total size (in bytes) of all APKs that will be delivered in this session. |
open Unit |
setUnarchiveId(unarchiveId: Int) Used to set the unarchive ID received as part of an |
open Unit |
setWhitelistedRestrictedPermissions(permissions: MutableSet<String!>?) Sets which restricted permissions to be allowlisted for the app. |
open Unit |
writeToParcel(dest: Parcel, flags: Int) |
Properties | |
---|---|
static Parcelable.Creator<PackageInstaller.SessionParams!>! | |
static MutableSet<String!> |
Special constant to refer to all restricted permissions. |
Constants
MODE_FULL_INSTALL
static val MODE_FULL_INSTALL: Int
Mode for an install session whose staged APKs should fully replace any existing APKs for the target app.
Value: 1
MODE_INHERIT_EXISTING
static val MODE_INHERIT_EXISTING: Int
Mode for an install session that should inherit any existing APKs for the target app, unless they have been explicitly overridden (based on split name) by the session. For example, this can be used to add one or more split APKs to an existing installation.
If there are no existing APKs for the target app, this behaves like MODE_FULL_INSTALL
.
Value: 2
PERMISSION_STATE_DEFAULT
static val PERMISSION_STATE_DEFAULT: Int
Value is passed by the installer to setPermissionState(java.lang.String,int)
to set the state of a permission. This indicates no preference by the installer, relying on the device's default policy to set the grant state of the permission.
Value: 0
PERMISSION_STATE_DENIED
static val PERMISSION_STATE_DENIED: Int
Value is passed by the installer to setPermissionState(java.lang.String,int)
to set the state of a permission. This indicates the installers wants to deny the permission by default to the package being installed. The user and other actors in the system may still be able to grant the permission after installation.
Value: 2
PERMISSION_STATE_GRANTED
static val PERMISSION_STATE_GRANTED: Int
Value is passed by the installer to setPermissionState(java.lang.String,int)
to set the state of a permission. This indicates the installers wants to automatically grant the permission to the package being installed. The user and other actors in the system may still be able to deny the permission after installation.
Value: 1
USER_ACTION_NOT_REQUIRED
static val USER_ACTION_NOT_REQUIRED: Int
This value is passed by the installer to SessionParams#setRequireUserAction(int)
to indicate that user action is not required for this install.
Value: 2
USER_ACTION_REQUIRED
static val USER_ACTION_REQUIRED: Int
This value is passed by the installer to SessionParams#setRequireUserAction(int)
to indicate that user action is required for this install.
Value: 1
USER_ACTION_UNSPECIFIED
static val USER_ACTION_UNSPECIFIED: Int
This value is passed by the installer to SessionParams#setRequireUserAction(int)
to indicate that user action is unspecified for this install. requireUserAction
also defaults to this value unless modified by SessionParams#setRequireUserAction(int)
Value: 0
Public constructors
SessionParams
SessionParams(mode: Int)
Construct parameters for a new package install session.
Parameters | |
---|---|
mode |
Int: one of MODE_FULL_INSTALL or MODE_INHERIT_EXISTING describing how the session should interact with an existing app. |
Public methods
describeContents
open fun describeContents(): Int
Return | |
---|---|
Int |
a bitmask indicating the set of special object types marshaled by this Parcelable object instance. Value is either 0 or android.os.Parcelable#CONTENTS_FILE_DESCRIPTOR |
setAppIcon
open fun setAppIcon(appIcon: Bitmap?): Unit
Optionally set an icon representing the app being installed. This should be roughly ActivityManager#getLauncherLargeIconSize()
in both dimensions.
Parameters | |
---|---|
appIcon |
Bitmap?: This value may be null . |
setAppLabel
open fun setAppLabel(appLabel: CharSequence?): Unit
Optionally set a label representing the app being installed. This value will be trimmed to the first 1000 characters.
Parameters | |
---|---|
appLabel |
CharSequence?: This value may be null . |
setAppPackageName
open fun setAppPackageName(appPackageName: String?): Unit
Optionally set the package name of the app being installed. It's strongly recommended that you provide this value when known, so that observers can communicate installing apps to users.
If the APKs staged in the session aren't consistent with this package name, the install will fail. Regardless of this value, all APKs in the app must have the same package name.
Parameters | |
---|---|
appPackageName |
String?: This value may be null . |
setApplicationEnabledSettingPersistent
open fun setApplicationEnabledSettingPersistent(): Unit
Request to keep the original application enabled setting. This will prevent the application from being enabled if it was previously in a disabled state.
setAutoRevokePermissionsMode
open funsetAutoRevokePermissionsMode(shouldAutoRevoke: Boolean): Unit
Deprecated: No longer used
Sets whether permissions should be auto-revoked if this package is unused for an extended periodd of time. It's disabled by default but generally the installer should enable it for most packages, excluding only those where doing so might cause breakage that cannot be easily addressed by simply re-requesting the permission(s). If user explicitly enabled or disabled it via settings, this call is ignored.
Parameters | |
---|---|
shouldAutoRevoke |
Boolean: whether permissions should be auto-revoked. |
setDontKillApp
open fun setDontKillApp(dontKillApp: Boolean): Unit
Requests that the system not kill any of the package's running processes as part of a SessionParams#MODE_INHERIT_EXISTING
session in which splits being added. By default, all installs will result in the package's running processes being killed before the install completes.
Parameters | |
---|---|
dontKillApp |
Boolean: set to true to request that the processes belonging to the package not be killed as part of this install. |
setInstallLocation
open fun setInstallLocation(installLocation: Int): Unit
Provide value of PackageInfo#installLocation
, which may be used to determine where the app will be staged. Defaults to PackageInfo#INSTALL_LOCATION_INTERNAL_ONLY
.
setInstallReason
open fun setInstallReason(installReason: Int): Unit
Set the reason for installing this package.
The install reason should be a pre-defined integer. The behavior is undefined if other values are used.
Parameters | |
---|---|
installReason |
Int: Value is android.content.pm.PackageManager#INSTALL_REASON_UNKNOWN , android.content.pm.PackageManager#INSTALL_REASON_POLICY , android.content.pm.PackageManager#INSTALL_REASON_DEVICE_RESTORE , android.content.pm.PackageManager#INSTALL_REASON_DEVICE_SETUP , android.content.pm.PackageManager#INSTALL_REASON_USER , or android.content.pm.PackageManager.INSTALL_REASON_ROLLBACK |
See Also
setInstallScenario
open fun setInstallScenario(installScenario: Int): Unit
Sets the install scenario for this session, which describes the expected user journey.
setInstallerPackageName
open fun setInstallerPackageName(installerPackageName: String?): Unit
Set the installer package for the app. By default this is the app that created the PackageInstaller
object. Note: Only applications with android.Manifest.permission#INSTALL_PACKAGES
permission are allowed to set an installer that is not the caller's own installer package name, otherwise it will cause a SecurityException
when creating the install session.
Parameters | |
---|---|
installerPackageName |
String?: The name of the installer package, its length must be less than 255 , otherwise it will be invalid. This value may be null . |
setMultiPackage
open fun setMultiPackage(): Unit
Set this session to be the parent of a multi-package install. A multi-package install session contains no APKs and only references other install sessions via ID. When a multi-package session is committed, all of its children are committed to the system in an atomic manner. If any children fail to install, all of them do, including the multi-package session.
setOriginatingUid
open fun setOriginatingUid(originatingUid: Int): Unit
Sets the UID that initiated the package installation. This is informational and may be used as a signal for anti-malware purposes.
setOriginatingUri
open fun setOriginatingUri(originatingUri: Uri?): Unit
Optionally set the URI where this package was downloaded from. This is informational and may be used as a signal for anti-malware purposes.
Parameters | |
---|---|
originatingUri |
Uri?: This value may be null . |
setPackageSource
open fun setPackageSource(packageSource: Int): Unit
Optionally indicate the package source of the app being installed. This is informational and may be used as a signal by the system. An installer should specify PACKAGE_SOURCE_OTHER
if no other package source constant adequately reflects the source for this session. The default value is PACKAGE_SOURCE_UNSPECIFIED
.
setPermissionState
open fun setPermissionState(
permissionName: String,
state: Int
): PackageInstaller.SessionParams
Sets the state of permissions for the package at installation.
Granting any runtime permissions require theandroid.Manifest.permission#INSTALL_GRANT_RUNTIME_PERMISSIONS
permission to be held by the caller. Revoking runtime permissions is not allowed, even during app update sessions.
Holders without the permission are allowed to change the following special permissions:
On platform UPSIDE_DOWN_CAKE
:
Install time permissions, which cannot be revoked by the user, cannot be changed by the installer.
See Permissions on Android for more information.
Parameters | |
---|---|
permissionName |
String: The permission to change state for. This value cannot be null . |
state |
Int: Either PERMISSION_STATE_DEFAULT , PERMISSION_STATE_GRANTED , or PERMISSION_STATE_DENIED to set the permission to. Value is android.content.pm.PackageInstaller.SessionParams#PERMISSION_STATE_DEFAULT , android.content.pm.PackageInstaller.SessionParams#PERMISSION_STATE_GRANTED , or android.content.pm.PackageInstaller.SessionParams#PERMISSION_STATE_DENIED |
Return | |
---|---|
PackageInstaller.SessionParams |
This object for easier chaining. This value cannot be null . |
setReferrerUri
open fun setReferrerUri(referrerUri: Uri?): Unit
Optionally set the URI that referred you to install this package. This is informational and may be used as a signal for anti-malware purposes.
Parameters | |
---|---|
referrerUri |
Uri?: This value may be null . |
setRequestUpdateOwnership
open fun setRequestUpdateOwnership(enable: Boolean): Unit
Optionally indicate whether the package being installed needs the update ownership enforcement. Once the update ownership enforcement is enabled, the other installers will need the user action to update the package even if the installers have been granted the INSTALL_PACKAGES
permission. Default to false
. The update ownership enforcement can only be enabled on initial installation. Set this to true
on package update is a no-op. Note: To enable the update ownership enforcement, the installer must have the ENFORCE_UPDATE_OWNERSHIP
permission.
Requires android.Manifest.permission#ENFORCE_UPDATE_OWNERSHIP
setRequireUserAction
open fun setRequireUserAction(requireUserAction: Int): Unit
Optionally indicate whether user action should be required when the session is committed.
Defaults to USER_ACTION_UNSPECIFIED
unless otherwise set. When unspecified for installers using the REQUEST_INSTALL_PACKAGES
permission will behave as if set to USER_ACTION_REQUIRED
, and USER_ACTION_NOT_REQUIRED
otherwise. When requireUserAction
is set to USER_ACTION_REQUIRED
, installers will receive a STATUS_PENDING_USER_ACTION
callback once the session is committed, indicating that user action is required for the install to proceed.
For installers that have been granted the REQUEST_INSTALL_PACKAGES
permission, user action will not be required when all of the following conditions are met:
requireUserAction
is set toUSER_ACTION_NOT_REQUIRED
.- The app being installed targets:
- The installer is:
- The
update owner
of an existing version of the app (in other words, this install session is an app update) if the update ownership enforcement is enabled. - The
installer of record
of an existing version of the app (in other words, this install session is an app update) if the update ownership enforcement isn't enabled. - Updating itself.
- The
- The installer declares the
UPDATE_PACKAGES_WITHOUT_USER_ACTION
permission.
Note: The target API level requirement will advance in future Android versions. Session owners should always be prepared to handle STATUS_PENDING_USER_ACTION
.
Parameters | |
---|---|
requireUserAction |
Int: whether user action should be required. Value is android.content.pm.PackageInstaller.SessionParams#USER_ACTION_UNSPECIFIED , android.content.pm.PackageInstaller.SessionParams#USER_ACTION_REQUIRED , or android.content.pm.PackageInstaller.SessionParams#USER_ACTION_NOT_REQUIRED |
setSize
open fun setSize(sizeBytes: Long): Unit
Optionally indicate the total size (in bytes) of all APKs that will be delivered in this session. The system may use this to ensure enough disk space exists before proceeding, or to estimate container size for installations living on external storage.
setUnarchiveId
open fun setUnarchiveId(unarchiveId: Int): Unit
Used to set the unarchive ID received as part of an Intent#ACTION_UNARCHIVE_PACKAGE
.
The ID should be retrieved from the unarchive intent and passed into the session that's being created to unarchive the app in question. Used to link the unarchive intent and the install session to disambiguate.
setWhitelistedRestrictedPermissions
open fun setWhitelistedRestrictedPermissions(permissions: MutableSet<String!>?): Unit
Sets which restricted permissions to be allowlisted for the app. Allowlisting is not granting the permissions, rather it allows the app to hold permissions which are otherwise restricted. Allowlisting a non restricted permission has no effect.
Permissions can be hard restricted which means that the app cannot hold them or soft restricted where the app can hold the permission but in a weaker form. Whether a permission is restricted
or soft restricted
depends on the permission declaration. Allowlisting a hard restricted permission allows the app to hold that permission and allowlisting a soft restricted permission allows the app to hold the permission in its full, unrestricted form.
Permissions can also be immutably restricted which means that the allowlist state of the permission can be determined only at install time and cannot be changed on updated or at a later point via the package manager APIs.
Initially, all restricted permissions are allowlisted but you can change which ones are allowlisted by calling this method or the corresponding ones on the PackageManager
. Only soft or hard restricted permissions on the current Android version are supported and any invalid entries will be removed.
Parameters | |
---|---|
permissions |
MutableSet<String!>?: This value may be null . |
writeToParcel
open fun writeToParcel(
dest: Parcel,
flags: Int
): Unit
Parameters | |
---|---|
dest |
Parcel: The Parcel in which the object should be written. This value cannot be null . |
flags |
Int: Additional flags about how the object should be written. May be 0 or PARCELABLE_WRITE_RETURN_VALUE . Value is either 0 or a combination of android.os.Parcelable#PARCELABLE_WRITE_RETURN_VALUE , and android.os.Parcelable.PARCELABLE_ELIDE_DUPLICATES |
Properties
CREATOR
static val CREATOR: Parcelable.Creator<PackageInstaller.SessionParams!>!
RESTRICTED_PERMISSIONS_ALL
static val RESTRICTED_PERMISSIONS_ALL: MutableSet<String!>
Special constant to refer to all restricted permissions.