From 16e9a9c3a884075960618919d0a10f4fcd63b386 Mon Sep 17 00:00:00 2001 From: Neil Fuller Date: Wed, 7 Apr 2021 15:51:34 +0100 Subject: [PATCH] Improve / fix docs This is a docs-only change to improve System API javadocs (TimeZoneProviderService) and track some command line changes from an earlier commit (LocationTimeZoneManagerService). Bug: 175718363 Test: build only Change-Id: I255cf064d62a0fb4bb54a407877d4ab3d33ec311 --- .../timezone/TimeZoneProviderService.java | 61 +++++++++++-------- .../LocationTimeZoneManagerService.java | 10 +-- 2 files changed, 38 insertions(+), 33 deletions(-) diff --git a/core/java/android/service/timezone/TimeZoneProviderService.java b/core/java/android/service/timezone/TimeZoneProviderService.java index a9348c68165d6..a2b22e8d8a7af 100644 --- a/core/java/android/service/timezone/TimeZoneProviderService.java +++ b/core/java/android/service/timezone/TimeZoneProviderService.java @@ -50,35 +50,49 @@ import java.util.Objects; * *

Once stopped or failed, providers are required to stop generating callbacks. * - *

Provider discovery: - * - *

You must declare the service in your manifest file with the - * {@link android.Manifest.permission#BIND_TIME_ZONE_PROVIDER_SERVICE} permission, - * and include an intent filter with the necessary action indicating what type of provider it is. - * - *

Device configuration can influence how {@link TimeZoneProviderService}s are discovered. - * In one mode, there can be multiple {@link TimeZoneProviderService}s configured with the same - * action, and the one with the highest "serviceVersion" metadata will be used. - * - *

{@link TimeZoneProviderService}s may be deployed into processes that run once-per-user - * or once-per-device (i.e. they service multiple users). The "serviceIsMultiuser" metadata must - * be set accordingly. - * *

Provider types: * *

Android supports up to two location-derived time zone providers. These are called the - * "primary" and "secondary" location time zone provider. The primary location time zone provider is - * started first and will be used until it becomes uncertain or fails, at which point the secondary - * provider will be started. + * "primary" and "secondary" location time zone providers. When a location-derived time zone is + * required, the primary location time zone provider is started first and used until it becomes + * uncertain or fails, at which point the secondary provider will be started. The secondary will be + * started and stopped as needed. * - *

Location-derived time zone providers are configured using {@link - * #PRIMARY_LOCATION_TIME_ZONE_PROVIDER_SERVICE_INTERFACE} and {@link - * #SECONDARY_LOCATION_TIME_ZONE_PROVIDER_SERVICE_INTERFACE} intent-filter actions respectively. - * Besides declaring the android:permission attribute mentioned above, the application supplying a - * location provider must be granted the {@link + *

Provider discovery: + * + *

Each provider is optional and can be disabled. When enabled, a provider's package name must + * be explicitly configured in the system server, see {@code + * config_primaryLocationTimeZoneProviderPackageName} and {@code + * config_secondaryLocationTimeZoneProviderPackageName} for details. + * + *

You must declare the service in the AndroidManifest of the app hosting the provider with the + * {@link android.Manifest.permission#BIND_TIME_ZONE_PROVIDER_SERVICE} permission, + * and include an intent filter with the necessary action indicating that it is the primary + * provider ({@link #PRIMARY_LOCATION_TIME_ZONE_PROVIDER_SERVICE_INTERFACE}) or the secondary + * provider ({@link #SECONDARY_LOCATION_TIME_ZONE_PROVIDER_SERVICE_INTERFACE}). + * + *

Besides declaring the android:permission attribute mentioned above, the application supplying + * a location provider must be granted the {@link * android.Manifest.permission#INSTALL_LOCATION_TIME_ZONE_PROVIDER_SERVICE} permission to be * accepted by the system server. * + *

{@link TimeZoneProviderService}s may be deployed into processes that run once-per-user + * or once-per-device (i.e. they service multiple users). See serviceIsMultiuser metadata below for + * configuration details. + * + *

The service may specify metadata on its capabilities: + * + *

+ * *

For example: * 

  *   <uses-permission
@@ -86,7 +100,7 @@ import java.util.Objects;
  *
  * ...
  *
- *     <service android:name=".FooTimeZoneProviderService"
+ *     <service android:name=".ExampleTimeZoneProviderService"
  *             android:exported="true"
  *             android:permission="android.permission.BIND_TIME_ZONE_PROVIDER_SERVICE">
  *         <intent-filter>
@@ -94,7 +108,6 @@ import java.util.Objects;
  *             android:name="android.service.timezone.SecondaryLocationTimeZoneProviderService"
  *             />
  *         </intent-filter>
- *         <meta-data android:name="serviceVersion" android:value="1" />
  *         <meta-data android:name="serviceIsMultiuser" android:value="true" />
  *     </service>
  *
diff --git a/services/core/java/com/android/server/timezonedetector/location/LocationTimeZoneManagerService.java b/services/core/java/com/android/server/timezonedetector/location/LocationTimeZoneManagerService.java index ca4a6408cfbb5..12767bce9c702 100644 --- a/services/core/java/com/android/server/timezonedetector/location/LocationTimeZoneManagerService.java +++ b/services/core/java/com/android/server/timezonedetector/location/LocationTimeZoneManagerService.java @@ -77,15 +77,7 @@ import java.util.concurrent.atomic.AtomicReference; * bound (ensuring no real location events will be received) and simulated events / behaviors * can be injected via the command line. * - *

To enter simulation mode for a provider, use {@code adb shell cmd location_time_zone_manager - * set_provider_mode_override <provider name> simulated} and restart the service with {@code - * adb shell cmd location_time_zone_manager stop} and {@code adb shell cmd - * location_time_zone_manager start}. - * - *

e.g. {@code adb shell cmd location_time_zone_manager set_provider_mode_override primary - * simulated}. - * - *

See {@code adb shell cmd location_time_zone_manager help}" for more options. + *

See {@code adb shell cmd location_time_zone_manager help}" for details and more options. */ public class LocationTimeZoneManagerService extends Binder {