1 /* 2 * Copyright (C) 2024 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package com.android.extensions.appfunctions; 18 19 import android.annotation.NonNull; 20 import android.app.appfunctions.AppFunctionManager; 21 import android.app.appsearch.GenericDocument; 22 import android.os.Bundle; 23 24 import java.util.Objects; 25 26 /** The response to an app function execution. */ 27 public final class ExecuteAppFunctionResponse { 28 /** 29 * The name of the property that stores the function return value within the {@code 30 * resultDocument}. 31 * 32 * <p>See {@link GenericDocument#getProperty(String)} for more information. 33 * 34 * <p>If the function returns {@code void} or throws an error, the {@code resultDocument} will 35 * be empty {@link GenericDocument}. 36 * 37 * <p>If the {@code resultDocument} is empty, {@link GenericDocument#getProperty(String)} will 38 * return {@code null}. 39 * 40 * <p>See {@link #getResultDocument} for more information on extracting the return value. 41 */ 42 public static final String PROPERTY_RETURN_VALUE = "androidAppfunctionsReturnValue"; 43 44 /** 45 * Returns the return value of the executed function. 46 * 47 * <p>The return value is stored in a {@link GenericDocument} with the key {@link 48 * #PROPERTY_RETURN_VALUE}. 49 * 50 * <p>See {@link #getResultDocument} for more information on extracting the return value. 51 */ 52 @NonNull private final GenericDocument mResultDocument; 53 54 /** Returns the additional metadata data relevant to this function execution response. */ 55 @NonNull private final Bundle mExtras; 56 57 /** 58 * @param resultDocument The return value of the executed function. 59 */ ExecuteAppFunctionResponse(@onNull GenericDocument resultDocument)60 public ExecuteAppFunctionResponse(@NonNull GenericDocument resultDocument) { 61 this(resultDocument, Bundle.EMPTY); 62 } 63 64 /** 65 * @param resultDocument The return value of the executed function. 66 * @param extras The additional metadata for this function execution response. 67 */ ExecuteAppFunctionResponse( @onNull GenericDocument resultDocument, @NonNull Bundle extras)68 public ExecuteAppFunctionResponse( 69 @NonNull GenericDocument resultDocument, @NonNull Bundle extras) { 70 mResultDocument = Objects.requireNonNull(resultDocument); 71 mExtras = Objects.requireNonNull(extras); 72 } 73 74 /** 75 * Returns a generic document containing the return value of the executed function. 76 * 77 * <p>The {@link #PROPERTY_RETURN_VALUE} key can be used to obtain the return value. 78 * 79 * <p>Sample code for extracting the return value: 80 * 81 * <pre> 82 * GenericDocument resultDocument = response.getResultDocument(); 83 * Object returnValue = resultDocument.getProperty(PROPERTY_RETURN_VALUE); 84 * if (returnValue != null) { 85 * // Cast returnValue to expected type, or use {@link GenericDocument#getPropertyString}, 86 * // {@link GenericDocument#getPropertyLong} etc. 87 * // Do something with the returnValue 88 * } 89 * </pre> 90 * 91 * @see AppFunctionManager on how to determine the expected function return. 92 */ 93 @NonNull getResultDocument()94 public GenericDocument getResultDocument() { 95 return mResultDocument; 96 } 97 98 /** Returns the additional metadata for this function execution response. */ 99 @NonNull getExtras()100 public Bundle getExtras() { 101 return mExtras; 102 } 103 } 104