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.media.soundtrigger_middleware;
18 
19 import android.media.permission.Identity;
20 import android.media.soundtrigger_middleware.ISoundTriggerCallback;
21 import android.media.soundtrigger_middleware.ISoundTriggerInjection;
22 import android.media.soundtrigger_middleware.ISoundTriggerModule;
23 import android.media.soundtrigger_middleware.SoundTriggerModuleDescriptor;
24 
25 /**
26  * Main entry point into this module.
27  *
28  * Allows the client to enumerate the available soundtrigger devices and their capabilities, then
29  * attach to either one of them in order to use it.
30  *
31  * {@hide}
32  */
33 interface ISoundTriggerMiddlewareService {
34     /**
35      * Query the available modules and their capabilities.
36      *
37      * This variant is intended for use by the originator of the operations for permission
38      * enforcement purposes. The provided identity's uid/pid fields will be ignored and overridden
39      * by the ones provided by Binder.getCallingUid() / Binder.getCallingPid().
40      */
listModulesAsOriginator(in Identity identity)41     SoundTriggerModuleDescriptor[] listModulesAsOriginator(in Identity identity);
42 
43     /**
44      * Query the available modules and their capabilities.
45      *
46      * This variant is intended for use by a trusted "middleman", acting on behalf of some identity
47      * other than itself. The caller must provide:
48      * - Its own identity, which will be used to establish trust via the
49      *   SOUNDTRIGGER_DELEGATE_IDENTITY permission. This identity's uid/pid fields will be ignored
50      *   and overridden by the ones provided by Binder.getCallingUid() / Binder.getCallingPid().
51      *   This implies that the caller must clear its caller identity to protect from the case where
52      *   it resides in the same process as the callee.
53      * - The identity of the entity on behalf of which module operations are to be performed.
54      */
listModulesAsMiddleman(in Identity middlemanIdentity, in Identity originatorIdentity)55     SoundTriggerModuleDescriptor[] listModulesAsMiddleman(in Identity middlemanIdentity,
56                                                           in Identity originatorIdentity);
57 
58     /**
59      * Attach to one of the available modules.
60      *
61      * This variant is intended for use by the originator of the operations for permission
62      * enforcement purposes. The provided identity's uid/pid fields will be ignored and overridden
63      * by the ones provided by Binder.getCallingUid() / Binder.getCallingPid().
64      *
65      * listModules() must be called prior to calling this method and the provided handle must be
66      * one of the handles from the returned list.
67      */
attachAsOriginator(int handle, in Identity identity, ISoundTriggerCallback callback)68     ISoundTriggerModule attachAsOriginator(int handle,
69                                            in Identity identity,
70                                            ISoundTriggerCallback callback);
71 
72     /**
73      * Attach to one of the available modules.
74      *
75      * This variant is intended for use by a trusted "middleman", acting on behalf of some identity
76      * other than itself. The caller must provide:
77      * - Its own identity, which will be used to establish trust via the
78      *   SOUNDTRIGGER_DELEGATE_IDENTITY permission. This identity's uid/pid fields will be ignored
79      *   and overridden by the ones provided by Binder.getCallingUid() / Binder.getCallingPid().
80      *   This implies that the caller must clear its caller identity to protect from the case where
81      *   it resides in the same process as the callee.
82      * - The identity of the entity on behalf of which module operations are to be performed.
83      * @param isTrusted - {@code true} if the middleware should not audit data delivery, since the
84      * callback is being delivered to another trusted component which will audit access.
85      * listModules() must be called prior to calling this method and the provided handle must be
86      * one of the handles from the returned list.
87      */
attachAsMiddleman(int handle, in Identity middlemanIdentity, in Identity originatorIdentity, ISoundTriggerCallback callback, boolean isTrusted)88     ISoundTriggerModule attachAsMiddleman(int handle,
89                                           in Identity middlemanIdentity,
90                                           in Identity originatorIdentity,
91                                           ISoundTriggerCallback callback,
92                                           boolean isTrusted);
93 
94     /**
95      * Attach an injection interface interface to the ST mock HAL.
96      * See {@link ISoundTriggerInjection} for injection details.
97      * If another client attaches, this session will be pre-empted.
98      */
attachFakeHalInjection(ISoundTriggerInjection injection)99     void attachFakeHalInjection(ISoundTriggerInjection injection);
100 
101 }
102