Merge "Update AppFunction sidecar lib Documentation" into main (6fe280bd) · Commits · e / os / android_frameworks_base

core/java/android/app/appfunctions/AppFunctionManager.java

+3 −3

Original line number	Diff line number	Diff line
		@@ -47,10 +47,10 @@ import java.util.function.Consumer;
		* <p>An app function is a piece of functionality that apps expose to the system for cross-app
		* orchestration.
		*
		* <p>Developer Workflow:
		* <p>Building App Functions:
		*
		* <p>Most developers should interact with app functions through the AppFunctions SDK. This SDK
		* library offers a more convenient and type-safe way to represent the inputs and outputs of an app
		* <p>Most developers should build app functions through the AppFunctions SDK. This SDK library
		* offers a more convenient and type-safe way to represent the inputs and outputs of an app
		* function, using custom data classes called "AppFunction Schemas".
		*
		* <p>The suggested way to build an app function is to use the AppFunctions SDK. The SDK provides

libs/appfunctions/java/com/google/android/appfunctions/sidecar/AppFunctionManager.java

+10 −38

Original line number	Diff line number	Diff line
		@@ -16,7 +16,6 @@

		package com.google.android.appfunctions.sidecar;

		import android.Manifest;
		import android.annotation.CallbackExecutor;
		import android.annotation.IntDef;
		import android.annotation.NonNull;
		@@ -41,8 +40,6 @@ import java.util.function.Consumer;
		* <p>This class wraps {@link android.app.appfunctions.AppFunctionManager} functionalities and
		* exposes it here as a sidecar library (avoiding direct dependency on the platform API).
		*/
		// TODO(b/357551503): Implement get and set enabled app function APIs.
		// TODO(b/367329899): Add sidecar library to Android B builds.
		public final class AppFunctionManager {
		/**
		* The default state of the app function. Call {@link #setAppFunctionEnabled} with this to reset
		@@ -102,6 +99,9 @@ public final class AppFunctionManager {
		* <p>Proxies request and response to the underlying {@link
		* android.app.appfunctions.AppFunctionManager#executeAppFunction}, converting the request and
		* response in the appropriate type required by the function.
		*
		* <p>See {@link android.app.appfunctions.AppFunctionManager#executeAppFunction} for the
		* documented behaviour of this method.
		*/
		public void executeAppFunction(
		@NonNull ExecuteAppFunctionRequest sidecarRequest,
		@@ -128,24 +128,8 @@ public final class AppFunctionManager {
		/**
		* Returns a boolean through a callback, indicating whether the app function is enabled.
		*
		* <p>* This method can only check app functions owned by the caller, or those where the caller
		* has visibility to the owner package and holds either the {@link
		* Manifest.permission#EXECUTE_APP_FUNCTIONS} or {@link
		* Manifest.permission#EXECUTE_APP_FUNCTIONS_TRUSTED} permission.
		*
		* <p>If operation fails, the callback's {@link OutcomeReceiver#onError} is called with errors:
		*
		* <ul>
		* <li>{@link IllegalArgumentException}, if the function is not found or the caller does not
		* have access to it.
		* </ul>
		*
		* @param functionIdentifier the identifier of the app function to check (unique within the
		* target package) and in most cases, these are automatically generated by the AppFunctions
		* SDK
		* @param targetPackage the package name of the app function's owner
		* @param executor the executor to run the request
		* @param callback the callback to receive the function enabled check result
		* <p>See {@link android.app.appfunctions.AppFunctionManager#isAppFunctionEnabled} for the
		* documented behaviour of this method.
		*/
		public void isAppFunctionEnabled(
		@NonNull String functionIdentifier,
		@@ -158,20 +142,8 @@ public final class AppFunctionManager {
		/**
		* Sets the enabled state of the app function owned by the calling package.
		*
		* <p>If operation fails, the callback's {@link OutcomeReceiver#onError} is called with errors:
		*
		* <ul>
		* <li>{@link IllegalArgumentException}, if the function is not found or the caller does not
		* have access to it.
		* </ul>
		*
		* @param functionIdentifier the identifier of the app function to enable (unique within the
		* calling package). In most cases, identifiers are automatically generated by the
		* AppFunctions SDK
		* @param newEnabledState the new state of the app function
		* @param executor the executor to run the callback
		* @param callback the callback to receive the result of the function enablement. The call was
		* successful if no exception was thrown.
		* <p>See {@link android.app.appfunctions.AppFunctionManager#setAppFunctionEnabled} for the
		* documented behavoir of this method.
		*/
		// Constants in @EnabledState should always mirror those in
		// android.app.appfunctions.AppFunctionManager.

libs/appfunctions/java/com/google/android/appfunctions/sidecar/ExecuteAppFunctionRequest.java

+22 −9

Original line number	Diff line number	Diff line
		@@ -34,8 +34,8 @@ public final class ExecuteAppFunctionRequest {
		@NonNull private final String mTargetPackageName;

		/**
		* Returns the unique string identifier of the app function to be executed. TODO(b/357551503):
		* Document how callers can get the available function identifiers.
		* The unique string identifier of the app function to be executed. This identifier is used to
		* execute a specific app function.
		*/
		@NonNull private final String mFunctionIdentifier;

		@@ -49,8 +49,6 @@ public final class ExecuteAppFunctionRequest {
		*
		* <p>The document may have missing parameters. Developers are advised to implement defensive
		* handling measures.
		*
		* <p>TODO(b/357551503): Document how function parameters can be obtained for function execution
		*/
		@NonNull private final GenericDocument mParameters;

		@@ -71,7 +69,19 @@ public final class ExecuteAppFunctionRequest {
		return mTargetPackageName;
		}

		/** Returns the unique string identifier of the app function to be executed. */
		/**
		* Returns the unique string identifier of the app function to be executed.
		*
		* <p>When there is a package change or the device starts up, the metadata of available
		* functions is indexed by AppSearch. AppSearch stores the indexed information as {@code
		* AppFunctionStaticMetadata} document.
		*
		* <p>The ID can be obtained by querying the {@code AppFunctionStaticMetadata} documents from
		* AppSearch.
		*
		* <p>If the {@code functionId} provided is invalid, the caller will get an invalid argument
		* response.
		*/
		@NonNull
		public String getFunctionIdentifier() {
		return mFunctionIdentifier;
		@@ -83,6 +93,12 @@ public final class ExecuteAppFunctionRequest {
		*
		* <p>The bundle may have missing parameters. Developers are advised to implement defensive
		* handling measures.
		*
		* <p>Similar to {@link #getFunctionIdentifier()} the parameters required by a function can be
		* obtained by querying AppSearch for the corresponding {@code AppFunctionStaticMetadata}. This
		* metadata will contain enough information for the caller to resolve the required parameters
		* either using information from the metadata itself or using the AppFunction SDK for function
		* callers.
		*/
		@NonNull
		public GenericDocument getParameters() {
		@@ -128,10 +144,7 @@ public final class ExecuteAppFunctionRequest {
		@NonNull
		public ExecuteAppFunctionRequest build() {
		return new ExecuteAppFunctionRequest(
		mTargetPackageName,
		mFunctionIdentifier,
		mExtras,
		mParameters);
		mTargetPackageName, mFunctionIdentifier, mExtras, mParameters);
		}
		}
		}

libs/appfunctions/java/com/google/android/appfunctions/sidecar/ExecuteAppFunctionResponse.java

+6 −5

Original line number	Diff line number	Diff line
		@@ -56,14 +56,15 @@ public final class ExecuteAppFunctionResponse {
		/** The caller does not have the permission to execute an app function. */
		public static final int RESULT_DENIED = 1;

		/** An unknown error occurred while processing the call in the AppFunctionService. */
		public static final int RESULT_APP_UNKNOWN_ERROR = 2;

		/**
		* An internal error occurred within AppFunctionManagerService.
		* An unknown error occurred while processing the call in the AppFunctionService.
		*
		* <p>This error may be considered similar to {@link IllegalStateException}
		* <p>This error is thrown when the service is connected in the remote application but an
		* unexpected error is thrown from the bound application.
		*/
		public static final int RESULT_APP_UNKNOWN_ERROR = 2;

		/** An internal unexpected error coming from the system. */
		public static final int RESULT_INTERNAL_ERROR = 3;

		/**