Added in API level 36

Summary: Constants | Methods | Inherited Methods

AppFunctionManager

Kotlin |Java

public final class AppFunctionManager
extends Object

java.lang.Object
↳	android.app.appfunctions.AppFunctionManager

Provides access to App Functions.

See android.app.appfunctions for a comprehensive overview of App Functions.

Summary

Constants
`int`	`APP_FUNCTION_STATE_DEFAULT` The default state of the app function.
`int`	`APP_FUNCTION_STATE_DISABLED` The app function is disabled.
`int`	`APP_FUNCTION_STATE_ENABLED` The app function is enabled.

Public methods
`void`	`executeAppFunction(ExecuteAppFunctionRequest request, Executor executor, CancellationSignal cancellationSignal, OutcomeReceiver<ExecuteAppFunctionResponse, AppFunctionException> callback)` Executes the app function.
`void`	`getAppFunctionActivityStates(Set<AppFunctionActivityId> activityIds, Executor executor, OutcomeReceiver<List<AppFunctionActivityState>, Exception> callback)` Retrieves the registered app functions for the specified activities.
`void`	`getAppFunctionStates(List<AppFunctionName> appFunctionNames, Executor executor, OutcomeReceiver<List<AppFunctionState>, Exception> callback)` Retrieves the runtime state of the specified app functions.
`void`	`isAppFunctionEnabled(String functionIdentifier, Executor executor, OutcomeReceiver<Boolean, Exception> callback)` Retrieves whether an app function owned by the calling package is enabled (allows execution).
`void`	`isAppFunctionEnabled(String functionIdentifier, String targetPackage, Executor executor, OutcomeReceiver<Boolean, Exception> callback)` Retrieves whether an app function is enabled (allows execution).
`AppFunctionObservation`	`observeAppFunctions(Executor executor, AppFunctionObserver appFunctionObserver)` Registers an observer to monitor changes to app functions within packages that the caller can query.
`AppFunctionRegistration`	`registerAppFunction(String functionIdentifier, Executor executor, AppFunction appFunction)` Registers a runtime implementation for an app function, that can be executed using `executeAppFunction(ExecuteAppFunctionRequest, Executor, CancellationSignal, OutcomeReceiver)`.
`AppFunctionRegistration`	`registerAppFunctions(List<RegisterAppFunctionRequest> requests)` Registers several `AppFunction` implementations at once, sharing a single lifecycle.
`void`	`searchAppFunctions(AppFunctionSearchSpec searchSpec, Executor executor, OutcomeReceiver<List<AppFunctionMetadata>, Exception> callback)` Searches app function `AppFunctionMetadata`s.
`void`	`setAppFunctionEnabled(String functionIdentifier, int newEnabledState, Executor executor, OutcomeReceiver<Void, Exception> callback)` Sets the enabled state of the app function owned by the calling package.

Inherited methods

From class


        
          java.lang.Object

`Object`	`clone()` Creates and returns a copy of this object.
`boolean`	`equals(Object obj)` Indicates whether some other object is "equal to" this one.
`void`	`finalize()` Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
`final Class<?>`	`getClass()` Returns the runtime class of this `Object`.
`int`	`hashCode()` Returns a hash code value for the object.
`final void`	`notify()` Wakes up a single thread that is waiting on this object's monitor.
`final void`	`notifyAll()` Wakes up all threads that are waiting on this object's monitor.
`String`	`toString()` Returns a string representation of the object.
`final void`	`wait(long timeoutMillis, int nanos)` Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
`final void`	`wait(long timeoutMillis)` Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
`final void`	`wait()` Causes the current thread to wait until it is awakened, typically by being notified or interrupted.

Constants

APP_FUNCTION_STATE_DEFAULT

Added in API level 36

public static final int APP_FUNCTION_STATE_DEFAULT

The default state of the app function.

To reset the enabled state to the default value, call setAppFunctionEnabled(String, int, Executor, OutcomeReceiver) with this value.

Constant Value: 0 (0x00000000)

APP_FUNCTION_STATE_DISABLED

Added in API level 36

public static final int APP_FUNCTION_STATE_DISABLED

The app function is disabled.

To disable an app function, call setAppFunctionEnabled(String, int, Executor, OutcomeReceiver) with this value.

Constant Value: 2 (0x00000002)

APP_FUNCTION_STATE_ENABLED

Added in API level 36

public static final int APP_FUNCTION_STATE_ENABLED

The app function is enabled.

To enable an app function, call setAppFunctionEnabled(String, int, Executor, OutcomeReceiver) with this value.

Constant Value: 1 (0x00000001)

Public methods

executeAppFunction

Added in API level 36

public void executeAppFunction (ExecuteAppFunctionRequest request, 
                Executor executor, 
                CancellationSignal cancellationSignal, 
                OutcomeReceiver<ExecuteAppFunctionResponse, AppFunctionException> callback)

Executes the app function.

Applications can execute functions they define. To execute functions defined in another component, the caller must have the Manifest.permission.EXECUTE_APP_FUNCTIONS or ERROR(Manifest.permission.EXECUTE_APP_FUNCTIONS_SYSTEM/android.Manifest.permission#EXECUTE_APP_FUNCTIONS_SYSTEM Manifest.permission.EXECUTE_APP_FUNCTIONS_SYSTEM) permissions.

A function can only be executed while its AppFunctionState.isEnabled is true.

See AppFunctionException for possible failures.

Parameters
`request`	`ExecuteAppFunctionRequest`: the request to execute the app function. This value cannot be `null`.
`executor`	`Executor`: the executor to run the callback. This value cannot be `null`. Callback and listener events are dispatched through this `Executor`, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use `Context.getMainExecutor()`. Otherwise, provide an `Executor` that dispatches to an appropriate thread.
`cancellationSignal`	`CancellationSignal`: the cancellation signal to cancel the execution. This value cannot be `null`.
`callback`	`OutcomeReceiver`: the callback to receive the function execution result or error. This value cannot be `null`.

getAppFunctionActivityStates

Added in API level 37

public void getAppFunctionActivityStates (Set<AppFunctionActivityId> activityIds, 
                Executor executor, 
                OutcomeReceiver<List<AppFunctionActivityState>, Exception> callback)

Retrieves the registered app functions for the specified activities.

Each AppFunctionActivityState contains the set of registered AppFunctionNames associated with a requested AppFunctionActivityId.

Functions that do not exist or are not visible to the calling application will be silently omitted from the result. Requested activities that have no registered functions will be omitted from the result.

See AppFunctionActivityId for potential usages, including conversion from VoiceInteractionSession.ActivityId.

This method follows the same permission rules as searchAppFunctions(AppFunctionSearchSpec, Executor, OutcomeReceiver).

See getAppFunctionStates(List, Executor, OutcomeReceiver) for retrieving the runtime state of app functions based on their names.

See searchAppFunctions(AppFunctionSearchSpec, Executor, OutcomeReceiver) on how to retrieve the AppFunctionMetadata of app functions.

See observeAppFunctions(Executor, AppFunctionObserver) for observing changes to app functions' AppFunctionMetadata and AppFunctionStates.

Parameters
`activityIds`	`Set`: The set of activity IDs to retrieve function states for. This value cannot be `null`.
`executor`	`Executor`: The executor to run the callback. This value cannot be `null`. Callback and listener events are dispatched through this `Executor`, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use `Context.getMainExecutor()`. Otherwise, provide an `Executor` that dispatches to an appropriate thread.
`callback`	`OutcomeReceiver`: The callback to receive the list of activity states. This value cannot be `null`.

See also:

VoiceInteractionSession.getAppFunctionActivityId(ActivityId)

getAppFunctionStates

Added in API level 37

public void getAppFunctionStates (List<AppFunctionName> appFunctionNames, 
                Executor executor, 
                OutcomeReceiver<List<AppFunctionState>, Exception> callback)

Retrieves the runtime state of the specified app functions.

This includes runtime-changing properties such as whether the functions are currently enabled or disabled. Functions that do not exist or are not visible to the calling application will be silently omitted from the result list.

This method follows the same permission rules as searchAppFunctions(AppFunctionSearchSpec, Executor, OutcomeReceiver).

See getAppFunctionActivityStates(Set, Executor, OutcomeReceiver) for retrieving the states of app functions associated with a specific activity.

See searchAppFunctions(AppFunctionSearchSpec, Executor, OutcomeReceiver) on how to retrieve the AppFunctionMetadata of app functions.

See observeAppFunctions(Executor, AppFunctionObserver) for observing changes to app functions' AppFunctionMetadata and AppFunctionStates.

Parameters
`appFunctionNames`	`List`: The names of the app functions to request the state for. This value cannot be `null`.
`executor`	`Executor`: The executor to run the callback. This value cannot be `null`. Callback and listener events are dispatched through this `Executor`, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use `Context.getMainExecutor()`. Otherwise, provide an `Executor` that dispatches to an appropriate thread.
`callback`	`OutcomeReceiver`: The callback to receive the function state result. This value cannot be `null`.

isAppFunctionEnabled

Added in API level 36

public void isAppFunctionEnabled (String functionIdentifier, 
                Executor executor, 
                OutcomeReceiver<Boolean, Exception> callback)

Retrieves whether an app function owned by the calling package is enabled (allows execution).

Same as isAppFunctionEnabled(String,String,Executor,OutcomeReceiver) but only for checking functions owned by the calling package.

This is equivalent to calling getAppFunctionStates(List, Executor, OutcomeReceiver) and checking the AppFunctionState.isEnabled property of the result. Consider using getAppFunctionStates(List, Executor, OutcomeReceiver) to get the full state of the app function.

Parameters
`functionIdentifier`	`String`: the identifier of the app function to check (unique within the target package). This value cannot be `null`.
`executor`	`Executor`: the executor to run the request. This value cannot be `null`.
`callback`	`OutcomeReceiver`: the callback to receive the function enabled check result. This value cannot be `null`.

isAppFunctionEnabled

Added in API level 36

public void isAppFunctionEnabled (String functionIdentifier, 
                String targetPackage, 
                Executor executor, 
                OutcomeReceiver<Boolean, Exception> callback)

Retrieves whether an app function is enabled (allows execution).

If the operation fails, the callback's OutcomeReceiver.onError is called with errors:

IllegalArgumentException, if the function is not found or the caller does not have access to it.

Parameters
`functionIdentifier`	`String`: the identifier of the app function to check (unique within the target package). This value cannot be `null`.
`targetPackage`	`String`: the package name of the app function's owner. This value cannot be `null`.
`executor`	`Executor`: the executor to run the request. This value cannot be `null`.
`callback`	`OutcomeReceiver`: the callback to receive the function enabled check result. This value cannot be `null`.

See also:

AppFunctionState.isEnabled

observeAppFunctions

Added in API level 37

public AppFunctionObservation observeAppFunctions (Executor executor, 
                AppFunctionObserver appFunctionObserver)

Registers an observer to monitor changes to app functions within packages that the caller can query.

The caller should retain a reference to the returned AppFunctionObservation, and call AppFunctionObservation.cancel when observation is no longer required.

The callback is only triggered by changes after its registration. Any changes that occur before the registration are not reported.

An example usage flow is:

Call observeAppFunctions(Executor, AppFunctionObserver), to start monitoring app function changes, using the AppFunctionObserver.
Call searchAppFunctions(AppFunctionSearchSpec, Executor, OutcomeReceiver) and getAppFunctionStates(List, Executor, OutcomeReceiver) to get the initial list of app functions and their states.
In AppFunctionObserver.onAppFunctionMetadataChanged, call searchAppFunctions(AppFunctionSearchSpec, Executor, OutcomeReceiver) with a AppFunctionSearchSpec that matches the changed packages to get the updated metadata.
In AppFunctionObserver.onAppFunctionStatesChanged, call getAppFunctionStates(List, Executor, OutcomeReceiver) with the list of AppFunctionNames that matches the changed functions to get the updated states.
Note that this is guaranteed to trigger after AppFunctionObserver.onAppFunctionMetadataChanged for new functions or functions that also changed states, so there's no need to call getAppFunctionStates(List, Executor, OutcomeReceiver) in AppFunctionObserver.onAppFunctionMetadataChanged.

Parameters

Parameters
`executor`	`Executor`: the executor to run the `AppFunctionObserver` callbacks. This value cannot be `null`. Callback and listener events are dispatched through this `Executor`, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use `Context.getMainExecutor()`. Otherwise, provide an `Executor` that dispatches to an appropriate thread.
`appFunctionObserver`	`AppFunctionObserver`: the observer to receive updates to registered app functions. This value cannot be `null`.

executor

Executor: the executor to run the AppFunctionObserver callbacks.
This value cannot be null.
Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.

appFunctionObserver

AppFunctionObserver: the observer to receive updates to registered app functions.
This value cannot be null.

Returns
`AppFunctionObservation`	An `AppFunctionObservation` used to cancel this observation. This value cannot be `null`.

registerAppFunction

Added in API level 37

public AppFunctionRegistration registerAppFunction (String functionIdentifier, 
                Executor executor, 
                AppFunction appFunction)

Registers a runtime implementation for an app function, that can be executed using executeAppFunction(ExecuteAppFunctionRequest, Executor, CancellationSignal, OutcomeReceiver).

executeAppFunction(ExecuteAppFunctionRequest, Executor, CancellationSignal, OutcomeReceiver) targeting an app function provided by this method will trigger the ERROR(AppFunction.onExecute/android.app.appfunctions.AppFunction#onExecute AppFunction.onExecute) method of the provided implementation, as long as the process registering it is not frozen, and the Context registering it is not destroyed (at which point the registration will be removed).

You must declare the app function in your AndroidManifest.xml using an application-level <property> named android.app.appfunctions. See AppFunctionMetadata for details on the XML schema (your_app_functions.xml in the example below).

Example manifest declaration:

<application ...>
   <property
       android:name="android.app.appfunctions.v2"
       android:value="your_app_functions.xml" />
   ...
 </application>

Function implementations can only be registered from Activity or Service contexts. If registering from an Activity, strongly consider AppFunctionMetadata.SCOPE_ACTIVITY for your function definition.

The functionIdentifier must correspond to an app function declared in your app's application-level XML assets. If the identifier is not found, this method will throw an IllegalArgumentException. Attempting to register a duplicate function based on the rules of AppFunctionMetadata.getScope will throw an IllegalStateException.

To register multiple functions at once, consider using registerAppFunctions(List) as a more efficient alternative.

The system holds a strong reference to the provided AppFunction implementation as long as it is registered. To prevent memory leaks and ensure the system is aware that the function is no longer available, you must explicitly call AppFunctionRegistration.unregister when the function is no longer relevant (e.g., in Activity.onStop() or before Service.stopForeground(boolean)).

Parameters
`functionIdentifier`	`String`: The unique identifier for the function, which must match an entry in the app's XML resource declarations. This value cannot be `null`.
`executor`	`Executor`: The `Executor` on which the function will be invoked. This value cannot be `null`.
`appFunction`	`AppFunction`: The `AppFunction` implementation to be executed when the function is triggered. This value cannot be `null`.

Returns
`AppFunctionRegistration`	A `AppFunctionRegistration` object that can be used to unregister the function. This value cannot be `null`.

Throws
`IllegalArgumentException`	if the provided `functionIdentifier` is not declared in the app's application-level XML resources or if an activity-scoped function is registered from a non-Activity context.
`IllegalStateException`	if a duplicate function is already registered (see `AppFunctionMetadata.getScope`), or if not called from `Activity` or `Service` contexts.

registerAppFunctions

Added in API level 37

public AppFunctionRegistration registerAppFunctions (List<RegisterAppFunctionRequest> requests)

Registers several AppFunction implementations at once, sharing a single lifecycle.

This is a more efficient alternative to calling registerAppFunction(String, Executor, AppFunction) multiple times.

Behavior and Lifecycle

Each function registered through this method follows the same execution and lifecycle rules as those registered with registerAppFunction(String, Executor, AppFunction).

Batch Operation and Atomicity

The registration is atomic: either all functions in the provided list are registered successfully, or none are. If any function in the list fails validation (e.g., its is already registered or not declared in the manifest), this method will throw an exception, and no functions from the batch will be registered. Each function in the request follows the scoping rules declared in the app's XML resources.

A single AppFunctionRegistration object is returned, which can be used to unregister the entire batch of functions with one call.

Parameters
`requests`	`List`: A list of `RegisterAppFunctionRequest` objects, each specifying a function to be registered. This value cannot be `null`.

Returns
`AppFunctionRegistration`	A single `AppFunctionRegistration` object that can be used to unregister all the functions in the batch with one call. This value cannot be `null`.

Throws
`IllegalArgumentException`	if any `RegisterAppFunctionRequest.getFunctionIdentifier` is not declared in the app's application-level XML assets or the `requests` list is empty.
`IllegalStateException`	if any function in the `requests` list is already registered by this app.

searchAppFunctions

Added in API level 37

public void searchAppFunctions (AppFunctionSearchSpec searchSpec, 
                Executor executor, 
                OutcomeReceiver<List<AppFunctionMetadata>, Exception> callback)

Searches app function AppFunctionMetadatas.

Note that the state is not guaranteed to be the latest, as metadata can change between request and execute times when apps are updated.

The calling app can search for:

Functions in its own package (no permission required).
When holding the Manifest.permission.EXECUTE_APP_FUNCTIONS or ERROR(Manifest.permission.DISCOVER_APP_FUNCTIONS/android.Manifest.permission#DISCOVER_APP_FUNCTIONS Manifest.permission.DISCOVER_APP_FUNCTIONS) or ERROR(Manifest.permission.EXECUTE_APP_FUNCTIONS_SYSTEM/android.Manifest.permission#EXECUTE_APP_FUNCTIONS_SYSTEM Manifest.permission.EXECUTE_APP_FUNCTIONS_SYSTEM) permission - functions in other packages that it is allowed to query via PackageManager.canPackageQuery(String, String).

See getAppFunctionStates(List, Executor, OutcomeReceiver) and getAppFunctionActivityStates(Set, Executor, OutcomeReceiver) on how to retrieve the runtime state of app functions.

See observeAppFunctions(Executor, AppFunctionObserver) for observing changes to app functions' AppFunctionMetadata and AppFunctionStates.

Parameters
`searchSpec`	`AppFunctionSearchSpec`: The spec of app functions to search for. This value cannot be `null`.
`executor`	`Executor`: The executor to run the callback. This value cannot be `null`. Callback and listener events are dispatched through this `Executor`, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use `Context.getMainExecutor()`. Otherwise, provide an `Executor` that dispatches to an appropriate thread.
`callback`	`OutcomeReceiver`: The callback to receive the search results. This value cannot be `null`.

setAppFunctionEnabled

Added in API level 36

public void setAppFunctionEnabled (String functionIdentifier, 
                int newEnabledState, 
                Executor executor, 
                OutcomeReceiver<Void, Exception> callback)

Sets the enabled state of the app function owned by the calling package.

Important: This method only applies to functions backed by an AppFunctionService. It cannot be used to modify the state of functions registered at runtime. For runtime-registered app functions, use registerAppFunction(String, Executor, AppFunction) to register them and AppFunctionRegistration.unregister to unregister them instead.

Parameters
`functionIdentifier`	`String`: the identifier of the app function to enable (unique within the calling package). This value cannot be `null`.
`newEnabledState`	`int`: the new state of the app function. Value is one of the following: `APP_FUNCTION_STATE_DEFAULT` `APP_FUNCTION_STATE_ENABLED` `APP_FUNCTION_STATE_DISABLED`
`executor`	`Executor`: the executor to run the callback. This value cannot be `null`.
`callback`	`OutcomeReceiver`: the callback to receive the result of the function enablement. Can return `IllegalArgumentException` if the function is not found or the caller does not have access to it. This value cannot be `null`.

Throws
`IllegalArgumentException`	if the function is runtime-registered.