1 /*
2  * Copyright 2025 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 androidx.appfunctions
18 
19 import android.os.Build
20 import android.os.Bundle
21 import androidx.annotation.RequiresApi
22 import androidx.annotation.RestrictTo
23 import androidx.annotation.RestrictTo.Scope.LIBRARY_GROUP
24 
25 /**
26  * Represents a request to execute a specific app function.
27  *
28  * @property targetPackageName The package name of the app that hosts the function.
29  * @property functionIdentifier The unique string identifier of the app function to be executed.
30  * @property functionParameters The parameters required to invoke this function. Within this
31  *   [AppFunctionData], the property names are the names of the function parameters and the property
32  *   values are the values of those parameters. The data object may have missing parameters.
33  *   Developers are advised to implement defensive handling measures.
34  */
35 public class ExecuteAppFunctionRequest
36 @RestrictTo(LIBRARY_GROUP)
37 constructor(
38     public val targetPackageName: String,
39     public val functionIdentifier: String,
40     public val functionParameters: AppFunctionData,
41     /** Whether the parameters in this request is encoded in the jetpack format or not. */
42     @get:RestrictTo(LIBRARY_GROUP) public val useJetpackSchema: Boolean
43 ) {
44     public constructor(
45         targetPackageName: String,
46         functionIdentifier: String,
47         functionParameters: AppFunctionData
48     ) : this(targetPackageName, functionIdentifier, functionParameters, useJetpackSchema = true)
49 
50     @RestrictTo(LIBRARY_GROUP)
toPlatformExtensionClassnull51     public fun toPlatformExtensionClass():
52         com.android.extensions.appfunctions.ExecuteAppFunctionRequest {
53         return com.android.extensions.appfunctions.ExecuteAppFunctionRequest.Builder(
54                 targetPackageName,
55                 functionIdentifier,
56             )
57             .setParameters(functionParameters.genericDocument)
58             .setExtras(
59                 Bundle().apply {
60                     putBundle(EXTRA_PARAMETERS, functionParameters.extras)
61                     putBoolean(EXTRA_USE_JETPACK_SCHEMA, useJetpackSchema)
62                 }
63             )
64             .build()
65     }
66 
toStringnull67     override fun toString(): String {
68         return "ExecuteAppFunctionRequest(targetPackageName=$targetPackageName, " +
69             "functionIdentifier=$functionIdentifier, functionParameters=$functionParameters)"
70     }
71 
72     @RestrictTo(LIBRARY_GROUP)
copynull73     public fun copy(
74         targetPackageName: String = this.targetPackageName,
75         functionIdentifier: String = this.functionIdentifier,
76         functionParameters: AppFunctionData = this.functionParameters,
77         useJetpackSchema: Boolean = this.useJetpackSchema
78     ): ExecuteAppFunctionRequest =
79         ExecuteAppFunctionRequest(
80             targetPackageName,
81             functionIdentifier,
82             functionParameters,
83             useJetpackSchema
84         )
85 
86     public companion object {
87         internal const val EXTRA_PARAMETERS = "androidXAppfunctionsExtraParameters"
88         internal const val EXTRA_USE_JETPACK_SCHEMA = "androidXAppfunctionsExtraUseJetpackSchema"
89 
90         @RequiresApi(Build.VERSION_CODES.TIRAMISU)
91         @RestrictTo(LIBRARY_GROUP)
92         public fun fromPlatformExtensionClass(
93             request: com.android.extensions.appfunctions.ExecuteAppFunctionRequest
94         ): ExecuteAppFunctionRequest {
95             return ExecuteAppFunctionRequest(
96                 targetPackageName = request.targetPackageName,
97                 functionIdentifier = request.functionIdentifier,
98                 functionParameters =
99                     AppFunctionData(
100                         request.parameters,
101                         request.extras.getBundle(EXTRA_PARAMETERS) ?: Bundle.EMPTY
102                     ),
103                 useJetpackSchema = request.extras.getBoolean(EXTRA_USE_JETPACK_SCHEMA, false)
104             )
105         }
106     }
107 }
108