1 /*
2  * Copyright (C) 2021 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 per  missions and
14  * limitations under the License.
15  */
16 
17 package android.companion;
18 
19 import android.companion.AssociationInfo;
20 
21 /** @hide */
22 interface IOnAssociationsChangedListener {
23 
24     /*
25      * IMPORTANT: This method is intentionally NOT "oneway".
26      *
27      * The method is intentionally "blocking" to make sure that the clients of the
28      * addOnAssociationsChangedListener() API (@SystemAPI guarded by a "signature" permission) are
29      * able to prevent race conditions that may arise if their own clients (applications)
30      * effectively get notified about the changes before system services do.
31      *
32      * This is safe for 2 reasons:
33      *  1. The addOnAssociationsChangedListener() is only available to the system components
34      *     (guarded by a "signature" permission).
35      *     See android.permission.MANAGE_COMPANION_DEVICES.
36      *  2. On the Java side addOnAssociationsChangedListener() in CDM takes an Executor, and the
37      *     proxy implementation of onAssociationsChanged() simply "post" a Runnable to it.
38      *     See CompanionDeviceManager.OnAssociationsChangedListenerProxy class.
39      */
onAssociationsChanged(in List<AssociationInfo> associations)40     void onAssociationsChanged(in List<AssociationInfo> associations);
41 }