src.com.android.server.timezonedetector.TimeZoneDetectorStrategy Maven / Gradle / Ivy
Show all versions of android-all Show documentation
/*
* Copyright 2019 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.android.server.timezonedetector;
import android.annotation.NonNull;
import android.annotation.UserIdInt;
import android.app.time.TimeZoneConfiguration;
import android.app.timezonedetector.ManualTimeZoneSuggestion;
import android.app.timezonedetector.TelephonyTimeZoneSuggestion;
import android.util.IndentingPrintWriter;
/**
* The interface for the class that is responsible for setting the time zone on a device, used by
* {@link TimeZoneDetectorService} and {@link TimeZoneDetectorInternal}.
*
* The strategy receives suggestions, which it may use to modify the device's time zone setting.
* Suggestions are acted on or ignored as needed, depending on previously received suggestions and
* the current user's configuration (see {@link ConfigurationInternal}).
*
*
Devices can have zero, one or two automatic time zone detection algorithm available at any
* point in time.
*
*
The two automatic detection algorithms supported are "telephony" and "geolocation". Algorithm
* availability and use depends on several factors:
*
* - Telephony is only available on devices with a telephony stack.
*
- Geolocation is also optional and configured at image creation time. When enabled on a
* device, its availability depends on the current user's settings, so switching between users can
* change the automatic algorithm used by the device.
*
*
* If there are no automatic time zone detections algorithms available then the user can usually
* change the device time zone manually. Under most circumstances the current user can turn
* automatic time zone detection on or off, or choose the algorithm via settings.
*
*
Telephony detection is independent of the current user. The device keeps track of the most
* recent telephony suggestion from each slotIndex. When telephony detection is in use, the highest
* scoring suggestion is used to set the device time zone based on a scoring algorithm. If several
* slotIndexes provide the same score then the slotIndex with the lowest numeric value "wins". If
* the situation changes and it is no longer possible to be confident about the time zone,
* slotIndexes must have an empty suggestion submitted in order to "withdraw" their previous
* suggestion otherwise it will remain in use.
*
*
Geolocation detection is dependent on the current user and their settings. The device retains
* at most one geolocation suggestion. Generally, use of a device's location is dependent on the
* user's "location toggle", but even when that is enabled the user may choose to enable / disable
* the use of geolocation for device time zone detection. If the current user changes to one that
* does not have geolocation detection enabled, or the user turns off geolocation detection, then
* the strategy discards the latest geolocation suggestion. Devices that lose a location fix must
* have an empty suggestion submitted in order to "withdraw" their previous suggestion otherwise it
* will remain in use.
*
*
Threading:
*
*
Suggestion calls with a void return type may be handed off to a separate thread and handled
* asynchronously. Synchronous calls like {@link #getCurrentUserConfigurationInternal()},
* {@link #generateMetricsState()} and debug calls like {@link
* #dump(IndentingPrintWriter, String[])}, may be called on a different thread concurrently with
* other operations.
*
* @hide
*/
public interface TimeZoneDetectorStrategy extends Dumpable, Dumpable.Container {
/**
* Adds a listener that will be triggered whenever {@link ConfigurationInternal} may have
* changed.
*/
void addConfigChangeListener(@NonNull ConfigurationChangeListener listener);
/**
* Returns a snapshot of the configuration that controls time zone detector behavior for the
* specified user.
*/
@NonNull
ConfigurationInternal getConfigurationInternal(@UserIdInt int userId);
/**
* Returns a snapshot of the configuration that controls time zone detector behavior for the
* current user.
*/
@NonNull
ConfigurationInternal getCurrentUserConfigurationInternal();
/**
* Updates the configuration properties that control a device's time zone behavior.
*
*
This method returns {@code true} if the configuration was changed,
* {@code false} otherwise.
*/
boolean updateConfiguration(
@UserIdInt int userId, @NonNull TimeZoneConfiguration configuration);
/**
* Suggests zero, one or more time zones for the device, or withdraws a previous suggestion if
* {@link GeolocationTimeZoneSuggestion#getZoneIds()} is {@code null}.
*/
void suggestGeolocationTimeZone(@NonNull GeolocationTimeZoneSuggestion suggestion);
/**
* Suggests a time zone for the device using manually-entered (i.e. user sourced) information.
*/
boolean suggestManualTimeZone(
@UserIdInt int userId, @NonNull ManualTimeZoneSuggestion suggestion);
/**
* Suggests a time zone for the device, or withdraws a previous suggestion if
* {@link TelephonyTimeZoneSuggestion#getZoneId()} is {@code null}. The suggestion is scoped to
* a specific {@link TelephonyTimeZoneSuggestion#getSlotIndex() slotIndex}.
* See {@link TelephonyTimeZoneSuggestion} for an explanation of the metadata associated with a
* suggestion.
*/
void suggestTelephonyTimeZone(@NonNull TelephonyTimeZoneSuggestion suggestion);
/** Generates a state snapshot for metrics. */
@NonNull
MetricsTimeZoneDetectorState generateMetricsState();
}