| /* |
| * Copyright (C) 2014 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 android.app; |
| |
| import android.annotation.SystemApi; |
| import android.content.Context; |
| import android.os.Bundle; |
| import android.os.IBinder; |
| import android.os.Looper; |
| import android.os.Message; |
| import android.os.RemoteException; |
| import android.util.ArrayMap; |
| import android.util.Log; |
| import com.android.internal.app.IVoiceInteractor; |
| import com.android.internal.app.IVoiceInteractorCallback; |
| import com.android.internal.app.IVoiceInteractorRequest; |
| import com.android.internal.os.HandlerCaller; |
| import com.android.internal.os.SomeArgs; |
| |
| import java.util.ArrayList; |
| |
| /** |
| * @hide |
| * Interface for an {@link Activity} to interact with the user through voice. Use |
| * {@link android.app.Activity#getVoiceInteractor() Activity.getVoiceInteractor} |
| * to retrieve the interface, if the activity is currently involved in a voice interaction. |
| * |
| * <p>The voice interactor revolves around submitting voice interaction requests to the |
| * back-end voice interaction service that is working with the user. These requests are |
| * submitted with {@link #submitRequest}, providing a new instance of a |
| * {@link Request} subclass describing the type of operation to perform -- currently the |
| * possible requests are {@link ConfirmationRequest} and {@link CommandRequest}. |
| * |
| * <p>Once a request is submitted, the voice system will process it and eventually deliver |
| * the result to the request object. The application can cancel a pending request at any |
| * time. |
| * |
| * <p>The VoiceInteractor is integrated with Activity's state saving mechanism, so that |
| * if an activity is being restarted with retained state, it will retain the current |
| * VoiceInteractor and any outstanding requests. Because of this, you should always use |
| * {@link Request#getActivity() Request.getActivity} to get back to the activity of a |
| * request, rather than holding on to the activity instance yourself, either explicitly |
| * or implicitly through a non-static inner class. |
| */ |
| @SystemApi |
| public class VoiceInteractor { |
| static final String TAG = "VoiceInteractor"; |
| static final boolean DEBUG = true; |
| |
| final IVoiceInteractor mInteractor; |
| |
| Context mContext; |
| Activity mActivity; |
| |
| final HandlerCaller mHandlerCaller; |
| final HandlerCaller.Callback mHandlerCallerCallback = new HandlerCaller.Callback() { |
| @Override |
| public void executeMessage(Message msg) { |
| SomeArgs args = (SomeArgs)msg.obj; |
| Request request; |
| switch (msg.what) { |
| case MSG_CONFIRMATION_RESULT: |
| request = pullRequest((IVoiceInteractorRequest)args.arg1, true); |
| if (DEBUG) Log.d(TAG, "onConfirmResult: req=" |
| + ((IVoiceInteractorRequest)args.arg1).asBinder() + "/" + request |
| + " confirmed=" + msg.arg1 + " result=" + args.arg2); |
| if (request != null) { |
| ((ConfirmationRequest)request).onConfirmationResult(msg.arg1 != 0, |
| (Bundle) args.arg2); |
| request.clear(); |
| } |
| break; |
| case MSG_COMPLETE_VOICE_RESULT: |
| request = pullRequest((IVoiceInteractorRequest)args.arg1, true); |
| if (DEBUG) Log.d(TAG, "onCompleteVoice: req=" |
| + ((IVoiceInteractorRequest)args.arg1).asBinder() + "/" + request |
| + " result=" + args.arg1); |
| if (request != null) { |
| ((CompleteVoiceRequest)request).onCompleteResult((Bundle) args.arg2); |
| request.clear(); |
| } |
| break; |
| case MSG_ABORT_VOICE_RESULT: |
| request = pullRequest((IVoiceInteractorRequest)args.arg1, true); |
| if (DEBUG) Log.d(TAG, "onAbortVoice: req=" |
| + ((IVoiceInteractorRequest)args.arg1).asBinder() + "/" + request |
| + " result=" + args.arg1); |
| if (request != null) { |
| ((AbortVoiceRequest)request).onAbortResult((Bundle) args.arg2); |
| request.clear(); |
| } |
| break; |
| case MSG_COMMAND_RESULT: |
| request = pullRequest((IVoiceInteractorRequest)args.arg1, msg.arg1 != 0); |
| if (DEBUG) Log.d(TAG, "onCommandResult: req=" |
| + ((IVoiceInteractorRequest)args.arg1).asBinder() + "/" + request |
| + " result=" + args.arg2); |
| if (request != null) { |
| ((CommandRequest)request).onCommandResult((Bundle) args.arg2); |
| if (msg.arg1 != 0) { |
| request.clear(); |
| } |
| } |
| break; |
| case MSG_CANCEL_RESULT: |
| request = pullRequest((IVoiceInteractorRequest)args.arg1, true); |
| if (DEBUG) Log.d(TAG, "onCancelResult: req=" |
| + ((IVoiceInteractorRequest)args.arg1).asBinder() + "/" + request); |
| if (request != null) { |
| request.onCancel(); |
| request.clear(); |
| } |
| break; |
| } |
| } |
| }; |
| |
| final IVoiceInteractorCallback.Stub mCallback = new IVoiceInteractorCallback.Stub() { |
| @Override |
| public void deliverConfirmationResult(IVoiceInteractorRequest request, boolean confirmed, |
| Bundle result) { |
| mHandlerCaller.sendMessage(mHandlerCaller.obtainMessageIOO( |
| MSG_CONFIRMATION_RESULT, confirmed ? 1 : 0, request, result)); |
| } |
| |
| @Override |
| public void deliverCompleteVoiceResult(IVoiceInteractorRequest request, Bundle result) { |
| mHandlerCaller.sendMessage(mHandlerCaller.obtainMessageOO( |
| MSG_COMPLETE_VOICE_RESULT, request, result)); |
| } |
| |
| @Override |
| public void deliverAbortVoiceResult(IVoiceInteractorRequest request, Bundle result) { |
| mHandlerCaller.sendMessage(mHandlerCaller.obtainMessageOO( |
| MSG_ABORT_VOICE_RESULT, request, result)); |
| } |
| |
| @Override |
| public void deliverCommandResult(IVoiceInteractorRequest request, boolean complete, |
| Bundle result) { |
| mHandlerCaller.sendMessage(mHandlerCaller.obtainMessageIOO( |
| MSG_COMMAND_RESULT, complete ? 1 : 0, request, result)); |
| } |
| |
| @Override |
| public void deliverCancel(IVoiceInteractorRequest request) throws RemoteException { |
| mHandlerCaller.sendMessage(mHandlerCaller.obtainMessageO( |
| MSG_CANCEL_RESULT, request)); |
| } |
| }; |
| |
| final ArrayMap<IBinder, Request> mActiveRequests = new ArrayMap<IBinder, Request>(); |
| |
| static final int MSG_CONFIRMATION_RESULT = 1; |
| static final int MSG_COMPLETE_VOICE_RESULT = 2; |
| static final int MSG_ABORT_VOICE_RESULT = 3; |
| static final int MSG_COMMAND_RESULT = 4; |
| static final int MSG_CANCEL_RESULT = 5; |
| |
| public static abstract class Request { |
| IVoiceInteractorRequest mRequestInterface; |
| Context mContext; |
| Activity mActivity; |
| |
| public Request() { |
| } |
| |
| public void cancel() { |
| try { |
| mRequestInterface.cancel(); |
| } catch (RemoteException e) { |
| Log.w(TAG, "Voice interactor has died", e); |
| } |
| } |
| |
| public Context getContext() { |
| return mContext; |
| } |
| |
| public Activity getActivity() { |
| return mActivity; |
| } |
| |
| public void onCancel() { |
| } |
| |
| public void onAttached(Activity activity) { |
| } |
| |
| public void onDetached() { |
| } |
| |
| void clear() { |
| mRequestInterface = null; |
| mContext = null; |
| mActivity = null; |
| } |
| |
| abstract IVoiceInteractorRequest submit(IVoiceInteractor interactor, |
| String packageName, IVoiceInteractorCallback callback) throws RemoteException; |
| } |
| |
| public static class ConfirmationRequest extends Request { |
| final CharSequence mPrompt; |
| final Bundle mExtras; |
| |
| /** |
| * Confirms an operation with the user via the trusted system |
| * VoiceInteractionService. This allows an Activity to complete an unsafe operation that |
| * would require the user to touch the screen when voice interaction mode is not enabled. |
| * The result of the confirmation will be returned through an asynchronous call to |
| * either {@link #onConfirmationResult(boolean, android.os.Bundle)} or |
| * {@link #onCancel()}. |
| * |
| * <p>In some cases this may be a simple yes / no confirmation or the confirmation could |
| * include context information about how the action will be completed |
| * (e.g. booking a cab might include details about how long until the cab arrives) |
| * so the user can give a confirmation. |
| * @param prompt Optional confirmation text to read to the user as the action being |
| * confirmed. |
| * @param extras Additional optional information. |
| */ |
| public ConfirmationRequest(CharSequence prompt, Bundle extras) { |
| mPrompt = prompt; |
| mExtras = extras; |
| } |
| |
| public void onConfirmationResult(boolean confirmed, Bundle result) { |
| } |
| |
| IVoiceInteractorRequest submit(IVoiceInteractor interactor, String packageName, |
| IVoiceInteractorCallback callback) throws RemoteException { |
| return interactor.startConfirmation(packageName, callback, mPrompt, mExtras); |
| } |
| } |
| |
| public static class CompleteVoiceRequest extends Request { |
| final CharSequence mMessage; |
| final Bundle mExtras; |
| |
| /** |
| * Reports that the current interaction was successfully completed with voice, so the |
| * application can report the final status to the user. When the response comes back, the |
| * voice system has handled the request and is ready to switch; at that point the |
| * application can start a new non-voice activity or finish. Be sure when starting the new |
| * activity to use {@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK |
| * Intent.FLAG_ACTIVITY_NEW_TASK} to keep the new activity out of the current voice |
| * interaction task. |
| * |
| * @param message Optional message to tell user about the completion status of the task. |
| * @param extras Additional optional information. |
| */ |
| public CompleteVoiceRequest(CharSequence message, Bundle extras) { |
| mMessage = message; |
| mExtras = extras; |
| } |
| |
| public void onCompleteResult(Bundle result) { |
| } |
| |
| IVoiceInteractorRequest submit(IVoiceInteractor interactor, String packageName, |
| IVoiceInteractorCallback callback) throws RemoteException { |
| return interactor.startCompleteVoice(packageName, callback, mMessage, mExtras); |
| } |
| } |
| |
| public static class AbortVoiceRequest extends Request { |
| final CharSequence mMessage; |
| final Bundle mExtras; |
| |
| /** |
| * Reports that the current interaction can not be complete with voice, so the |
| * application will need to switch to a traditional input UI. Applications should |
| * only use this when they need to completely bail out of the voice interaction |
| * and switch to a traditional UI. When the response comes back, the voice |
| * system has handled the request and is ready to switch; at that point the application |
| * can start a new non-voice activity. Be sure when starting the new activity |
| * to use {@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK |
| * Intent.FLAG_ACTIVITY_NEW_TASK} to keep the new activity out of the current voice |
| * interaction task. |
| * |
| * @param message Optional message to tell user about not being able to complete |
| * the interaction with voice. |
| * @param extras Additional optional information. |
| */ |
| public AbortVoiceRequest(CharSequence message, Bundle extras) { |
| mMessage = message; |
| mExtras = extras; |
| } |
| |
| public void onAbortResult(Bundle result) { |
| } |
| |
| IVoiceInteractorRequest submit(IVoiceInteractor interactor, String packageName, |
| IVoiceInteractorCallback callback) throws RemoteException { |
| return interactor.startAbortVoice(packageName, callback, mMessage, mExtras); |
| } |
| } |
| |
| public static class CommandRequest extends Request { |
| final String mCommand; |
| final Bundle mArgs; |
| |
| /** |
| * Execute a command using the trusted system VoiceInteractionService. |
| * This allows an Activity to request additional information from the user needed to |
| * complete an action (e.g. booking a table might have several possible times that the |
| * user could select from or an app might need the user to agree to a terms of service). |
| * The result of the confirmation will be returned through an asynchronous call to |
| * either {@link #onCommandResult(android.os.Bundle)} or |
| * {@link #onCancel()}. |
| * |
| * <p>The command is a string that describes the generic operation to be performed. |
| * The command will determine how the properties in extras are interpreted and the set of |
| * available commands is expected to grow over time. An example might be |
| * "com.google.voice.commands.REQUEST_NUMBER_BAGS" to request the number of bags as part of |
| * airline check-in. (This is not an actual working example.) |
| * |
| * @param command The desired command to perform. |
| * @param args Additional arguments to control execution of the command. |
| */ |
| public CommandRequest(String command, Bundle args) { |
| mCommand = command; |
| mArgs = args; |
| } |
| |
| public void onCommandResult(Bundle result) { |
| } |
| |
| IVoiceInteractorRequest submit(IVoiceInteractor interactor, String packageName, |
| IVoiceInteractorCallback callback) throws RemoteException { |
| return interactor.startCommand(packageName, callback, mCommand, mArgs); |
| } |
| } |
| |
| VoiceInteractor(IVoiceInteractor interactor, Context context, Activity activity, |
| Looper looper) { |
| mInteractor = interactor; |
| mContext = context; |
| mActivity = activity; |
| mHandlerCaller = new HandlerCaller(context, looper, mHandlerCallerCallback, true); |
| } |
| |
| Request pullRequest(IVoiceInteractorRequest request, boolean complete) { |
| synchronized (mActiveRequests) { |
| Request req = mActiveRequests.get(request.asBinder()); |
| if (req != null && complete) { |
| mActiveRequests.remove(request.asBinder()); |
| } |
| return req; |
| } |
| } |
| |
| private ArrayList<Request> makeRequestList() { |
| final int N = mActiveRequests.size(); |
| if (N < 1) { |
| return null; |
| } |
| ArrayList<Request> list = new ArrayList<Request>(N); |
| for (int i=0; i<N; i++) { |
| list.add(mActiveRequests.valueAt(i)); |
| } |
| return list; |
| } |
| |
| void attachActivity(Activity activity) { |
| if (mActivity == activity) { |
| return; |
| } |
| mContext = activity; |
| mActivity = activity; |
| ArrayList<Request> reqs = makeRequestList(); |
| if (reqs != null) { |
| for (int i=0; i<reqs.size(); i++) { |
| Request req = reqs.get(i); |
| req.mContext = activity; |
| req.mActivity = activity; |
| req.onAttached(activity); |
| } |
| } |
| } |
| |
| void detachActivity() { |
| ArrayList<Request> reqs = makeRequestList(); |
| if (reqs != null) { |
| for (int i=0; i<reqs.size(); i++) { |
| Request req = reqs.get(i); |
| req.onDetached(); |
| req.mActivity = null; |
| req.mContext = null; |
| } |
| } |
| mContext = null; |
| mActivity = null; |
| } |
| |
| public boolean submitRequest(Request request) { |
| try { |
| IVoiceInteractorRequest ireq = request.submit(mInteractor, |
| mContext.getOpPackageName(), mCallback); |
| request.mRequestInterface = ireq; |
| request.mContext = mContext; |
| request.mActivity = mActivity; |
| synchronized (mActiveRequests) { |
| mActiveRequests.put(ireq.asBinder(), request); |
| } |
| return true; |
| } catch (RemoteException e) { |
| Log.w(TAG, "Remove voice interactor service died", e); |
| return false; |
| } |
| } |
| |
| /** |
| * Queries the supported commands available from the VoiceinteractionService. |
| * The command is a string that describes the generic operation to be performed. |
| * An example might be "com.google.voice.commands.REQUEST_NUMBER_BAGS" to request the number |
| * of bags as part of airline check-in. (This is not an actual working example.) |
| * |
| * @param commands |
| */ |
| public boolean[] supportsCommands(String[] commands) { |
| try { |
| boolean[] res = mInteractor.supportsCommands(mContext.getOpPackageName(), commands); |
| if (DEBUG) Log.d(TAG, "supportsCommands: cmds=" + commands + " res=" + res); |
| return res; |
| } catch (RemoteException e) { |
| throw new RuntimeException("Voice interactor has died", e); |
| } |
| } |
| } |
