1 /** 2 * Copyright (C) 2014 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 com.android.server; 18 19 import android.annotation.NonNull; 20 import android.annotation.Nullable; 21 import android.hardware.soundtrigger.IRecognitionStatusCallback; 22 import android.hardware.soundtrigger.ModelParams; 23 import android.hardware.soundtrigger.SoundTrigger; 24 import android.hardware.soundtrigger.SoundTrigger.Keyphrase; 25 import android.hardware.soundtrigger.SoundTrigger.KeyphraseSoundModel; 26 import android.hardware.soundtrigger.SoundTrigger.ModelParamRange; 27 import android.hardware.soundtrigger.SoundTrigger.ModuleProperties; 28 import android.hardware.soundtrigger.SoundTrigger.RecognitionConfig; 29 import android.media.permission.Identity; 30 import android.os.IBinder; 31 32 import java.io.FileDescriptor; 33 import java.io.PrintWriter; 34 import java.util.List; 35 36 /** 37 * Provides a local service for managing voice-related recoginition models. This is primarily used 38 * by the {@code VoiceInteractionManagerService}. 39 */ 40 public interface SoundTriggerInternal { 41 /** 42 * Return codes for {@link Session#startRecognition(int, KeyphraseSoundModel, 43 * IRecognitionStatusCallback, RecognitionConfig)}, 44 * {@link Session#stopRecognition(int, IRecognitionStatusCallback)} 45 */ 46 int STATUS_ERROR = SoundTrigger.STATUS_ERROR; 47 int STATUS_OK = SoundTrigger.STATUS_OK; 48 49 // Attach to a specific underlying STModule 50 /** 51 * Attach to a specific underlying STModule. 52 * @param client - Binder token representing the app client for death notifications 53 * @param underlyingModule - Properties of the underlying STModule to attach to 54 * @param isTrusted - {@code true} if callbacks will be appropriately AppOps attributed by 55 * a trusted component prior to delivery to the ultimate client. 56 */ attach(@onNull IBinder client, ModuleProperties underlyingModule, boolean isTrusted)57 Session attach(@NonNull IBinder client, ModuleProperties underlyingModule, boolean isTrusted); 58 59 // Enumerate possible STModules to attach to listModuleProperties(Identity originatorIdentity)60 List<ModuleProperties> listModuleProperties(Identity originatorIdentity); 61 62 interface Session { 63 /** 64 * Starts recognition for the given keyphraseId. 65 * 66 * @param keyphraseId The identifier of the keyphrase for which 67 * the recognition is to be started. 68 * @param soundModel The sound model to use for recognition. 69 * @param listener The listener for the recognition events related to the given 70 * keyphrase. 71 * @param runInBatterySaverMode flag that indicates whether the recognition should continue 72 * after battery saver mode is enabled. 73 * @return One of {@link #STATUS_ERROR} or {@link #STATUS_OK}. 74 */ startRecognition(int keyphraseId, KeyphraseSoundModel soundModel, IRecognitionStatusCallback listener, RecognitionConfig recognitionConfig, boolean runInBatterySaverMode)75 int startRecognition(int keyphraseId, KeyphraseSoundModel soundModel, 76 IRecognitionStatusCallback listener, RecognitionConfig recognitionConfig, 77 boolean runInBatterySaverMode); 78 79 /** 80 * Stops recognition for the given {@link Keyphrase} if a recognition is 81 * currently active. 82 * 83 * @param keyphraseId The identifier of the keyphrase for which 84 * the recognition is to be stopped. 85 * @param listener The listener for the recognition events related to the given 86 * keyphrase. 87 * @return One of {@link #STATUS_ERROR} or {@link #STATUS_OK}. 88 */ stopRecognition(int keyphraseId, IRecognitionStatusCallback listener)89 int stopRecognition(int keyphraseId, IRecognitionStatusCallback listener); 90 getModuleProperties()91 ModuleProperties getModuleProperties(); 92 93 /** 94 * Set a model specific {@link ModelParams} with the given value. This 95 * parameter will keep its value for the duration the model is loaded regardless of starting 96 * and 97 * stopping recognition. Once the model is unloaded, the value will be lost. 98 * {@link #queryParameter} should be checked first before calling this 99 * method. 100 * 101 * @param keyphraseId The identifier of the keyphrase for which 102 * to modify model parameters 103 * @param modelParam {@link ModelParams} 104 * @param value Value to set 105 * @return - {@link SoundTrigger#STATUS_OK} in case of success 106 * - {@link SoundTrigger#STATUS_NO_INIT} if the native service cannot be reached 107 * - {@link SoundTrigger#STATUS_BAD_VALUE} invalid input parameter 108 * - {@link SoundTrigger#STATUS_INVALID_OPERATION} if the call is out of sequence or 109 * if API is not supported by HAL 110 */ setParameter(int keyphraseId, @ModelParams int modelParam, int value)111 int setParameter(int keyphraseId, @ModelParams int modelParam, int value); 112 113 /** 114 * Get a model specific {@link ModelParams}. This parameter will keep its value 115 * for the duration the model is loaded regardless of starting and stopping recognition. 116 * Once the model is unloaded, the value will be lost. If the value is not set, a default 117 * value is returned. See ModelParams for parameter default values. 118 * {{@link #queryParameter}} should be checked first before calling this 119 * method. 120 * 121 * @param keyphraseId The identifier of the keyphrase for which 122 * to modify model parameters 123 * @param modelParam {@link ModelParams} 124 * @return value of parameter 125 * @throws UnsupportedOperationException if hal or model do not support this API. 126 * queryParameter should be checked first. 127 * @throws IllegalArgumentException if invalid model handle or parameter is passed. 128 * queryParameter should be checked first. 129 */ getParameter(int keyphraseId, @ModelParams int modelParam)130 int getParameter(int keyphraseId, @ModelParams int modelParam); 131 132 /** 133 * Determine if parameter control is supported for the given model handle. 134 * This method should be checked prior to calling {@link #setParameter} 135 * or {@link #getParameter}. 136 * 137 * @param keyphraseId The identifier of the keyphrase for which 138 * to modify model parameters 139 * @param modelParam {@link ModelParams} 140 * @return supported range of parameter, null if not supported 141 */ 142 @Nullable queryParameter(int keyphraseId, @ModelParams int modelParam)143 ModelParamRange queryParameter(int keyphraseId, 144 @ModelParams int modelParam); 145 146 /** 147 * Invalidates the sound trigger session and clears any associated resources. Subsequent 148 * calls to this object will throw IllegalStateException. 149 */ detach()150 void detach(); 151 152 /** 153 * Unloads (and stops if running) the given keyphraseId 154 */ unloadKeyphraseModel(int keyphaseId)155 int unloadKeyphraseModel(int keyphaseId); 156 } 157 } 158