1 /*
2  * Copyright (C) 2022 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.service.voice;
18 
19 import android.annotation.DurationMillisLong;
20 import android.annotation.Nullable;
21 import android.annotation.SystemApi;
22 import android.os.Bundle;
23 import android.os.IRemoteCallback;
24 import android.os.PersistableBundle;
25 import android.os.RemoteException;
26 import android.os.SharedMemory;
27 
28 import java.util.function.IntConsumer;
29 
30 /**
31  * Provides common initialzation methods for sandboxed detection services.
32  *
33  * @hide
34  */
35 @SystemApi
36 public interface SandboxedDetectionInitializer {
37 
38     /**
39      * Indicates that the updated status is successful.
40      */
41     int INITIALIZATION_STATUS_SUCCESS = 0;
42 
43     /**
44      * Indicates that the callback wasn’t invoked within the timeout.
45      * This is used by system.
46      */
47     int INITIALIZATION_STATUS_UNKNOWN = 100;
48 
49     /** @hide */
50     String KEY_INITIALIZATION_STATUS = "initialization_status";
51 
52     /**
53      * The maximum number of initialization status for some application specific failed reasons.
54      *
55      * @hide
56      */
57     int MAXIMUM_NUMBER_OF_INITIALIZATION_STATUS_CUSTOM_ERROR = 2;
58 
59     /**
60      * Returns the maximum number of initialization status for some application specific failed
61      * reasons.
62      *
63      * Note: The value 0 is reserved for success.
64      */
getMaxCustomInitializationStatus()65     static int getMaxCustomInitializationStatus() {
66         return MAXIMUM_NUMBER_OF_INITIALIZATION_STATUS_CUSTOM_ERROR;
67     }
68 
69     /**
70      * Creates a {@link IntConsumer} that sends the initialization status to the
71      * {@link VoiceInteractionService} via {@link IRemoteCallback}.
72      *
73      * @hide
74      */
createInitializationStatusConsumer(IRemoteCallback callback)75     static IntConsumer createInitializationStatusConsumer(IRemoteCallback callback) {
76         IntConsumer intConsumer = null;
77         if (callback != null) {
78             intConsumer =
79                     value -> {
80                         if (value > SandboxedDetectionInitializer
81                                 .getMaxCustomInitializationStatus()) {
82                             throw new IllegalArgumentException(
83                                     "The initialization status is invalid for " + value);
84                         }
85                         try {
86                             Bundle status = new Bundle();
87                             status.putInt(KEY_INITIALIZATION_STATUS, value);
88                             callback.sendResult(status);
89                         } catch (RemoteException e) {
90                             throw e.rethrowFromSystemServer();
91                         }
92                     };
93         }
94         return intConsumer;
95     }
96 
97     /**
98      * Called when sandboxed detectors that extend {@link HotwordDetector} are created or
99      * {@link HotwordDetector#updateState(PersistableBundle, SharedMemory)} requests an
100      * update of the sandboxed detection parameters.
101      *
102      * @param options Application configuration data to provide to sandboxed detection services.
103      * PersistableBundle does not allow any remotable objects or other contents that can be used to
104      * communicate with other processes.
105      * @param sharedMemory The unrestricted data blob to provide to sandboxed detection services.
106      * Use this to provide model data or other such data to the trusted process.
107      * @param callbackTimeoutMillis Timeout in milliseconds for the operation to invoke the
108      * statusCallback.
109      * @param statusCallback Use this to return the updated result; the allowed values are
110      * {@link #INITIALIZATION_STATUS_SUCCESS}, 1<->{@link #getMaxCustomInitializationStatus()}.
111      * This is non-null only when sandboxed detection services are being initialized; and it
112      * is null if the state is updated after that.
113      */
onUpdateState( @ullable PersistableBundle options, @Nullable SharedMemory sharedMemory, @DurationMillisLong long callbackTimeoutMillis, @Nullable IntConsumer statusCallback)114     void onUpdateState(
115             @Nullable PersistableBundle options,
116             @Nullable SharedMemory sharedMemory,
117             @DurationMillisLong long callbackTimeoutMillis,
118             @Nullable IntConsumer statusCallback);
119 }
120