Update AppFunction Documentation
Flag: android.app.appfunctions.flags.enable_app_function_manager
Test: Existing CTS
Bug: 375121362
Change-Id: I6c6c88215a6a4ae4c17f3cae120eb6dc2238cf57
diff --git a/core/java/android/app/appfunctions/AppFunctionManager.java b/core/java/android/app/appfunctions/AppFunctionManager.java
index dca4336..a82c6ba7 100644
--- a/core/java/android/app/appfunctions/AppFunctionManager.java
+++ b/core/java/android/app/appfunctions/AppFunctionManager.java
@@ -47,7 +47,6 @@
* <p>App function is a specific piece of functionality that an app offers to the system. These
* functionalities can be integrated into various system features.
*/
-// TODO(b/357551503): Implement get and set enabled app function APIs.
@FlaggedApi(FLAG_ENABLE_APP_FUNCTION_MANAGER)
@SystemService(Context.APP_FUNCTION_SERVICE)
public final class AppFunctionManager {
@@ -111,17 +110,19 @@
* @param request the request to execute the app function
* @param executor the executor to run the callback
* @param cancellationSignal the cancellation signal to cancel the execution.
- * @param callback the callback to receive the function execution result. if the calling app
- * does not own the app function or does not have {@code
+ * @param callback the callback to receive the function execution result.
+ * <p>If the calling app does not own the app function or does not have {@code
* android.permission.EXECUTE_APP_FUNCTIONS_TRUSTED} or {@code
* android.permission.EXECUTE_APP_FUNCTIONS}, the execution result will contain {@code
* ExecuteAppFunctionResponse.RESULT_DENIED}.
+ * <p>If the caller only has {@code android.permission.EXECUTE_APP_FUNCTIONS} but the
+ * function requires {@code android.permission.EXECUTE_APP_FUNCTIONS_TRUSTED}, the execution
+ * result will contain {@code ExecuteAppFunctionResponse.RESULT_DENIED}
+ * <p>If the function requested for execution is disabled, then the execution result will
+ * contain {@code ExecuteAppFunctionResponse.RESULT_DISABLED}
+ * <p>If the cancellation signal is issued, the operation is cancelled and no response is
+ * returned to the caller.
*/
- // TODO(b/357551503): Document the behavior when the cancellation signal is issued.
- // TODO(b/360864791): Document that apps can opt-out from being executed by callers with
- // EXECUTE_APP_FUNCTIONS and how a caller knows whether a function is opted out.
- // TODO(b/357551503): Update documentation when get / set APIs are implemented that this will
- // also return RESULT_DENIED if the app function is disabled.
@RequiresPermission(
anyOf = {
Manifest.permission.EXECUTE_APP_FUNCTIONS_TRUSTED,
diff --git a/core/java/android/app/appfunctions/ExecuteAppFunctionRequest.java b/core/java/android/app/appfunctions/ExecuteAppFunctionRequest.java
index fe7fd88..4c5e8c1 100644
--- a/core/java/android/app/appfunctions/ExecuteAppFunctionRequest.java
+++ b/core/java/android/app/appfunctions/ExecuteAppFunctionRequest.java
@@ -50,12 +50,12 @@
}
};
- /** Returns the package name of the app that hosts the function. */
+ /** Returns the package name of the app that hosts/owns the function. */
@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;
@@ -69,8 +69,6 @@
*
* <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 GenericDocumentWrapper mParameters;
@@ -91,7 +89,19 @@
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;
@@ -103,6 +113,12 @@
*
* <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() {
diff --git a/core/java/android/app/appfunctions/ExecuteAppFunctionResponse.java b/core/java/android/app/appfunctions/ExecuteAppFunctionResponse.java
index a879b1b..c907ef1 100644
--- a/core/java/android/app/appfunctions/ExecuteAppFunctionResponse.java
+++ b/core/java/android/app/appfunctions/ExecuteAppFunctionResponse.java
@@ -79,14 +79,15 @@
/** 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. */
+ /**
+ * An unknown error occurred while processing the call in the AppFunctionService.
+ *
+ * <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 error occurred within AppFunctionManagerService.
- *
- * <p>This error may be considered similar to {@link IllegalStateException}
- */
+ /** An internal unexpected error coming from the system. */
public static final int RESULT_INTERNAL_ERROR = 3;
/**