| /* |
| * Copyright (C) 2019 The Android Open Source Project |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| package com.android.server.soundtrigger_middleware; |
| |
| import android.hardware.soundtrigger3.ISoundTriggerHw; |
| import android.hardware.soundtrigger3.ISoundTriggerHwCallback; |
| import android.hardware.soundtrigger3.ISoundTriggerHwGlobalCallback; |
| import android.media.soundtrigger.ModelParameterRange; |
| import android.media.soundtrigger.PhraseSoundModel; |
| import android.media.soundtrigger.Properties; |
| import android.media.soundtrigger.RecognitionConfig; |
| import android.media.soundtrigger.SoundModel; |
| import android.media.soundtrigger_middleware.PhraseRecognitionEventSys; |
| import android.media.soundtrigger_middleware.RecognitionEventSys; |
| import android.os.IBinder; |
| |
| /** |
| * This interface mimics the soundtrigger HAL interface, with a few key differences: |
| * <ul> |
| * <li>Generally, methods should not throw, except for the following cases: |
| * <ul> |
| * <li>Any unexpected HAL behavior is considered an internal HAL malfunction and should be thrown |
| * as a {@link HalException}, from any method. |
| * <li>A {@link RuntimeException} with a {@link android.os.DeadObjectException} cause represents |
| * a dead HAL process and may be thrown by any method. |
| * <li>Implementations of earlier versions of the interface may throw a |
| * {@link RecoverableException} with a |
| * {@link android.media.soundtrigger.Status#OPERATION_NOT_SUPPORTED} for methods that |
| * have been introduced in later versions of the interface. |
| * <li>Certain methods are allowed to throw a {@link RecoverableException} with a |
| * {@link android.media.soundtrigger.Status#RESOURCE_CONTENTION} to indicate transient |
| * failures. |
| * </ul> |
| * <li>Some binder-specific details are hidden. |
| * <li>No RemoteExceptions are specified. Some implementations of this interface may rethrow |
| * RemoteExceptions as RuntimeExceptions, some can guarantee handling them somehow and never throw |
| * them. |
| * </ul> |
| * For cases where the client wants to explicitly handle specific versions of the underlying driver |
| * interface, they may call {@link #interfaceDescriptor()}. |
| * <p> |
| * <b>Note to maintainers</b>: This class must always be kept in sync with the latest version, |
| * so that clients have access to the entire functionality without having to burden themselves with |
| * compatibility, as much as possible. |
| */ |
| interface ISoundTriggerHal { |
| /** |
| * @see ISoundTriggerHw#getProperties() |
| */ |
| Properties getProperties(); |
| |
| /** |
| * @see ISoundTriggerHw#registerGlobalCallback(ISoundTriggerHwGlobalCallback) |
| */ |
| void registerCallback(GlobalCallback callback); |
| |
| /** |
| * @see ISoundTriggerHw#loadSoundModel(android.media.soundtrigger.SoundModel, |
| * ISoundTriggerHwCallback) |
| */ |
| int loadSoundModel(SoundModel soundModel, ModelCallback callback); |
| |
| /** |
| * @see ISoundTriggerHw#loadPhraseSoundModel(android.media.soundtrigger.PhraseSoundModel, |
| * ISoundTriggerHwCallback) |
| */ |
| int loadPhraseSoundModel(PhraseSoundModel soundModel, ModelCallback callback); |
| |
| /** |
| * @see ISoundTriggerHw#unloadSoundModel(int) |
| */ |
| void unloadSoundModel(int modelHandle); |
| |
| /** |
| * @see ISoundTriggerHw#startRecognition(int, int, int, RecognitionConfig) |
| */ |
| void startRecognition(int modelHandle, int deviceHandle, int ioHandle, |
| RecognitionConfig config); |
| |
| /** |
| * @see ISoundTriggerHw#stopRecognition(int) |
| */ |
| void stopRecognition(int modelHandle); |
| |
| /** |
| * @see ISoundTriggerHw#forceRecognitionEvent(int) |
| */ |
| void forceRecognitionEvent(int modelHandle); |
| |
| /** |
| * @return null if not supported. |
| * @see ISoundTriggerHw#queryParameter(int, int) |
| */ |
| ModelParameterRange queryParameter(int modelHandle, int param); |
| |
| /** |
| * @see ISoundTriggerHw#getParameter(int, int) |
| */ |
| int getModelParameter(int modelHandle, int param); |
| |
| /** |
| * @see ISoundTriggerHw#setParameter(int, int, int) |
| */ |
| void setModelParameter(int modelHandle, int param, int value); |
| |
| /** |
| * @see IBinder#getInterfaceDescriptor() |
| */ |
| String interfaceDescriptor(); |
| |
| /** |
| * @see IBinder#linkToDeath(IBinder.DeathRecipient, int) |
| */ |
| void linkToDeath(IBinder.DeathRecipient recipient); |
| |
| /** |
| * @see IBinder#unlinkToDeath(IBinder.DeathRecipient, int) |
| */ |
| void unlinkToDeath(IBinder.DeathRecipient recipient); |
| |
| /* |
| * This is only useful for testing decorators and doesn't actually do anything with the real |
| * HAL. This method would block until all callbacks that were previously generated have been |
| * invoked. For most decorators, this merely flushes the delegate, but for delegates that may |
| * have additional buffers for callbacks this should flush them. |
| */ |
| void flushCallbacks(); |
| |
| /** |
| * Used only for testing purposes. Called when a client attaches to the framework. |
| * Transmitting this event to the fake STHAL allows observation of this event, which is |
| * normally consumed by the framework, and is not communicated to the STHAL. |
| * @param token - A unique binder token associated with this session. |
| */ |
| void clientAttached(IBinder token); |
| |
| /** |
| * Used only for testing purposes. Called when a client detached from the framework. |
| * Transmitting this event to the fake STHAL allows observation of this event, which is |
| * normally consumed by the framework, and is not communicated to the STHAL. |
| * @param token - The same token passed to the corresponding {@link clientAttached(IBinder)}. |
| */ |
| void clientDetached(IBinder token); |
| |
| /** |
| * Kill and restart the HAL instance. This is typically a last resort for error recovery and may |
| * result in other related services being killed. |
| */ |
| void reboot(); |
| |
| /** |
| * Called when this interface is guaranteed to no longer be used and can free up any resources |
| * used. |
| */ |
| void detach(); |
| |
| /** |
| * Callback interface for model-related events. |
| */ |
| interface ModelCallback { |
| /** |
| * Decorated callback of |
| * {@link ISoundTriggerHwCallback#recognitionCallback(int, RecognitionEvent)} where |
| * {@link RecognitionEventSys} is decorating the returned {@link RecognitionEvent} |
| */ |
| void recognitionCallback(int modelHandle, RecognitionEventSys event); |
| |
| /** |
| * Decorated callback of |
| * {@link ISoundTriggerHwCallback#phraseRecognitionCallback(int, PhraseRecognitionEvent)} |
| * where {@link PhraseRecognitionEventSys} is decorating the returned |
| * {@link PhraseRecognitionEvent} |
| */ |
| void phraseRecognitionCallback(int modelHandle, PhraseRecognitionEventSys event); |
| |
| /** |
| * @see ISoundTriggerHwCallback#modelUnloaded(int) |
| */ |
| void modelUnloaded(int modelHandle); |
| } |
| |
| /** |
| * Callback interface for global events. |
| */ |
| interface GlobalCallback { |
| /** |
| * @see ISoundTriggerHwGlobalCallback#onResourcesAvailable() |
| */ |
| void onResourcesAvailable(); |
| } |
| } |