VoiceInteractionSession

An active voice interaction session, providing a facility for the implementation
to interact with the user in the voice interaction layer. The user interface is
initially shown by default, and can be created be overriding onCreateContentView()
in which the UI can be built.

A voice interaction session can be self-contained, ultimately calling finish()
when done. It can also initiate voice interactions with applications by calling
startVoiceActivity(Intent)

Level for onTrimMemory(int): the process is around the middle
of the background LRU list; freeing memory can help the system keep
other processes running later in the list for better overall performance.

Level for onTrimMemory(int): the process is not an expendable
background process, but the device is running extremely low on memory
and is about to not be able to keep any background processes running.

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.

Causes the current thread to wait until another thread invokes the
notify() method or the
notifyAll() method for this object, or
some other thread interrupts the current thread, or a certain
amount of real time has elapsed.

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.

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.

onAssistStructureFailure

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.

Parameters

failure

Throwable: The failure exception that was thrown when building the
AssistStructure.

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().

onConfigurationChanged

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.

Return an array of booleans indicating which of each entry in the
command array is supported. A true entry in the array indicates the command
is supported; false indicates it is not. The default implementation returns
an array of all false entries.

onHandleAssist

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.

Parameters

data

Bundle: Arbitrary data supplied by the app through
Activity.onProvideAssistData.
May be null if assist data has been disabled by the user or device policy.

structure

AssistStructure: If available, the structure definition of all windows currently
displayed by the app. May be null if assist data has been disabled by the user
or device policy; will be an empty stub if the application has disabled assist
by marking its window as secure.

content

AssistContent: Additional content data supplied by the app through
Activity.onProvideAssistContent.
May be null if assist data has been disabled by the user or device policy; will
not be automatically filled in with data from the app if the app has marked its
window as secure.

onHandleAssistSecondary

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.

Parameters

data

Bundle: Arbitrary data supplied by the app through
Activity.onProvideAssistData.
May be null if assist data has been disabled by the user or device policy.

structure

AssistStructure: If available, the structure definition of all windows currently
displayed by the app. May be null if assist data has been disabled by the user
or device policy; will be an empty stub if the application has disabled assist
by marking its window as secure.

content

AssistContent: Additional content data supplied by the app through
Activity.onProvideAssistContent.
May be null if assist data has been disabled by the user or device policy; will
not be automatically filled in with data from the app if the app has marked its
window as secure.

onHandleScreenshot

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.

onLockscreenShown

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.

onRequestAbortVoice

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.

onRequestCompleteVoice

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.

onShow

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

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.

onTrimMemory

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.

setKeepAwake

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).

startAssistantActivity

Ask that a new assistant activity be started. This will create a new task in the
in activity manager: 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 on top of other activities in the system
in a new layer that is not affected by multi-window mode. Tasks started from this activity
will go into the normal activity layer and not this new layer.

startVoiceActivity

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.