SystemUpdatePolicy

public final class SystemUpdatePolicy
extends Object implements Parcelable

java.lang.Object
   ↳ android.app.admin.SystemUpdatePolicy


Determines when over-the-air system updates are installed on a device. Only a device policy controller (DPC) running in device owner mode can set an update policy for the device—by calling the DevicePolicyManager method setSystemUpdatePolicy(). An update policy affects the pending system update (if there is one) and any future updates for the device.

If a policy is set on a device, the system doesn't notify the user about updates.

Example

The example below shows how a DPC might set a maintenance window for system updates:


 private final MAINTENANCE_WINDOW_START = 1380; // 11pm
 private final MAINTENANCE_WINDOW_END = 120; // 2am

 // ...

 // Create the system update policy
 SystemUpdatePolicy policy = SystemUpdatePolicy.createWindowedInstallPolicy(
     MAINTENANCE_WINDOW_START, MAINTENANCE_WINDOW_END);

 // Get a DevicePolicyManager instance to set the policy on the device
 DevicePolicyManager dpm =
     (DevicePolicyManager) context.getSystemService(Context.DEVICE_POLICY_SERVICE);
 ComponentName adminComponent = getComponentName(context);
 dpm.setSystemUpdatePolicy(adminComponent, policy);
 

Developer guide

To learn more, read Manage system updates.

Summary

Nested classes

class SystemUpdatePolicy.ValidationFailedException

An exception class that represents various validation errors thrown from SystemUpdatePolicy.setFreezePeriods(List) and DevicePolicyManager.setSystemUpdatePolicy(ComponentName, SystemUpdatePolicy)  

Constants

int TYPE_INSTALL_AUTOMATIC

Installs system updates (without user interaction) as soon as they become available.

int TYPE_INSTALL_WINDOWED

Installs system updates (without user interaction) during a daily maintenance window.

int TYPE_POSTPONE

Postpones the installation of system updates for 30 days.

Inherited constants

Fields

public static final Creator<SystemUpdatePolicy> CREATOR

Public methods

static SystemUpdatePolicy createAutomaticInstallPolicy()

Create a policy object and set it to install update automatically as soon as one is available.

static SystemUpdatePolicy createPostponeInstallPolicy()

Create a policy object and set it to block installation for a maximum period of 30 days.

static SystemUpdatePolicy createWindowedInstallPolicy(int startTime, int endTime)

Create a policy object and set it to: new system update will only be installed automatically when the system clock is inside a daily maintenance window.

int describeContents()

Describe the kinds of special objects contained in this Parcelable instance's marshaled representation.

List<FreezePeriod> getFreezePeriods()

Returns the list of freeze periods previously set on this system update policy object.

int getInstallWindowEnd()

Get the end of the maintenance window.

int getInstallWindowStart()

Get the start of the maintenance window.

int getPolicyType()

Returns the type of system update policy, or -1 if no policy has been set.

SystemUpdatePolicy setFreezePeriods(List<FreezePeriod> freezePeriods)

Configure a list of freeze periods on top of the current policy.

String toString()

Returns a string representation of the object.

void writeToParcel(Parcel dest, int flags)

Flatten this object in to a Parcel.

Inherited methods

Constants

TYPE_INSTALL_AUTOMATIC

added in API level 23
public static final int TYPE_INSTALL_AUTOMATIC

Installs system updates (without user interaction) as soon as they become available. Setting this policy type immediately installs any pending updates that might be postponed or waiting for a maintenance window.

Constant Value: 1 (0x00000001)

TYPE_INSTALL_WINDOWED

added in API level 23
public static final int TYPE_INSTALL_WINDOWED

Installs system updates (without user interaction) during a daily maintenance window. Set the start and end of the daily maintenance window, as minutes of the day, when creating a new TYPE_INSTALL_WINDOWED policy. See createWindowedInstallPolicy().

No connectivity, not enough disk space, or a low battery are typical reasons Android might not install a system update in the daily maintenance window. After 30 days trying to install an update in the maintenance window (regardless of policy changes in this period), the system prompts the device user to install the update.

Constant Value: 2 (0x00000002)

TYPE_POSTPONE

added in API level 23
public static final int TYPE_POSTPONE

Postpones the installation of system updates for 30 days. After the 30-day period has ended, the system prompts the device user to install the update.

The system limits each update to one 30-day postponement. The period begins when the system first postpones the update and setting new TYPE_POSTPONE policies won’t extend the period. If, after 30 days the update isn’t installed (through policy changes), the system prompts the user to install the update.

Note: Device manufacturers or carriers might choose to exempt important security updates from a postponement policy. Exempted updates notify the device user when they become available.

Constant Value: 3 (0x00000003)

Fields

CREATOR

added in API level 23
public static final Creator<SystemUpdatePolicy> CREATOR

Public methods

createAutomaticInstallPolicy

added in API level 23
public static SystemUpdatePolicy createAutomaticInstallPolicy ()

Create a policy object and set it to install update automatically as soon as one is available.

Returns
SystemUpdatePolicy

createPostponeInstallPolicy

added in API level 23
public static SystemUpdatePolicy createPostponeInstallPolicy ()

Create a policy object and set it to block installation for a maximum period of 30 days. To learn more about this policy's behavior, see TYPE_POSTPONE.

Note: security updates (e.g. monthly security patches) will not be affected by this policy.

Returns
SystemUpdatePolicy

See also:

createWindowedInstallPolicy

added in API level 23
public static SystemUpdatePolicy createWindowedInstallPolicy (int startTime, 
                int endTime)

Create a policy object and set it to: new system update will only be installed automatically when the system clock is inside a daily maintenance window. If the start and end times are the same, the window is considered to include the whole 24 hours. That is, updates can install at any time. If start time is later than end time, the window is considered spanning midnight (i.e. the end time denotes a time on the next day). The maintenance window will last for 30 days for any given update, after which the window will no longer be effective and the pending update will be made available for manual installation as if no system update policy were set on the device. See TYPE_INSTALL_WINDOWED for the details of this policy's behavior.

Parameters
startTime int: the start of the maintenance window, measured as the number of minutes from midnight in the device's local time. Must be in the range of [0, 1440).

endTime int: the end of the maintenance window, measured as the number of minutes from midnight in the device's local time. Must be in the range of [0, 1440).

Returns
SystemUpdatePolicy The configured policy.

Throws
IllegalArgumentException If the startTime or endTime isn't in the accepted range.

describeContents

added in API level 23
public int describeContents ()

Describe the kinds of special objects contained in this Parcelable instance's marshaled representation. For example, if the object will include a file descriptor in the output of writeToParcel(Parcel, int), the return value of this method must include the CONTENTS_FILE_DESCRIPTOR bit.

Returns
int a bitmask indicating the set of special object types marshaled by this Parcelable object instance.

getFreezePeriods

added in API level 28
public List<FreezePeriod> getFreezePeriods ()

Returns the list of freeze periods previously set on this system update policy object.

Returns
List<FreezePeriod> the list of freeze periods, or an empty list if none was set.

getInstallWindowEnd

added in API level 23
public int getInstallWindowEnd ()

Get the end of the maintenance window.

Returns
int the end of the maintenance window measured as the number of minutes from midnight, or -1 if the policy does not have a maintenance window.

getInstallWindowStart

added in API level 23
public int getInstallWindowStart ()

Get the start of the maintenance window.

Returns
int the start of the maintenance window measured as the number of minutes from midnight, or -1 if the policy does not have a maintenance window.

getPolicyType

added in API level 23
public int getPolicyType ()

Returns the type of system update policy, or -1 if no policy has been set.

Returns
int The policy type or -1 if the type isn't set.

Value is TYPE_INSTALL_AUTOMATIC, TYPE_INSTALL_WINDOWED or TYPE_POSTPONE.

setFreezePeriods

added in API level 28
public SystemUpdatePolicy setFreezePeriods (List<FreezePeriod> freezePeriods)

Configure a list of freeze periods on top of the current policy. When the device's clock is within any of the freeze periods, all incoming system updates including security patches will be blocked and cannot be installed. When the device is outside the freeze periods, the normal policy behavior will apply.

Each individual freeze period is allowed to be at most 90 days long, and adjacent freeze periods need to be at least 60 days apart. Also, the list of freeze periods should not contain duplicates or overlap with each other. If any of these conditions is not met, a SystemUpdatePolicy.ValidationFailedException will be thrown.

Handling of leap year: we ignore leap years in freeze period calculations, in particular,

  • When a freeze period is defined, February 29th is disregarded so even though a freeze period can be specified to start or end on February 29th, it will be treated as if the period started or ended on February 28th.
  • When applying freeze period behavior to the device, a system clock of February 29th is treated as if it were February 28th
  • When calculating the number of days of a freeze period or separation between two freeze periods, February 29th is also ignored and not counted as one day.

Parameters
freezePeriods List: the list of freeze periods

Returns
SystemUpdatePolicy this instance

Throws
SystemUpdatePolicy.ValidationFailedException if the supplied freeze periods do not meet the requirement set above

toString

added in API level 23
public String toString ()

Returns a string representation of the object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method.

The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of:

 getClass().getName() + '@' + Integer.toHexString(hashCode())
 

Returns
String a string representation of the object.

writeToParcel

added in API level 23
public void writeToParcel (Parcel dest, 
                int flags)

Flatten this object in to a Parcel.

Parameters
dest Parcel: The Parcel in which the object should be written.

flags int: Additional flags about how the object should be written. May be 0 or Parcelable.PARCELABLE_WRITE_RETURN_VALUE.