Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 8b1d9fee authored by Oluwarotimi Adesina's avatar Oluwarotimi Adesina Committed by Desh
Browse files

Update AppFunction sidecar lib Documentation 

Flag: android.app.appfunctions.flags.enable_app_function_manager
Test: Existing CTS
Bug: 375121362
Change-Id: I565a875ed7966ce3b5f2b0e261ee26822bb0caca
parent cd4bc44f

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;



    /**