1 /*
2  * Copyright (C) 2019 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.timezonedetector;
18 
19 import android.annotation.NonNull;
20 import android.annotation.RequiresPermission;
21 import android.annotation.SystemService;
22 import android.content.Context;
23 
24 /**
25  * The interface through which system components can query and send signals to the
26  * TimeZoneDetectorService.
27  *
28  * <p>SDK APIs are exposed on {@link android.app.time.TimeManager} to obscure the internal split
29  * between time and time zone detection services. Migrate APIs there if they need to be part of an
30  * SDK API.
31  *
32  * @hide
33  */
34 @SystemService(Context.TIME_ZONE_DETECTOR_SERVICE)
35 public interface TimeZoneDetector {
36 
37     /**
38      * The name of the service for shell commands.
39      * @hide
40      */
41     String SHELL_COMMAND_SERVICE_NAME = "time_zone_detector";
42 
43     /**
44      * A shell command that prints the current "auto time zone detection" global setting value.
45      * @hide
46      */
47     String SHELL_COMMAND_IS_AUTO_DETECTION_ENABLED = "is_auto_detection_enabled";
48 
49     /**
50      * A shell command that sets the current "auto time zone detection" global setting value.
51      * @hide
52      */
53     String SHELL_COMMAND_SET_AUTO_DETECTION_ENABLED = "set_auto_detection_enabled";
54 
55     /**
56      * A shell command that prints whether the telephony-based time zone detection feature is
57      * supported on the device.
58      * @hide
59      */
60     String SHELL_COMMAND_IS_TELEPHONY_DETECTION_SUPPORTED = "is_telephony_detection_supported";
61 
62     /**
63      * A shell command that prints whether the geolocation-based time zone detection feature is
64      * supported on the device.
65      * @hide
66      */
67     String SHELL_COMMAND_IS_GEO_DETECTION_SUPPORTED = "is_geo_detection_supported";
68 
69     /**
70      * A shell command that prints the current user's "location-based time zone detection enabled"
71      * setting.
72      * @hide
73      */
74     String SHELL_COMMAND_IS_GEO_DETECTION_ENABLED = "is_geo_detection_enabled";
75 
76     /**
77      * A shell command that sets the current user's "location-based time zone detection enabled"
78      * setting.
79      * @hide
80      */
81     String SHELL_COMMAND_SET_GEO_DETECTION_ENABLED = "set_geo_detection_enabled";
82 
83     /**
84      * A shell command that injects a location algorithm event (as if from the
85      * location_time_zone_manager).
86      * @hide
87      */
88     String SHELL_COMMAND_HANDLE_LOCATION_ALGORITHM_EVENT = "handle_location_algorithm_event";
89 
90     /**
91      * A shell command that injects a manual time zone suggestion (as if from the SettingsUI or
92      * similar).
93      * @hide
94      */
95     String SHELL_COMMAND_SUGGEST_MANUAL_TIME_ZONE = "suggest_manual_time_zone";
96 
97     /**
98      * A shell command that injects a telephony time zone suggestion (as if from the phone app).
99      * @hide
100      */
101     String SHELL_COMMAND_SUGGEST_TELEPHONY_TIME_ZONE = "suggest_telephony_time_zone";
102 
103     /**
104      * A shell command that enables telephony time zone fallback. See {@link
105      * com.android.server.timezonedetector.TimeZoneDetectorStrategy} for details.
106      * @hide
107      */
108     String SHELL_COMMAND_ENABLE_TELEPHONY_FALLBACK = "enable_telephony_fallback";
109 
110     /**
111      * A shell command that retrieves the current time zone setting state.
112      * @hide
113      */
114     String SHELL_COMMAND_GET_TIME_ZONE_STATE = "get_time_zone_state";
115 
116     /**
117      * A shell command that sets the current time zone state for testing.
118      * @hide
119      */
120     String SHELL_COMMAND_SET_TIME_ZONE_STATE = "set_time_zone_state_for_tests";
121 
122     /**
123      * A shell command that sets the confidence in the current time zone state for testing.
124      * @hide
125      */
126     String SHELL_COMMAND_CONFIRM_TIME_ZONE = "confirm_time_zone";
127 
128     /**
129      * A shell command that dumps a {@link
130      * com.android.server.timezonedetector.MetricsTimeZoneDetectorState} object to stdout for
131      * debugging.
132      * @hide
133      */
134     String SHELL_COMMAND_DUMP_METRICS = "dump_metrics";
135 
136     /**
137      * A shared utility method to create a {@link ManualTimeZoneSuggestion}.
138      *
139      * @hide
140      */
createManualTimeZoneSuggestion(String tzId, String debugInfo)141     static ManualTimeZoneSuggestion createManualTimeZoneSuggestion(String tzId, String debugInfo) {
142         ManualTimeZoneSuggestion suggestion = new ManualTimeZoneSuggestion(tzId);
143         suggestion.addDebugInfo(debugInfo);
144         return suggestion;
145     }
146 
147     /**
148      * Suggests the current time zone, determined from the user's manually entered information, to
149      * the detector. Returns {@code false} if the suggestion was invalid, or the device
150      * configuration / user capabilities prevents the suggestion being used (even if it is the same
151      * as the current device time zone), {@code true} if the suggestion was accepted. A suggestion
152      * that is valid but does not change the time zone because it matches the current device time
153      * zone is considered accepted.
154      *
155      * @hide
156      */
157     @RequiresPermission(android.Manifest.permission.SUGGEST_MANUAL_TIME_AND_ZONE)
suggestManualTimeZone(@onNull ManualTimeZoneSuggestion timeZoneSuggestion)158     boolean suggestManualTimeZone(@NonNull ManualTimeZoneSuggestion timeZoneSuggestion);
159 
160     /**
161      * Suggests the current time zone, determined using telephony signals, to the detector. The
162      * detector may ignore the signal based on system settings, whether better information is
163      * available, and so on.
164      *
165      * @hide
166      */
167     @RequiresPermission(android.Manifest.permission.SUGGEST_TELEPHONY_TIME_AND_ZONE)
suggestTelephonyTimeZone(@onNull TelephonyTimeZoneSuggestion timeZoneSuggestion)168     void suggestTelephonyTimeZone(@NonNull TelephonyTimeZoneSuggestion timeZoneSuggestion);
169 }
170