Add Error categories for AppFunction exe response (3ead6206) · Commits · e / os / android_frameworks_base

core/api/current.txt

+11 −6

Original line number	Diff line number	Diff line
		@@ -8816,6 +8816,7 @@ package android.app.appfunctions {

		@FlaggedApi("android.app.appfunctions.flags.enable_app_function_manager") public final class ExecuteAppFunctionResponse implements android.os.Parcelable {
		method public int describeContents();
		method public int getErrorCategory();
		method @Nullable public String getErrorMessage();
		method @NonNull public android.os.Bundle getExtras();
		method public int getResultCode();
		@@ -8825,13 +8826,17 @@ package android.app.appfunctions {
		method @FlaggedApi("android.app.appfunctions.flags.enable_app_function_manager") @NonNull public static android.app.appfunctions.ExecuteAppFunctionResponse newSuccess(@NonNull android.app.appsearch.GenericDocument, @Nullable android.os.Bundle);
		method public void writeToParcel(@NonNull android.os.Parcel, int);
		field @NonNull public static final android.os.Parcelable.Creator<android.app.appfunctions.ExecuteAppFunctionResponse> CREATOR;
		field public static final int ERROR_CATEGORY_APP = 3; // 0x3
		field public static final int ERROR_CATEGORY_REQUEST_ERROR = 1; // 0x1
		field public static final int ERROR_CATEGORY_SYSTEM = 2; // 0x2
		field public static final int ERROR_CATEGORY_UNKNOWN = 0; // 0x0
		field public static final String PROPERTY_RETURN_VALUE = "returnValue";
		field public static final int RESULT_APP_UNKNOWN_ERROR = 2; // 0x2
		field public static final int RESULT_CANCELLED = 6; // 0x6
		field public static final int RESULT_DENIED = 1; // 0x1
		field public static final int RESULT_DISABLED = 5; // 0x5
		field public static final int RESULT_INTERNAL_ERROR = 3; // 0x3
		field public static final int RESULT_INVALID_ARGUMENT = 4; // 0x4
		field public static final int RESULT_APP_UNKNOWN_ERROR = 3000; // 0xbb8
		field public static final int RESULT_CANCELLED = 2001; // 0x7d1
		field public static final int RESULT_DENIED = 1000; // 0x3e8
		field public static final int RESULT_DISABLED = 1002; // 0x3ea
		field public static final int RESULT_INTERNAL_ERROR = 2000; // 0x7d0
		field public static final int RESULT_INVALID_ARGUMENT = 1001; // 0x3e9
		field public static final int RESULT_OK = 0; // 0x0
		}

core/java/android/app/appfunctions/ExecuteAppFunctionResponse.java

+119 −14

Original line number	Diff line number	Diff line
		@@ -73,38 +73,97 @@ public final class ExecuteAppFunctionResponse implements Parcelable {
		*/
		public static final String PROPERTY_RETURN_VALUE = "returnValue";

		/** The call was successful. */
		/**
		* The call was successful.
		*
		* <p>This result code does not belong in an error category.
		*/
		public static final int RESULT_OK = 0;

		/** The caller does not have the permission to execute an app function. */
		public static final int RESULT_DENIED = 1;
		/**
		* The caller does not have the permission to execute an app function.
		*
		* <p>This error is in the {@link #ERROR_CATEGORY_REQUEST_ERROR} category.
		*/
		public static final int RESULT_DENIED = 1000;

		/**
		* The caller supplied invalid arguments to the execution request.
		*
		* <p>This error may be considered similar to {@link IllegalArgumentException}.
		*
		* <p>This error is in the {@link #ERROR_CATEGORY_REQUEST_ERROR} category.
		*/
		public static final int RESULT_INVALID_ARGUMENT = 1001;

		/**
		* The caller tried to execute a disabled app function.
		*
		* <p>This error is in the request error category.
		*
		* <p>This error is in the {@link #ERROR_CATEGORY_REQUEST_ERROR} category.
		*/
		public static final int RESULT_DISABLED = 1002;

		/**
		* An internal unexpected error coming from the system.
		*
		* <p>This error is in the {@link #ERROR_CATEGORY_SYSTEM} category.
		*/
		public static final int RESULT_INTERNAL_ERROR = 2000;

		/**
		* The operation was cancelled. Use this error code to report that a cancellation is done after
		* receiving a cancellation signal.
		*
		* <p>This error is in the {@link #ERROR_CATEGORY_SYSTEM} category.
		*/
		public static final int RESULT_CANCELLED = 2001;

		/**
		* 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.
		*
		* <p>This error is in the {@link #ERROR_CATEGORY_APP} category.
		*/
		public static final int RESULT_APP_UNKNOWN_ERROR = 2;
		public static final int RESULT_APP_UNKNOWN_ERROR = 3000;

		/** An internal unexpected error coming from the system. */
		public static final int RESULT_INTERNAL_ERROR = 3;
		/**
		* The error category is unknown.
		*
		* <p>This is the default value for {@link #getErrorCategory}.
		*/
		public static final int ERROR_CATEGORY_UNKNOWN = 0;

		/**
		* The caller supplied invalid arguments to the call.
		* The error is caused by the app requesting a function execution.
		*
		* <p>This error may be considered similar to {@link IllegalArgumentException}.
		* <p>For example, the caller provided invalid parameters in the execution request e.g. an
		* invalid function ID.
		*
		* <p>Errors in the category fall in the range 1000-1999 inclusive.
		*/
		public static final int RESULT_INVALID_ARGUMENT = 4;
		public static final int ERROR_CATEGORY_REQUEST_ERROR = 1;

		/** The caller tried to execute a disabled app function. */
		public static final int RESULT_DISABLED = 5;
		/**
		* The error is caused by an issue in the system.
		*
		* <p>For example, the AppFunctionService implementation is not found by the system.
		*
		* <p>Errors in the category fall in the range 2000-2999 inclusive.
		*/
		public static final int ERROR_CATEGORY_SYSTEM = 2;

		/**
		* The operation was cancelled. Use this error code to report that a cancellation is done after
		* receiving a cancellation signal.
		* The error is caused by the app providing the function.
		*
		* <p>For example, the app crashed when the system is executing the request.
		*
		* <p>Errors in the category fall in the range 3000-3999 inclusive.
		*/
		public static final int RESULT_CANCELLED = 6;
		public static final int ERROR_CATEGORY_APP = 3;

		/** The result code of the app function execution. */
		@ResultCode private final int mResultCode;
		@@ -197,6 +256,36 @@ public final class ExecuteAppFunctionResponse implements Parcelable {
		return extras;
		}

		/**
		* Returns the error category of the {@link ExecuteAppFunctionResponse}.
		*
		* <p>This method categorizes errors based on their underlying cause, allowing developers to
		* implement targeted error handling and provide more informative error messages to users. It
		* maps ranges of result codes to specific error categories.
		*
		* <p>When constructing a {@link #newFailure} response, use the appropriate result code value to
		* ensure correct categorization of the failed response.
		*
		* <p>This method returns {@code ERROR_CATEGORY_UNKNOWN} if the result code does not belong to
		* any error category, for example, in the case of a successful result with {@link #RESULT_OK}.
		*
		* <p>See {@link ErrorCategory} for a complete list of error categories and their corresponding
		* result code ranges.
		*/
		@ErrorCategory
		public int getErrorCategory() {
		if (mResultCode >= 1000 && mResultCode < 2000) {
		return ERROR_CATEGORY_REQUEST_ERROR;
		}
		if (mResultCode >= 2000 && mResultCode < 3000) {
		return ERROR_CATEGORY_SYSTEM;
		}
		if (mResultCode >= 3000 && mResultCode < 4000) {
		return ERROR_CATEGORY_APP;
		}
		return ERROR_CATEGORY_UNKNOWN;
		}

		/**
		* Returns a generic document containing the return value of the executed function.
		*
		@@ -287,4 +376,20 @@ public final class ExecuteAppFunctionResponse implements Parcelable {
		})
		@Retention(RetentionPolicy.SOURCE)
		public @interface ResultCode {}

		/**
		* Error categories.
		*
		* @hide
		*/
		@IntDef(
		prefix = {"ERROR_CATEGORY_"},
		value = {
		ERROR_CATEGORY_UNKNOWN,
		ERROR_CATEGORY_REQUEST_ERROR,
		ERROR_CATEGORY_APP,
		ERROR_CATEGORY_SYSTEM
		})
		@Retention(RetentionPolicy.SOURCE)
		public @interface ErrorCategory {}
		}

libs/appfunctions/api/current.txt

+11 −6

Original line number	Diff line number	Diff line
		@@ -34,6 +34,7 @@ package com.google.android.appfunctions.sidecar {
		}

		public final class ExecuteAppFunctionResponse {
		method public int getErrorCategory();
		method @Nullable public String getErrorMessage();
		method @NonNull public android.os.Bundle getExtras();
		method public int getResultCode();
		@@ -41,13 +42,17 @@ package com.google.android.appfunctions.sidecar {
		method public boolean isSuccess();
		method @NonNull public static com.google.android.appfunctions.sidecar.ExecuteAppFunctionResponse newFailure(int, @Nullable String, @Nullable android.os.Bundle);
		method @NonNull public static com.google.android.appfunctions.sidecar.ExecuteAppFunctionResponse newSuccess(@NonNull android.app.appsearch.GenericDocument, @Nullable android.os.Bundle);
		field public static final int ERROR_CATEGORY_APP = 3; // 0x3
		field public static final int ERROR_CATEGORY_REQUEST_ERROR = 1; // 0x1
		field public static final int ERROR_CATEGORY_SYSTEM = 2; // 0x2
		field public static final int ERROR_CATEGORY_UNKNOWN = 0; // 0x0
		field public static final String PROPERTY_RETURN_VALUE = "returnValue";
		field public static final int RESULT_APP_UNKNOWN_ERROR = 2; // 0x2
		field public static final int RESULT_CANCELLED = 6; // 0x6
		field public static final int RESULT_DENIED = 1; // 0x1
		field public static final int RESULT_DISABLED = 5; // 0x5
		field public static final int RESULT_INTERNAL_ERROR = 3; // 0x3
		field public static final int RESULT_INVALID_ARGUMENT = 4; // 0x4
		field public static final int RESULT_APP_UNKNOWN_ERROR = 3000; // 0xbb8
		field public static final int RESULT_CANCELLED = 2001; // 0x7d1
		field public static final int RESULT_DENIED = 1000; // 0x3e8
		field public static final int RESULT_DISABLED = 1002; // 0x3ea
		field public static final int RESULT_INTERNAL_ERROR = 2000; // 0x7d0
		field public static final int RESULT_INVALID_ARGUMENT = 1001; // 0x3e9
		field public static final int RESULT_OK = 0; // 0x0
		}

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

+119 −14

Original line number	Diff line number	Diff line
		@@ -50,38 +50,97 @@ public final class ExecuteAppFunctionResponse {
		*/
		public static final String PROPERTY_RETURN_VALUE = "returnValue";

		/** The call was successful. */
		/**
		* The call was successful.
		*
		* <p>This result code does not belong in an error category.
		*/
		public static final int RESULT_OK = 0;

		/** The caller does not have the permission to execute an app function. */
		public static final int RESULT_DENIED = 1;
		/**
		* The caller does not have the permission to execute an app function.
		*
		* <p>This error is in the {@link #ERROR_CATEGORY_REQUEST_ERROR} category.
		*/
		public static final int RESULT_DENIED = 1000;

		/**
		* The caller supplied invalid arguments to the execution request.
		*
		* <p>This error may be considered similar to {@link IllegalArgumentException}.
		*
		* <p>This error is in the {@link #ERROR_CATEGORY_REQUEST_ERROR} category.
		*/
		public static final int RESULT_INVALID_ARGUMENT = 1001;

		/**
		* The caller tried to execute a disabled app function.
		*
		* <p>This error is in the request error category.
		*
		* <p>This error is in the {@link #ERROR_CATEGORY_REQUEST_ERROR} category.
		*/
		public static final int RESULT_DISABLED = 1002;

		/**
		* An internal unexpected error coming from the system.
		*
		* <p>This error is in the {@link #ERROR_CATEGORY_SYSTEM} category.
		*/
		public static final int RESULT_INTERNAL_ERROR = 2000;

		/**
		* The operation was cancelled. Use this error code to report that a cancellation is done after
		* receiving a cancellation signal.
		*
		* <p>This error is in the {@link #ERROR_CATEGORY_SYSTEM} category.
		*/
		public static final int RESULT_CANCELLED = 2001;

		/**
		* 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.
		*
		* <p>This error is in the {@link #ERROR_CATEGORY_APP} category.
		*/
		public static final int RESULT_APP_UNKNOWN_ERROR = 2;
		public static final int RESULT_APP_UNKNOWN_ERROR = 3000;

		/** An internal unexpected error coming from the system. */
		public static final int RESULT_INTERNAL_ERROR = 3;
		/**
		* The error category is unknown.
		*
		* <p>This is the default value for {@link #getErrorCategory}.
		*/
		public static final int ERROR_CATEGORY_UNKNOWN = 0;

		/**
		* The caller supplied invalid arguments to the call.
		* The error is caused by the app requesting a function execution.
		*
		* <p>This error may be considered similar to {@link IllegalArgumentException}.
		* <p>For example, the caller provided invalid parameters in the execution request e.g. an
		* invalid function ID.
		*
		* <p>Errors in the category fall in the range 1000-1999 inclusive.
		*/
		public static final int RESULT_INVALID_ARGUMENT = 4;
		public static final int ERROR_CATEGORY_REQUEST_ERROR = 1;

		/** The caller tried to execute a disabled app function. */
		public static final int RESULT_DISABLED = 5;
		/**
		* The error is caused by an issue in the system.
		*
		* <p>For example, the AppFunctionService implementation is not found by the system.
		*
		* <p>Errors in the category fall in the range 2000-2999 inclusive.
		*/
		public static final int ERROR_CATEGORY_SYSTEM = 2;

		/**
		* The operation was cancelled. Use this error code to report that a cancellation is done after
		* receiving a cancellation signal.
		* The error is caused by the app providing the function.
		*
		* <p>For example, the app crashed when the system is executing the request.
		*
		* <p>Errors in the category fall in the range 3000-3999 inclusive.
		*/
		public static final int RESULT_CANCELLED = 6;
		public static final int ERROR_CATEGORY_APP = 3;

		/** The result code of the app function execution. */
		@ResultCode private final int mResultCode;
		@@ -170,6 +229,36 @@ public final class ExecuteAppFunctionResponse {
		return extras;
		}

		/**
		* Returns the error category of the {@link ExecuteAppFunctionResponse}.
		*
		* <p>This method categorizes errors based on their underlying cause, allowing developers to
		* implement targeted error handling and provide more informative error messages to users. It
		* maps ranges of result codes to specific error categories.
		*
		* <p>When constructing a {@link #newFailure} response, use the appropriate result code value to
		* ensure correct categorization of the failed response.
		*
		* <p>This method returns {@code ERROR_CATEGORY_UNKNOWN} if the result code does not belong to
		* any error category, for example, in the case of a successful result with {@link #RESULT_OK}.
		*
		* <p>See {@link ErrorCategory} for a complete list of error categories and their corresponding
		* result code ranges.
		*/
		@ErrorCategory
		public int getErrorCategory() {
		if (mResultCode >= 1000 && mResultCode < 2000) {
		return ERROR_CATEGORY_REQUEST_ERROR;
		}
		if (mResultCode >= 2000 && mResultCode < 3000) {
		return ERROR_CATEGORY_SYSTEM;
		}
		if (mResultCode >= 3000 && mResultCode < 4000) {
		return ERROR_CATEGORY_APP;
		}
		return ERROR_CATEGORY_UNKNOWN;
		}

		/**
		* Returns a generic document containing the return value of the executed function.
		*
		@@ -245,4 +334,20 @@ public final class ExecuteAppFunctionResponse {
		})
		@Retention(RetentionPolicy.SOURCE)
		public @interface ResultCode {}

		/**
		* Error categories.
		*
		* @hide
		*/
		@IntDef(
		prefix = {"ERROR_CATEGORY_"},
		value = {
		ERROR_CATEGORY_UNKNOWN,
		ERROR_CATEGORY_REQUEST_ERROR,
		ERROR_CATEGORY_APP,
		ERROR_CATEGORY_SYSTEM
		})
		@Retention(RetentionPolicy.SOURCE)
		public @interface ErrorCategory {}
		}