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 /**
20  * Marks a function within a class as callable by other applications.
21  *
22  * The `@AppFunction` annotation signals that the annotated function can be invoked by external
23  * applications with proper permission (e.g., an assistant). For instance, a note-taking app could
24  * expose a function allowing an assistant to create notes based on user commands.
25  *
26  * The enclosing class of the function would be instantiated whenever an AppFunction within the
27  * class is called. If the enclosing class requires constructor parameters or custom instantiation,
28  * add a custom factory in [AppFunctionConfiguration.Builder.addEnclosingClassFactory]. This allows
29  * you to inject dependencies or handle more complex object creation scenarios.
30  *
31  * When a function is annotated with `@AppFunction`, the compiler will automatically:
32  * * Generate an XML file within the APK. This file describes the signatures of all
33  *   `@AppFunction`-annotated functions within the application.
34  * * Provide the necessary infrastructure to expose these functions via
35  *   [android.app.appfunctions.AppFunctionService].
36  *
37  * Applications with the appropriate permissions can then use
38  * [android.app.appfunctions.AppFunctionManager] to invoke these exposed functions.
39  *
40  * The compiler also generates an ID class associated with the class containing `@AppFunction`
41  * annotations. This ID class provides constants for retrieving the unique identifier of each
42  * annotated function. Consider this example:
43  * ```kotlin
44  * package com.example.mynotes
45  *
46  * class NoteFunctions: CreateNote, UpdateNote {
47  *   @AppFunction
48  *   override suspend fun createNote(...): Note { ... }
49  *
50  *   @AppFunction
51  *   override suspend fun updateNote(...): Note? { ... }
52  * }
53  * ```
54  *
55  * The compiler will generate a `NoteFunctionsIds` class within the same `com.example.mynotes`
56  * package. This generated class will contain constants like `CREATE_NOTE_ID` and `UPDATE_NOTE_ID`,
57  * which correspond to the `createNote` and `updateNote` functions, respectively.
58  *
59  * **IMPORTANT:** By default, functions annotated with `@AppFunction` are executed on the main
60  * thread. For operations that may take a significant amount of time, it is crucial to use a
61  * coroutine dispatcher that runs on a background thread.
62  *
63  * @see AppFunctionConfiguration.Builder.addEnclosingClassFactory
64  */
65 // Use BINARY here so that the annotation is kept around at the aggregation stage.
66 @Retention(AnnotationRetention.BINARY)
67 @Target(AnnotationTarget.FUNCTION)
68 public annotation class AppFunction(
69     /**
70      * Indicates whether this function is enabled. The default value is "true".
71      *
72      * If set to `false`, this function will be unavailable for invocation by other applications
73      * unless explicitly enabled at runtime. When disabled, any attempt to call this function by
74      * another application will be rejected.
75      */
76     public val isEnabled: Boolean = true,
77 )
78