Merge "Improve / fix docs" into sc-dev

 *

 * <p>Once stopped or failed, providers are required to stop generating callbacks.

 *

 * <p>Provider types:

 *

 * <p>Android supports up to two <em>location-derived</em> time zone providers. These are called the

 * "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.

 *

 * <p>Provider discovery:

 *

 * <p>You must declare the service in your manifest file with the

 * <p>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.

 *

 * <p>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 what type of provider it is.

 * 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}).

 *

 * <p>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.

 * <p>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.

 *

 * <p>{@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.

 *

 * <p>Provider types:

 * or once-per-device (i.e. they service multiple users). See serviceIsMultiuser metadata below for

 * configuration details.

 *

 * <p>Android supports up to two <em>location-derived</em> 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.

 * <p>The service may specify metadata on its capabilities:

 *

 * <p>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

 * android.Manifest.permission#INSTALL_LOCATION_TIME_ZONE_PROVIDER_SERVICE} permission to be

 * accepted by the system server.

 * <ul>

 *     <li>

 *         "serviceIsMultiuser": A boolean property, indicating if the service wishes to take

 *         responsibility for handling changes to the current user on the device. If true, the

 *         service will always be bound from the system user. If false, the service will always be

 *         bound from the current user. If the current user changes, the old binding will be

 *         released, and a new binding established under the new user. Assumed to be false if not

 *         specified.

 *     </li>

 * </ul>

 *

 * <p>For example:

 * <pre>

 *

 * ...

 *

 *     <service android:name=".FooTimeZoneProviderService"

 *     <service android:name=".ExampleTimeZoneProviderService"

 *             android:exported="true"

 *             android:permission="android.permission.BIND_TIME_ZONE_PROVIDER_SERVICE">

 *         <intent-filter>

 *             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>

 * </pre>

 * bound (ensuring no real location events will be received) and simulated events / behaviors

 * can be injected via the command line.

 *

 * <p>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}.

 *

 * <p>e.g. {@code adb shell cmd location_time_zone_manager set_provider_mode_override primary

 * simulated}.

 *

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

 * <p>See {@code adb shell cmd location_time_zone_manager help}" for details and more options.

 */

public class LocationTimeZoneManagerService extends Binder {