diff options
3 files changed, 49 insertions, 28 deletions
diff --git a/core/java/android/app/appfunctions/AppFunctionManager.java b/core/java/android/app/appfunctions/AppFunctionManager.java index 8944bb9c9c4c..74cae07d8911 100644 --- a/core/java/android/app/appfunctions/AppFunctionManager.java +++ b/core/java/android/app/appfunctions/AppFunctionManager.java @@ -50,29 +50,40 @@ import java.util.function.Consumer; * <p>**Building App Functions:** * * <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". + * offers a more convenient and type-safe way to build app functions. The SDK provides predefined + * function schemas for common use cases and associated data classes for function parameters and + * return values. Apps only have to implement the provided interfaces. Internally, the SDK converts + * these data classes into {@link ExecuteAppFunctionRequest#getParameters()} and + * {@link ExecuteAppFunctionResponse#getResultDocument()}. * - * <p>The suggested way to build an app function is to use the AppFunctions SDK. The SDK provides - * custom data classes (AppFunctions Schemas) and handles the conversion to the underlying {@link - * android.app.appsearch.GenericDocument}/{@link android.os.Bundle} format used in {@link - * ExecuteAppFunctionRequest} and {@link ExecuteAppFunctionResponse}. - * - * <p>**Discovering (Listing) App Functions:** + * <p>**Discovering App Functions:** * * <p>When there is a package change or the device starts up, the metadata of available functions is - * indexed on-device by {@link AppSearchManager}. AppSearch stores the indexed information as a - * {@code AppFunctionStaticMetadata} document. This allows other apps and the app itself to discover - * these functions using the AppSearch search APIs. Visibility to this metadata document is based on - * the packages that have visibility to the app providing the app functions. + * indexed on-device by {@link AppSearchManager}. AppSearch stores the indexed information as an + * {@code AppFunctionStaticMetadata} document. This document contains the {@code functionIdentifier} + * and the schema information that the app function implements. This allows other apps and the app + * itself to discover these functions using the AppSearch search APIs. Visibility to this metadata + * document is based on the packages that have visibility to the app providing the app functions. + * AppFunction SDK provides a convenient way to achieve this and is the preferred method. * * <p>**Executing App Functions:** * - * <p>Requests to execute a function are built using the {@link ExecuteAppFunctionRequest} class. - * Callers need the {@code android.permission.EXECUTE_APP_FUNCTIONS} or {@code - * android.permission.EXECUTE_APP_FUNCTIONS_TRUSTED} permission to execute app functions from other - * apps. An app has automatic visibility to its own functions and doesn't need these permissions to - * call its own functions via {@code AppFunctionManager}. + * <p>To execute an app function, the caller app can retrieve the {@code functionIdentifier} from + * the {@code AppFunctionStaticMetadata} document and use it to build an + * {@link ExecuteAppFunctionRequest}. Then, invoke {@link #executeAppFunction} with the request + * to execute the app function. Callers need the {@code android.permission.EXECUTE_APP_FUNCTIONS} + * or {@code android.permission.EXECUTE_APP_FUNCTIONS_TRUSTED} permission to execute app + * functions from other apps. An app can always execute its own app functions and doesn't need these + * permissions. AppFunction SDK provides a convenient way to achieve this and is the preferred + * method. + * + * <p>**Example:** + * + * <p>An assistant app is trying to fulfill the user request "Save XYZ into my note". The assistant + * app should first list all available app functions as {@code AppFunctionStaticMetadata} documents + * from AppSearch. Then, it should identify an app function that implements the {@code CreateNote} + * schema. Finally, the assistant app can invoke {@link #executeAppFunction} with the {@code + * functionIdentifier} of the chosen function. */ @FlaggedApi(FLAG_ENABLE_APP_FUNCTION_MANAGER) @SystemService(Context.APP_FUNCTION_SERVICE) diff --git a/core/java/android/app/appfunctions/ExecuteAppFunctionRequest.java b/core/java/android/app/appfunctions/ExecuteAppFunctionRequest.java index 4c5e8c130a73..41bb62270e9f 100644 --- a/core/java/android/app/appfunctions/ExecuteAppFunctionRequest.java +++ b/core/java/android/app/appfunctions/ExecuteAppFunctionRequest.java @@ -114,18 +114,14 @@ public final class ExecuteAppFunctionRequest implements Parcelable { * <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. + * @see AppFunctionManager on how to determine the expected parameters. */ @NonNull public GenericDocument getParameters() { return mParameters.getValue(); } - /** Returns the additional data relevant to this function execution. */ + /** Returns the additional metadata for this function execution request. */ @NonNull public Bundle getExtras() { return mExtras; @@ -153,19 +149,31 @@ public final class ExecuteAppFunctionRequest implements Parcelable { @NonNull private GenericDocument mParameters = new GenericDocument.Builder<>("", "", "").build(); + /** + * Creates a new instance of this builder class. + * + * @param targetPackageName The package name of the target app providing the app function to + * invoke. + * @param functionIdentifier The identifier used by the {@link AppFunctionService} from the + * target app to uniquely identify the function to be invoked. + */ public Builder(@NonNull String targetPackageName, @NonNull String functionIdentifier) { mTargetPackageName = Objects.requireNonNull(targetPackageName); mFunctionIdentifier = Objects.requireNonNull(functionIdentifier); } - /** Sets the additional data relevant to this function execution. */ + /** Sets the additional metadata for this function execution request. */ @NonNull public Builder setExtras(@NonNull Bundle extras) { mExtras = Objects.requireNonNull(extras); return this; } - /** Sets the function parameters. */ + /** + * Sets the function parameters. + * + * @see #ExecuteAppFunctionRequest#getParameters() + */ @NonNull public Builder setParameters(@NonNull GenericDocument parameters) { Objects.requireNonNull(parameters); diff --git a/core/java/android/app/appfunctions/ExecuteAppFunctionResponse.java b/core/java/android/app/appfunctions/ExecuteAppFunctionResponse.java index c907ef114286..83453a9d1c71 100644 --- a/core/java/android/app/appfunctions/ExecuteAppFunctionResponse.java +++ b/core/java/android/app/appfunctions/ExecuteAppFunctionResponse.java @@ -156,7 +156,7 @@ public final class ExecuteAppFunctionResponse implements Parcelable { * Returns a successful response. * * @param resultDocument The return value of the executed function. - * @param extras The additional metadata data relevant to this function execution response. + * @param extras The additional metadata for this function execution response. */ @NonNull @FlaggedApi(FLAG_ENABLE_APP_FUNCTION_MANAGER) @@ -174,7 +174,7 @@ public final class ExecuteAppFunctionResponse implements Parcelable { * Returns a failure response. * * @param resultCode The result code of the app function execution. - * @param extras The additional metadata data relevant to this function execution response. + * @param extras The additional metadata for this function execution response. * @param errorMessage The error message associated with the result, if any. */ @NonNull @@ -216,13 +216,15 @@ public final class ExecuteAppFunctionResponse implements Parcelable { * // Do something with the returnValue * } * </pre> + * + * @see AppFunctionManager on how to determine the expected function return. */ @NonNull public GenericDocument getResultDocument() { return mResultDocumentWrapper.getValue(); } - /** Returns the extras of the app function execution. */ + /** Returns the additional metadata for this function execution response. */ @NonNull public Bundle getExtras() { return mExtras; |