1 /*
2  * Copyright (C) 2023 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.flags;
18 
19 import android.flags.IFeatureFlagsCallback;
20 import android.flags.SyncableFlag;
21 
22 /**
23  * Binder interface for communicating with {@link com.android.server.flags.FeatureFlagsService}.
24  *
25  * This interface is used by {@link android.flags.FeatureFlags} and developers should use that to
26  * interface with the service. FeatureFlags is the "client" in this documentation.
27  *
28  * The methods allow client apps to communicate what flags they care about, and receive back
29  * current values for those flags. For stable flags, this is the finalized value until the device
30  * restarts. For {@link DynamicFlag}s, this is the last known value, though it may change in the
31  * future. Clients can listen for changes to flag values so that it can react accordingly.
32  * @hide
33  */
34 interface IFeatureFlags {
35     /**
36      * Synchronize with the {@link com.android.server.flags.FeatureFlagsService} about flags of
37      * interest.
38      *
39      * The client should pass in a list of flags that it is using as {@link SyncableFlag}s, which
40      * includes what it thinks the default values of the flags are.
41      *
42      * The response will contain a list of matching SyncableFlags, whose values are set to what the
43      * value of the flags actually are. The client should update its internal state flag data to
44      * match.
45      *
46      * Generally speaking, if a flag that is passed in is new to the FeatureFlagsService, the
47      * service will cache the passed-in value, and return it back out. If, however, a different
48      * client has synced that flag with the service previously, FeatureFlagsService will return the
49      * existing cached value, which may or may not be what the current client passed in. This allows
50      * FeatureFlagsService to keep clients in agreement with one another.
51      */
syncFlags(in List<SyncableFlag> flagList)52     List<SyncableFlag> syncFlags(in List<SyncableFlag> flagList);
53 
54     /**
55      * Pass in an {@link IFeatureFlagsCallback} that will be called whenever a {@link DymamicFlag}
56      * changes.
57      */
registerCallback(IFeatureFlagsCallback callback)58     void registerCallback(IFeatureFlagsCallback callback);
59 
60     /**
61      * Remove a {@link IFeatureFlagsCallback} that was previously registered with
62      * {@link #registerCallback}.
63      */
unregisterCallback(IFeatureFlagsCallback callback)64     void unregisterCallback(IFeatureFlagsCallback callback);
65 
66     /**
67      * Query the {@link com.android.server.flags.FeatureFlagsService} for flags, but don't
68      * cache them. See {@link #syncFlags}.
69      *
70      * You almost certainly don't want this method. This is intended for the Flag Flipper
71      * application that needs to query the state of system but doesn't want to affect it by
72      * doing so. All other clients should use {@link syncFlags}.
73      */
queryFlags(in List<SyncableFlag> flagList)74     List<SyncableFlag> queryFlags(in List<SyncableFlag> flagList);
75 
76     /**
77      * Change a flags value in the system.
78      *
79      * This is intended for use by the Flag Flipper application.
80      */
overrideFlag(in SyncableFlag flag)81     void overrideFlag(in SyncableFlag flag);
82 
83     /**
84      * Restore a flag to its default value.
85      *
86      * This is intended for use by the Flag Flipper application.
87      */
resetFlag(in SyncableFlag flag)88     void resetFlag(in SyncableFlag flag);
89 }