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.media.soundtrigger_middleware; 18 19 import android.media.soundtrigger.RecognitionConfig; 20 import android.media.soundtrigger.SoundModel; 21 import android.media.soundtrigger.Phrase; 22 23 import android.media.soundtrigger_middleware.IInjectModelEvent; 24 import android.media.soundtrigger_middleware.IInjectRecognitionEvent; 25 import android.media.soundtrigger_middleware.IInjectGlobalEvent; 26 import android.media.soundtrigger_middleware.ISoundTriggerInjection; 27 28 /** 29 * An injection interface for {@link android.media.soundtrigger_middleware.FakeSoundTriggerHal}. 30 * To avoid deadlocks, all calls to this interface and the sub-interface it creates are oneway. 31 * Calls are identified as stale via "Session" parameters. 32 * The client implements this interface and registers it with 33 * {@link ISoundTriggerMiddlewareService#attachMockHalInjection(ISoundTriggerInjection)}. 34 * Then, the client will receive callbacks which observe mock HAL events. 35 * There are two types of calls. 36 * 1) Those that provide a new injection sub-interface (contains param .*Injection). 37 * 2) Those that are sessioned via an injection sub-interface (contains param .*Session). 38 * The new injection sub-interfaces generated by (1) can be used to trigger HAL events. 39 * Some calls within (2) will invalidate the session object which they are associated with 40 * (e.g. {@link soundModelUnloaded}), and will be noted as such. 41 * Some calls within the injection interface (e.g. {@link IInjectModelEvent#triggerUnloadModel()}) 42 * will invalidate the session object they are called upon, and will be noted as such. 43 * @hide 44 */ 45 oneway interface ISoundTriggerInjection { 46 47 /** 48 * Value of {@link android.media.soundtrigger.Properties#supportedModelArch} that 49 * identifies the HAL as a fake HAL. 50 */ 51 const String FAKE_HAL_ARCH = "injection"; 52 53 /** 54 * Called following attachment via 55 * {@link ISoundTriggerMiddlewareService#attachMockHalInjection(ISoundTriggerInjection)}. 56 * Provides the client an injection interface for events which are always (globally) valid. 57 * @param globalInjection - Interface used to inject global events to the fake HAL. 58 * Used as a session object for further callbacks associated with the HAL globally. 59 */ registerGlobalEventInjection(IInjectGlobalEvent globalInjection)60 void registerGlobalEventInjection(IInjectGlobalEvent globalInjection); 61 62 /** 63 * Called when the HAL has been restarted by the framework. Not called after a 64 * {@link IInjectGlobalEvent#triggerRestart()}. 65 * @param globalSession - The interface previously provided by a 66 * {@link registerGlobalEventInjection} call which this restart is associated with. 67 * Used to disambiguate stale restart events from a subsequent global session. 68 */ onRestarted(IInjectGlobalEvent globalSession)69 void onRestarted(IInjectGlobalEvent globalSession); 70 71 /** 72 * Called when the HAL has been detached by the framework. 73 * @param globalSession - The interface previously provided by a 74 * {@link registerGlobalEventInjection} call which this detach is associated with. 75 * Used to disambiguate stale detach events from a subsequent global session. 76 */ onFrameworkDetached(IInjectGlobalEvent globalSession)77 void onFrameworkDetached(IInjectGlobalEvent globalSession); 78 79 /** 80 * Called when a client is attached to the framework. This event is not actually 81 * delivered to the HAL, but is useful to understand the framework state. 82 * @param token - An opaque token representing the framework client session. 83 * Associated with a subsequent call to {@link onClientDetached(IBinder)}. 84 * @param globalSession - The global STHAL session this attach is associated with. 85 */ onClientAttached(IBinder token, IInjectGlobalEvent globalSession)86 void onClientAttached(IBinder token, IInjectGlobalEvent globalSession); 87 88 /** 89 * Called when a client detaches from the framework. This event is not actually 90 * delivered to the HAL, but is useful to understand the framework state. 91 * @param token - The opaque token returned by a previous 92 * {@link onClientAttached(IBinder, IInjectGlobalEvent} call. 93 */ onClientDetached(IBinder token)94 void onClientDetached(IBinder token); 95 96 /** 97 * Called when a sound model is loaded into the fake STHAL by the framework. 98 * @param model - The model data for the newly loaded model. 99 * @param phrases - The phrase data for the newly loaded model, if it is a keyphrase model. 100 * Null otherwise. 101 * @param modelInjection - Interface used to inject events associated with the newly loaded 102 * model into the fake STHAL. 103 * Used as a session object for further callbacks associated with this newly loaded model. 104 * @param globalSession - The session object representing the global STHAL instance this load 105 * is associated with. 106 */ onSoundModelLoaded(in SoundModel model, in @nullable Phrase[] phrases, IInjectModelEvent modelInjection, IInjectGlobalEvent globalSession)107 void onSoundModelLoaded(in SoundModel model, in @nullable Phrase[] phrases, 108 IInjectModelEvent modelInjection, IInjectGlobalEvent globalSession); 109 110 /** 111 * Called when the fake STHAL receives a set parameter call from the framework on a previously 112 * loaded model. 113 * @param modelParam - Code of the parameter being set, see 114 * {@link android.media.soundtrigger.ModelParameter} 115 * @param value - Value to set the modelParam to 116 * @param modelSession - Session object of the loaded model the set param call is associated 117 * with. 118 */ 119 onParamSet(int modelParam, int value, IInjectModelEvent modelSession)120 void onParamSet(int modelParam, int value, IInjectModelEvent modelSession); 121 122 123 /** 124 * Called when a previously loaded model in the fake STHAL has recognition started by the 125 * framework. 126 * @param audioSessionToken - The audio session token passed by the framework which will be 127 * contained within a received recognition event. 128 * @param config - The recognition config passed by the framework for this recognition. 129 * @param recognitionInjection - A new injection interface which allows the client to 130 * trigger events associated with this newly started recognition. 131 * @param modelSession - The session object representing the loaded model that this 132 * recognition is associated with. 133 */ onRecognitionStarted(int audioSessionToken, in RecognitionConfig config, IInjectRecognitionEvent recognitionInjection, IInjectModelEvent modelSession)134 void onRecognitionStarted(int audioSessionToken, in RecognitionConfig config, 135 IInjectRecognitionEvent recognitionInjection, IInjectModelEvent modelSession); 136 137 /** 138 * Called when a previously started recognition in the fake STHAL is stopped by the framework. 139 * Not called following any calls on {@link IInjectRecognitionEvent}. 140 * @param recognitionSession - The session object received via a previous call to 141 * {@link recognitionStarted(int, RecognitionConfig, IInjectModelEvent, 142 * IInjectRecognitionEvent} which has been unloaded. 143 * This session is invalidated subsequent to this call, and no triggers will be respected. 144 */ onRecognitionStopped(IInjectRecognitionEvent recognitionSession)145 void onRecognitionStopped(IInjectRecognitionEvent recognitionSession); 146 147 /** 148 * Called when a previously loaded model in the fake STHAL is unloaded by the framework. 149 * Not called following {@link IInjectModelEvent#triggerUnloadModel()}. 150 * @param modelSession - The session object received via a previous call to 151 * {@link soundModelLoaded(SoundModel, Phrase[], IInjectModelEvent} which has been unloaded. 152 * This session is invalidated subsequent to this call, and no triggers will be respected. 153 */ onSoundModelUnloaded(IInjectModelEvent modelSession)154 void onSoundModelUnloaded(IInjectModelEvent modelSession); 155 156 /** 157 * Called when this injection interface has been preempted by a subsequent call to 158 * {@link ISoundTriggerMiddleware#attachFakeHal(ISoundTriggerInjection)}. 159 * No more events will be delivered, and any further injection will be ignored. 160 */ onPreempted()161 void onPreempted(); 162 163 } 164