1 /*
2  * Copyright (C) 2021 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package android.app.admin;
18 
19 import static java.util.Objects.requireNonNull;
20 
21 import android.annotation.NonNull;
22 import android.annotation.Nullable;
23 import android.annotation.SuppressLint;
24 import android.annotation.TestApi;
25 import android.content.ComponentName;
26 import android.os.Parcel;
27 import android.os.Parcelable;
28 import android.stats.devicepolicy.DevicePolicyEnums;
29 
30 import java.util.Locale;
31 
32 /**
33  * Params required to provision a fully managed device, see
34  * {@link DevicePolicyManager#provisionFullyManagedDevice}.
35  * @hide
36  */
37 @TestApi
38 public final class FullyManagedDeviceProvisioningParams implements Parcelable {
39     private static final String LEAVE_ALL_SYSTEM_APPS_ENABLED_PARAM =
40             "LEAVE_ALL_SYSTEM_APPS_ENABLED";
41     private static final String CAN_DEVICE_OWNER_GRANT_SENSOR_PERMISSIONS_PARAM =
42             "CAN_DEVICE_OWNER_GRANT_SENSOR_PERMISSIONS";
43     private static final String TIME_ZONE_PROVIDED_PARAM = "TIME_ZONE_PROVIDED";
44     private static final String LOCALE_PROVIDED_PARAM = "LOCALE_PROVIDED";
45 
46     @NonNull private final ComponentName mDeviceAdminComponentName;
47     @NonNull private final String mOwnerName;
48     private final boolean mLeaveAllSystemAppsEnabled;
49     @Nullable private final String mTimeZone;
50     private final long mLocalTime;
51     @SuppressLint("UseIcu")
52     @Nullable private final Locale mLocale;
53     private final boolean mDeviceOwnerCanGrantSensorsPermissions;
54 
FullyManagedDeviceProvisioningParams( @onNull ComponentName deviceAdminComponentName, @NonNull String ownerName, boolean leaveAllSystemAppsEnabled, @Nullable String timeZone, long localTime, @Nullable @SuppressLint(R) Locale locale, boolean deviceOwnerCanGrantSensorsPermissions)55     private FullyManagedDeviceProvisioningParams(
56             @NonNull ComponentName deviceAdminComponentName,
57             @NonNull String ownerName,
58             boolean leaveAllSystemAppsEnabled,
59             @Nullable String timeZone,
60             long localTime,
61             @Nullable @SuppressLint("UseIcu") Locale locale,
62             boolean deviceOwnerCanGrantSensorsPermissions) {
63         this.mDeviceAdminComponentName = requireNonNull(deviceAdminComponentName);
64         this.mOwnerName = requireNonNull(ownerName);
65         this.mLeaveAllSystemAppsEnabled = leaveAllSystemAppsEnabled;
66         this.mTimeZone = timeZone;
67         this.mLocalTime = localTime;
68         this.mLocale = locale;
69         this.mDeviceOwnerCanGrantSensorsPermissions =
70                 deviceOwnerCanGrantSensorsPermissions;
71     }
72 
FullyManagedDeviceProvisioningParams( @onNull ComponentName deviceAdminComponentName, @NonNull String ownerName, boolean leaveAllSystemAppsEnabled, @Nullable String timeZone, long localTime, @Nullable String localeStr, boolean deviceOwnerCanGrantSensorsPermissions)73     private FullyManagedDeviceProvisioningParams(
74             @NonNull ComponentName deviceAdminComponentName,
75             @NonNull String ownerName,
76             boolean leaveAllSystemAppsEnabled,
77             @Nullable String timeZone,
78             long localTime,
79             @Nullable String localeStr,
80             boolean deviceOwnerCanGrantSensorsPermissions) {
81         this(deviceAdminComponentName,
82                 ownerName,
83                 leaveAllSystemAppsEnabled,
84                 timeZone,
85                 localTime,
86                 getLocale(localeStr),
87                 deviceOwnerCanGrantSensorsPermissions);
88     }
89 
90     @Nullable
getLocale(String localeStr)91     private static Locale getLocale(String localeStr) {
92         return localeStr == null ? null : Locale.forLanguageTag(localeStr);
93     }
94 
95     @NonNull
getDeviceAdminComponentName()96     public ComponentName getDeviceAdminComponentName() {
97         return mDeviceAdminComponentName;
98     }
99 
100     @NonNull
getOwnerName()101     public String getOwnerName() {
102         return mOwnerName;
103     }
104 
isLeaveAllSystemAppsEnabled()105     public boolean isLeaveAllSystemAppsEnabled() {
106         return mLeaveAllSystemAppsEnabled;
107     }
108 
109     @Nullable
getTimeZone()110     public String getTimeZone() {
111         return mTimeZone;
112     }
113 
getLocalTime()114     public long getLocalTime() {
115         return mLocalTime;
116     }
117 
118     @Nullable
getLocale()119     public @SuppressLint("UseIcu") Locale getLocale() {
120         return mLocale;
121     }
122 
123     /**
124      * @return true if the device owner can control sensor-related permission grants, false
125      * if the device owner has opted out of it.
126      */
canDeviceOwnerGrantSensorsPermissions()127     public boolean canDeviceOwnerGrantSensorsPermissions() {
128         return mDeviceOwnerCanGrantSensorsPermissions;
129     }
130 
131     /**
132      * Logs the provisioning params using {@link DevicePolicyEventLogger}.
133      */
logParams(@onNull String callerPackage)134     public void logParams(@NonNull String callerPackage) {
135         requireNonNull(callerPackage);
136 
137         logParam(callerPackage, LEAVE_ALL_SYSTEM_APPS_ENABLED_PARAM, mLeaveAllSystemAppsEnabled);
138         logParam(callerPackage, CAN_DEVICE_OWNER_GRANT_SENSOR_PERMISSIONS_PARAM,
139                 mDeviceOwnerCanGrantSensorsPermissions);
140         logParam(callerPackage, TIME_ZONE_PROVIDED_PARAM, /* value= */ mTimeZone != null);
141         logParam(callerPackage, LOCALE_PROVIDED_PARAM, /* value= */ mLocale != null);
142     }
143 
logParam(String callerPackage, String param, boolean value)144     private void logParam(String callerPackage, String param, boolean value) {
145         DevicePolicyEventLogger
146                 .createEvent(DevicePolicyEnums.PLATFORM_PROVISIONING_PARAM)
147                 .setStrings(callerPackage)
148                 .setAdmin(mDeviceAdminComponentName)
149                 .setStrings(param)
150                 .setBoolean(value)
151                 .write();
152     }
153 
154     /**
155      * Builder class for {@link FullyManagedDeviceProvisioningParams} objects.
156      */
157     public static final class Builder {
158         @NonNull private final ComponentName mDeviceAdminComponentName;
159         @NonNull private final String mOwnerName;
160         private boolean mLeaveAllSystemAppsEnabled;
161         @Nullable private String mTimeZone;
162         private long mLocalTime;
163         @SuppressLint("UseIcu")
164         @Nullable private Locale mLocale;
165         // Default to allowing control over sensor permission grants.
166         boolean mDeviceOwnerCanGrantSensorsPermissions = true;
167 
168         /**
169          * Initialize a new {@link Builder} to construct a
170          * {@link FullyManagedDeviceProvisioningParams}.
171          * <p>
172          * See {@link DevicePolicyManager#provisionFullyManagedDevice}
173          *
174          * @param deviceAdminComponentName The admin {@link ComponentName} to be set as the device
175          * owner.
176          * @param ownerName The name of the device owner.
177          *
178          * @throws NullPointerException if {@code deviceAdminComponentName} or
179          * {@code ownerName} are null.
180          */
Builder( @onNull ComponentName deviceAdminComponentName, @NonNull String ownerName)181         public Builder(
182                 @NonNull ComponentName deviceAdminComponentName, @NonNull String ownerName) {
183             this.mDeviceAdminComponentName = requireNonNull(deviceAdminComponentName);
184             this.mOwnerName = requireNonNull(ownerName);
185         }
186 
187         /**
188          * Sets whether non-required system apps should be installed on
189          * the created profile when
190          * {@link DevicePolicyManager#provisionFullyManagedDevice}
191          * is called. Defaults to {@code false} if not set.
192          */
193         @NonNull
setLeaveAllSystemAppsEnabled(boolean leaveAllSystemAppsEnabled)194         public Builder setLeaveAllSystemAppsEnabled(boolean leaveAllSystemAppsEnabled) {
195             this.mLeaveAllSystemAppsEnabled = leaveAllSystemAppsEnabled;
196             return this;
197         }
198 
199         /**
200          * Sets {@code timeZone} on the device. If not set or set to {@code null},
201          * {@link DevicePolicyManager#provisionFullyManagedDevice} will not set a timezone
202          */
203         @NonNull
setTimeZone(@ullable String timeZone)204         public Builder setTimeZone(@Nullable String timeZone) {
205             this.mTimeZone = timeZone;
206             return this;
207         }
208 
209         /**
210          * Sets {@code localTime} on the device, If not set or set to
211          * {@code 0}, {@link DevicePolicyManager#provisionFullyManagedDevice} will not set a
212          * local time.
213          */
214         @NonNull
setLocalTime(long localTime)215         public Builder setLocalTime(long localTime) {
216             this.mLocalTime = localTime;
217             return this;
218         }
219 
220         /**
221          * Sets {@link Locale} on the device, If not set or set to {@code null},
222          * {@link DevicePolicyManager#provisionFullyManagedDevice} will not set a locale.
223          */
224         @NonNull
setLocale(@uppressLintR) @ullable Locale locale)225         public Builder setLocale(@SuppressLint("UseIcu") @Nullable Locale locale) {
226             this.mLocale = locale;
227             return this;
228         }
229 
230         /**
231          * Marks that the Device Owner may grant permissions related to device sensors.
232          * See {@link DevicePolicyManager#EXTRA_PROVISIONING_SENSORS_PERMISSION_GRANT_OPT_OUT}.
233          */
234         @NonNull
235         @SuppressLint("MissingGetterMatchingBuilder")
setDeviceOwnerCanGrantSensorsPermissions(boolean mayGrant)236         public Builder setDeviceOwnerCanGrantSensorsPermissions(boolean mayGrant) {
237             mDeviceOwnerCanGrantSensorsPermissions = mayGrant;
238             return this;
239         }
240 
241         /**
242          * Combines all of the attributes that have been set on this {@code Builder}
243          *
244          * @return a new {@link FullyManagedDeviceProvisioningParams} object.
245          */
246         @NonNull
build()247         public FullyManagedDeviceProvisioningParams build() {
248             return new FullyManagedDeviceProvisioningParams(
249                     mDeviceAdminComponentName,
250                     mOwnerName,
251                     mLeaveAllSystemAppsEnabled,
252                     mTimeZone,
253                     mLocalTime,
254                     mLocale,
255                     mDeviceOwnerCanGrantSensorsPermissions);
256         }
257     }
258 
259     @Override
describeContents()260     public int describeContents() {
261         return 0;
262     }
263 
264     @Override
toString()265     public String toString() {
266         return "FullyManagedDeviceProvisioningParams{"
267                 + "mDeviceAdminComponentName=" + mDeviceAdminComponentName
268                 + ", mOwnerName=" + mOwnerName
269                 + ", mLeaveAllSystemAppsEnabled=" + mLeaveAllSystemAppsEnabled
270                 + ", mTimeZone=" + (mTimeZone == null ? "null" : mTimeZone)
271                 + ", mLocalTime=" + mLocalTime
272                 + ", mLocale=" + (mLocale == null ? "null" : mLocale)
273                 + ", mDeviceOwnerCanGrantSensorsPermissions="
274                 + mDeviceOwnerCanGrantSensorsPermissions
275                 + '}';
276     }
277 
278     @Override
writeToParcel(@onNull Parcel dest, @Nullable int flags)279     public void writeToParcel(@NonNull Parcel dest, @Nullable int flags) {
280         dest.writeTypedObject(mDeviceAdminComponentName, flags);
281         dest.writeString(mOwnerName);
282         dest.writeBoolean(mLeaveAllSystemAppsEnabled);
283         dest.writeString(mTimeZone);
284         dest.writeLong(mLocalTime);
285         dest.writeString(mLocale == null ? null : mLocale.toLanguageTag());
286         dest.writeBoolean(mDeviceOwnerCanGrantSensorsPermissions);
287     }
288 
289     @NonNull
290     public static final Creator<FullyManagedDeviceProvisioningParams> CREATOR =
291             new Creator<FullyManagedDeviceProvisioningParams>() {
292                 @Override
293                 public FullyManagedDeviceProvisioningParams createFromParcel(Parcel in) {
294                     ComponentName componentName = in.readTypedObject(ComponentName.CREATOR);
295                     String ownerName = in.readString();
296                     boolean leaveAllSystemAppsEnabled = in.readBoolean();
297                     String timeZone = in.readString();
298                     long localtime = in.readLong();
299                     String locale = in.readString();
300                     boolean deviceOwnerCanGrantSensorsPermissions = in.readBoolean();
301 
302                     return new FullyManagedDeviceProvisioningParams(
303                             componentName,
304                             ownerName,
305                             leaveAllSystemAppsEnabled,
306                             timeZone,
307                             localtime,
308                             locale,
309                             deviceOwnerCanGrantSensorsPermissions);
310                 }
311 
312                 @Override
313                 public FullyManagedDeviceProvisioningParams[] newArray(int size) {
314                     return new FullyManagedDeviceProvisioningParams[size];
315                 }
316             };
317 }
318