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.app.Service;
20 import android.content.Intent;
21 import android.os.CancellationSignal;
22 import android.os.IBinder;
23 import android.os.OutcomeReceiver;
24 
25 import androidx.annotation.MainThread;
26 import androidx.annotation.RestrictTo;
27 
28 import org.jspecify.annotations.NonNull;
29 import org.jspecify.annotations.Nullable;
30 
31 /**
32  * Abstract base class to provide app functions to the system.
33  *
34  * <p>Include the following in the manifest:
35  *
36  * <pre>
37  * {@literal
38  * <service android:name=".YourService"
39  *       android:permission="android.permission.BIND_APP_FUNCTION_SERVICE">
40  *    <intent-filter>
41  *      <action android:name="android.app.appfunctions.AppFunctionService" />
42  *    </intent-filter>
43  * </service>
44  * }
45  * </pre>
46  *
47  * @see AppFunctionManager
48  */
49 @RestrictTo(RestrictTo.Scope.LIBRARY_GROUP_PREFIX)
50 public abstract class AppFunctionService extends Service {
51     /**
52      * The permission to only allow system access to the functions through the system.
53      */
54     @NonNull
55     public static final String BIND_APP_FUNCTION_SERVICE =
56             "android.permission.BIND_APP_FUNCTION_SERVICE";
57 
58     /**
59      * The {@link Intent} that must be declared as handled by the service. To be supported, the
60      * service must also require the {@link #BIND_APP_FUNCTION_SERVICE} permission so that other
61      * applications can not abuse it.
62      */
63     @NonNull
64     public static final String SERVICE_INTERFACE = "android.app.appfunctions.AppFunctionService";
65 
66     @NonNull
67     @Override
onBind(@ullable Intent intent)68     public final IBinder onBind(@Nullable Intent intent) {
69         throw new RuntimeException("Stub!");
70     }
71 
72     /**
73      * Called by the system to execute a specific app function.
74      *
75      * <p>This method is the entry point for handling all app function requests in an app. When the
76      * system needs your AppFunctionService to perform a function, it will invoke this method.
77      *
78      * <p>Each function you've registered is identified by a unique identifier. This identifier
79      * doesn't need to be globally unique, but it must be unique within your app. For example, a
80      * function to order food could be identified as "orderFood". In most cases, this identifier is
81      * automatically generated by the AppFunctions SDK.
82      *
83      * <p>You can determine which function to execute by calling {@link
84      * ExecuteAppFunctionRequest#getFunctionIdentifier()}. This allows your service to route the
85      * incoming request to the appropriate logic for handling the specific function.
86      *
87      * <p>This method is always triggered in the main thread. You should run heavy tasks on a worker
88      * thread and dispatch the result with the given callback. You should always report back the
89      * result using the callback, no matter if the execution was successful or not.
90      *
91      * <p>This method also accepts a {@link CancellationSignal} that the app should listen to cancel
92      * the execution of function if requested by the system.
93      *
94      * @param request            The function execution request.
95      * @param callingPackage     The package name of the app that is requesting the execution.
96      * @param cancellationSignal A signal to cancel the execution.
97      * @param callback           A callback to report back the result or error.
98      */
99     @MainThread
onExecuteFunction( @onNull ExecuteAppFunctionRequest request, @NonNull String callingPackage, @NonNull CancellationSignal cancellationSignal, @NonNull OutcomeReceiver<ExecuteAppFunctionResponse, AppFunctionException> callback)100     public abstract void onExecuteFunction(
101             @NonNull ExecuteAppFunctionRequest request,
102             @NonNull String callingPackage,
103             @NonNull CancellationSignal cancellationSignal,
104             @NonNull OutcomeReceiver<ExecuteAppFunctionResponse, AppFunctionException> callback);
105 }
106