1 /*
2  * Copyright (C) 2018 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.timedetector;
18 
19 import android.annotation.NonNull;
20 import android.annotation.RequiresPermission;
21 import android.annotation.SystemService;
22 import android.content.Context;
23 import android.os.SystemClock;
24 import android.os.TimestampedValue;
25 
26 /**
27  * The interface through which system components can send signals to the TimeDetectorService.
28  *
29  * @hide
30  */
31 @SystemService(Context.TIME_DETECTOR_SERVICE)
32 public interface TimeDetector {
33 
34     /**
35      * The name of the service for shell commands.
36      * @hide
37      */
38     String SHELL_COMMAND_SERVICE_NAME = "time_detector";
39 
40     /**
41      * A shell command that prints the current "auto time detection" global setting value.
42      * @hide
43      */
44     String SHELL_COMMAND_IS_AUTO_DETECTION_ENABLED = "is_auto_detection_enabled";
45 
46     /**
47      * A shared utility method to create a {@link ManualTimeSuggestion}.
48      *
49      * @hide
50      */
createManualTimeSuggestion(long when, String why)51     static ManualTimeSuggestion createManualTimeSuggestion(long when, String why) {
52         TimestampedValue<Long> utcTime =
53                 new TimestampedValue<>(SystemClock.elapsedRealtime(), when);
54         ManualTimeSuggestion manualTimeSuggestion = new ManualTimeSuggestion(utcTime);
55         manualTimeSuggestion.addDebugInfo(why);
56         return manualTimeSuggestion;
57     }
58 
59     /**
60      * Suggests a telephony-signal derived time to the detector. The detector may ignore the signal
61      * if better signals are available such as those that come from more reliable sources or were
62      * determined more recently.
63      */
64     @RequiresPermission(android.Manifest.permission.SUGGEST_TELEPHONY_TIME_AND_ZONE)
suggestTelephonyTime(@onNull TelephonyTimeSuggestion timeSuggestion)65     void suggestTelephonyTime(@NonNull TelephonyTimeSuggestion timeSuggestion);
66 
67     /**
68      * Suggests the current time, determined from the user's manually entered information, to
69      * the detector. Returns {@code false} if the suggestion was invalid, or the device
70      * configuration prevented the suggestion being used, {@code true} if the suggestion was
71      * accepted. A suggestion that is valid but does not change the time because it matches the
72      * current device time is considered accepted.
73      *
74      * @hide
75      */
76     @RequiresPermission(android.Manifest.permission.SUGGEST_MANUAL_TIME_AND_ZONE)
suggestManualTime(@onNull ManualTimeSuggestion timeSuggestion)77     boolean suggestManualTime(@NonNull ManualTimeSuggestion timeSuggestion);
78 
79     /**
80      * Suggests the time according to a network time source like NTP.
81      *
82      * @hide
83      */
84     @RequiresPermission(android.Manifest.permission.SET_TIME)
suggestNetworkTime(NetworkTimeSuggestion timeSuggestion)85     void suggestNetworkTime(NetworkTimeSuggestion timeSuggestion);
86 
87     /**
88      * Suggests the time according to a gnss time source.
89      *
90      * @hide
91      */
92     @RequiresPermission(android.Manifest.permission.SET_TIME)
suggestGnssTime(GnssTimeSuggestion timeSuggestion)93     void suggestGnssTime(GnssTimeSuggestion timeSuggestion);
94 }
95