VoiceInteractionSession

SHOW_SOURCE_ACTIVITY

int SHOW_SOURCE_ACTIVITY

Flag for use with onShow(Bundle, int): indicates that an Activity has invoked the voice interaction service for a local interaction using startLocalVoiceInteraction(Bundle).

Constant Value: 16 (0x00000010)

SHOW_SOURCE_APPLICATION

int SHOW_SOURCE_APPLICATION

Flag for use with onShow(Bundle, int): indicates that the application itself has invoked the assistant.

Constant Value: 8 (0x00000008)

SHOW_SOURCE_ASSIST_GESTURE

int SHOW_SOURCE_ASSIST_GESTURE

Flag for use with onShow(Bundle, int): indicates that the session has been started from the system assist gesture.

Constant Value: 4 (0x00000004)

SHOW_WITH_ASSIST

int SHOW_WITH_ASSIST

Flag received in onShow(Bundle, int): originator requested that the session be started with assist data from the currently focused activity.

Constant Value: 1 (0x00000001)

SHOW_WITH_SCREENSHOT

int SHOW_WITH_SCREENSHOT

Flag received in onShow(Bundle, int): originator requested that the session be started with a screen shot of the currently focused activity.

Constant Value: 2 (0x00000002)

VoiceInteractionSession

VoiceInteractionSession (Context context)

VoiceInteractionSession

VoiceInteractionSession (Context context, 
                Handler handler)

closeSystemDialogs

void closeSystemDialogs ()

Request that all system dialogs (and status bar shade etc) be closed, allowing access to the session's UI. This will not cause the lock screen to be dismissed.

dump

void dump (String prefix, 
                FileDescriptor fd, 
                PrintWriter writer, 
                String[] args)

Print the Service's state into the given stream. This gets invoked by VoiceInteractionSessionService when its Service dump(FileDescriptor, PrintWriter, String[]) method is called.

finish

void finish ()

Finish the session. This completely destroys the session -- the next time it is shown, an entirely new one will be created. You do not normally call this function; instead, use hide() and allow the system to destroy your session if it needs its RAM.

getContext

Context getContext ()

getDisabledShowContext

int getDisabledShowContext ()

Equivalent to VoiceInteractionService.getDisabledShowContext.

getLayoutInflater

LayoutInflater getLayoutInflater ()

Convenience for inflating views.

getUserDisabledShowContext

int getUserDisabledShowContext ()

Return which show context flags have been disabled by the user through the system settings UI, so the session will never get this data. Returned flags are any combination of VoiceInteractionSession.SHOW_WITH_ASSIST and VoiceInteractionSession.SHOW_WITH_SCREENSHOT. Note that this only tells you about global user settings, not about restrictions that may be applied contextual based on the current application the user is in or other transient states.

getWindow

Dialog getWindow ()

Retrieve the window being used to show the session's UI.

hide

void hide ()

Hide the session's UI, if currently shown. Call this when you are done with your user interaction.

onAssistStructureFailure

void onAssistStructureFailure (Throwable failure)

Called when there has been a failure transferring the AssistStructure to the assistant. This may happen, for example, if the data is too large and results in an out of memory exception, or the client has provided corrupt data. This will be called immediately before onHandleAssist(Bundle, AssistStructure, AssistContent) and the AssistStructure supplied there afterwards will be null.

onBackPressed

void onBackPressed ()

Called when the user presses the back button while focus is in the session UI. Note that this will only happen if the session UI has requested input focus in its window; otherwise, the back key will go to whatever window has focus and do whatever behavior it normally has there. The default implementation simply calls hide().

onCancelRequest

void onCancelRequest (VoiceInteractionSession.Request request)

Called when the VoiceInteractor has asked to cancel a VoiceInteractionSession.Request that was previously delivered to onRequestConfirmation(VoiceInteractionSession.ConfirmationRequest), onRequestPickOption(VoiceInteractionSession.PickOptionRequest), onRequestCompleteVoice(VoiceInteractionSession.CompleteVoiceRequest), onRequestAbortVoice(VoiceInteractionSession.AbortVoiceRequest), or onRequestCommand(VoiceInteractionSession.CommandRequest).

onCloseSystemDialogs

void onCloseSystemDialogs ()

Sessions automatically watch for requests that all system UI be closed (such as when the user presses HOME), which will appear here. The default implementation always calls hide().

onComputeInsets

void onComputeInsets (VoiceInteractionSession.Insets outInsets)

Compute the interesting insets into your UI. The default implementation sets outInsets.contentInsets.top to the height of the window, meaning it should not adjust content underneath. The default touchable insets are TOUCHABLE_INSETS_FRAME, meaning it consumes all touch events within its window frame.

onConfigurationChanged

void onConfigurationChanged (Configuration newConfig)

Called by the system when the device configuration changes while your component is running. Note that, unlike activities, other components are never restarted when a configuration changes: they must always deal with the results of the change, such as by re-retrieving resources.

At the time that this function has been called, your Resources object will have been updated to return resource values matching the new configuration.

For more information, read Handling Runtime Changes.

onCreate

void onCreate ()

Initiatize a new session. At this point you don't know exactly what this session will be used for; you will find that out in onShow(Bundle, int).

onCreateContentView

View onCreateContentView ()

Hook in which to create the session's UI.

onDestroy

void onDestroy ()

Last callback to the session as it is being finished.

onGetSupportedCommands

boolean[] onGetSupportedCommands (String[] commands)

Request to query for what extended commands the session supports.

onHandleAssist

void onHandleAssist (Bundle data, 
                AssistStructure structure, 
                AssistContent content)

Called to receive data from the application that the user was currently viewing when an assist session is started. If the original show request did not specify SHOW_WITH_ASSIST, this method will not be called.

onHandleAssistSecondary

void onHandleAssistSecondary (Bundle data, 
                AssistStructure structure, 
                AssistContent content, 
                int index, 
                int count)

Called to receive data from other applications that the user was or is interacting with, that are currently on the screen in a multi-window display environment, not including the currently focused activity. This could be a free-form window, a picture-in-picture window, or another window in a split-screen display.

This method is very similar to onHandleAssist(Bundle, AssistStructure, AssistContent) except that it is called for additional non-focused activities along with an index and count that indicates which additional activity the data is for. index will be between 1 and count-1 and this method is called once for each additional window, in no particular order. The count indicates how many windows to expect assist data for, including the top focused activity, which continues to be returned via onHandleAssist(Bundle, AssistStructure, AssistContent).

To be responsive to assist requests, process assist data as soon as it is received, without waiting for all queued activities to return assist data.

onHandleScreenshot

void onHandleScreenshot (Bitmap screenshot)

Called to receive a screenshot of what the user was currently viewing when an assist session is started. May be null if screenshots are disabled by the user, policy, or application. If the original show request did not specify SHOW_WITH_SCREENSHOT, this method will not be called.

onHide

void onHide ()

Called immediately after stopping to show the session UI.

onKeyDown

boolean onKeyDown (int keyCode, 
                KeyEvent event)

Called when a key down event has occurred. If you return true, you can first call KeyEvent.startTracking() to have the framework track the event through its onKeyUp(int, KeyEvent) and also call your onKeyLongPress(int, KeyEvent) if it occurs.

onKeyLongPress

boolean onKeyLongPress (int keyCode, 
                KeyEvent event)

Called when a long press has occurred. If you return true, the final key up will have FLAG_CANCELED and FLAG_CANCELED_LONG_PRESS set. Note that in order to receive this callback, someone in the event change must return true from onKeyDown(int, KeyEvent) and call startTracking() on the event.

onKeyMultiple

boolean onKeyMultiple (int keyCode, 
                int count, 
                KeyEvent event)

Called when multiple down/up pairs of the same key have occurred in a row.

onKeyUp

boolean onKeyUp (int keyCode, 
                KeyEvent event)

Called when a key up event has occurred.

onLockscreenShown

void onLockscreenShown ()

Called when the lockscreen was shown.

onLowMemory

void onLowMemory ()

This is called when the overall system is running low on memory, and actively running processes should trim their memory usage. While the exact point at which this will be called is not defined, generally it will happen when all background process have been killed. That is, before reaching the point of killing processes hosting service and foreground UI that we would like to avoid killing.

You should implement this method to release any caches or other unnecessary resources you may be holding on to. The system will perform a garbage collection for you after returning from this method.

Preferably, you should implement onTrimMemory(int) from ComponentCallbacks2 to incrementally unload your resources based on various levels of memory demands. That API is available for API level 14 and higher, so you should only use this onLowMemory() method as a fallback for older versions, which can be treated the same as onTrimMemory(int) with the TRIM_MEMORY_COMPLETE level.

onRequestAbortVoice

void onRequestAbortVoice (VoiceInteractionSession.AbortVoiceRequest request)

Request to abort the voice interaction session because the voice activity can not complete its interaction using voice. Corresponds to VoiceInteractor.AbortVoiceRequest. The default implementation just sends an empty confirmation back to allow the activity to exit.

onRequestCommand

void onRequestCommand (VoiceInteractionSession.CommandRequest request)

Process an arbitrary extended command from the caller, corresponding to a VoiceInteractor.CommandRequest.

onRequestCompleteVoice

void onRequestCompleteVoice (VoiceInteractionSession.CompleteVoiceRequest request)

Request to complete the voice interaction session because the voice activity successfully completed its interaction using voice. Corresponds to VoiceInteractor.CompleteVoiceRequest. The default implementation just sends an empty confirmation back to allow the activity to exit.

onRequestConfirmation

void onRequestConfirmation (VoiceInteractionSession.ConfirmationRequest request)

Request to confirm with the user before proceeding with an unrecoverable operation, corresponding to a VoiceInteractor.ConfirmationRequest.

onRequestPickOption

void onRequestPickOption (VoiceInteractionSession.PickOptionRequest request)

Request for the user to pick one of N options, corresponding to a VoiceInteractor.PickOptionRequest.

onShow

void onShow (Bundle args, 
                int showFlags)

Called when the session UI is going to be shown. This is called after onCreateContentView() (if the session's content UI needed to be created) and immediately prior to the window being shown. This may be called while the window is already shown, if a show request has come in while it is shown, to allow you to update the UI to match the new show arguments.

onTaskFinished

void onTaskFinished (Intent intent, 
                int taskId)

Called when the last activity of a task initiated by startVoiceActivity(android.content.Intent) has finished. The default implementation calls finish() on the assumption that this represents the completion of a voice action. You can override the implementation if you would like a different behavior.

onTaskStarted

void onTaskStarted (Intent intent, 
                int taskId)

Called when a task initiated by startVoiceActivity(android.content.Intent) has actually started.

onTrimMemory

void onTrimMemory (int level)

Called when the operating system has determined that it is a good time for a process to trim unneeded memory from its process. This will happen for example when it goes in the background and there is not enough memory to keep as many background processes running as desired. You should never compare to exact values of the level, since new intermediate values may be added -- you will typically want to compare if the value is greater or equal to a level you are interested in.

To retrieve the processes current trim level at any point, you can use ActivityManager.getMyMemoryState(RunningAppProcessInfo).

setContentView

void setContentView (View view)

setDisabledShowContext

void setDisabledShowContext (int flags)

Equivalent to VoiceInteractionService.setDisabledShowContext(int).

setKeepAwake

void setKeepAwake (boolean keepAwake)

Set whether this session will keep the device awake while it is running a voice activity. By default, the system holds a wake lock for it while in this state, so that it can work even if the screen is off. Setting this to false removes that wake lock, allowing the CPU to go to sleep. This is typically used if the session decides it has been waiting too long for a response from the user and doesn't want to let this continue to drain the battery.

Passing false here will release the wake lock, and you can call later with true to re-acquire it. It will also be automatically re-acquired for you each time you start a new voice activity task -- that is when you call startVoiceActivity(Intent).

setTheme

void setTheme (int theme)

You can call this to customize the theme used by your IME's window. This must be set before onCreate(), so you will typically call it in your constructor with the resource ID of your custom theme.

show

void show (Bundle args, 
                int flags)

Show the UI for this session. This asks the system to go through the process of showing your UI, which will eventually culminate in onShow(Bundle, int). This is similar to calling VoiceInteractionService.showSession.

startVoiceActivity

void startVoiceActivity (Intent intent)

Ask that a new activity be started for voice interaction. This will create a new dedicated task in the activity manager for this voice interaction session; this means that Intent.FLAG_ACTIVITY_NEW_TASK will be set for you to make it a new task.

The newly started activity will be displayed to the user in a special way, as a layer under the voice interaction UI.

As the voice activity runs, it can retrieve a VoiceInteractor through which it can perform voice interactions through your session. These requests for voice interactions will appear as callbacks on onGetSupportedCommands(String[]), onRequestConfirmation(VoiceInteractionSession.ConfirmationRequest), onRequestPickOption(VoiceInteractionSession.PickOptionRequest), onRequestCompleteVoice(VoiceInteractionSession.CompleteVoiceRequest), onRequestAbortVoice(VoiceInteractionSession.AbortVoiceRequest), or onRequestCommand(VoiceInteractionSession.CommandRequest)

You will receive a call to onTaskStarted(Intent, int) when the task starts up and onTaskFinished(Intent, int) when the last activity has finished.