1 // Copyright 2023, The Android Open Source Project
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 //     http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14 
15 #pragma once
16 
17 #include <android/llndk-versioning.h>
18 #include <stdint.h>
19 #include <sys/cdefs.h>
20 
21 __BEGIN_DECLS
22 
23 /**
24  * AApexInfo represents an information object for an APEX including name
25  * and version.
26  */
27 struct AApexInfo;
28 typedef struct AApexInfo AApexInfo;
29 
30 /**
31  * AApexInfoError tells the error when AApexInfo_create() fails.
32  */
33 typedef enum AApexInfoError : int32_t {
34   /* No error */
35   AAPEXINFO_OK,
36   /* The calling process is not from an APEX. */
37   AAPEXINFO_NO_APEX,
38   /* Failed to get the executable path of the calling process.
39    * See the log for details.
40    */
41   AAPEXINFO_ERROR_EXECUTABLE_PATH,
42   /* The current APEX is ill-formed. eg) No/invalid apex_manifest.pb.
43    * See the log for details.
44    */
45   AAPEXINFO_INVALID_APEX,
46 } AApexInfoError;
47 
48 /**
49  * Creates an AApexInfo object from the current calling executable. For example,
50  * when called by a binary from /apex/com.android.foo/bin/foo, this will set an
51  * out parameter with an AApexInfo object corresponding the APEX
52  * "com.android.foo". The allocated AApexInfo object has to be deallocated using
53  * AApexInfo_destroy().
54  *
55  * \param info out parameter for an AApexInfo object for the current APEX. Null
56  * when called from a non-APEX executable.
57  *
58  * \returns AApexInfoError
59  */
60 __attribute__((warn_unused_result)) AApexInfoError
61 AApexInfo_create(AApexInfo *_Nullable *_Nonnull info)
62     __INTRODUCED_IN_LLNDK(202404);
63 
64 /**
65  * Destroys an AApexInfo object created by AApexInfo_create().
66  *
67  * \param info pointer to the AApexInfo object created by AApexInfo_create()
68  */
69 void AApexInfo_destroy(AApexInfo *_Nonnull info) __INTRODUCED_IN_LLNDK(202404);
70 
71 /**
72  * Returns a C-string for the APEX name.
73  *
74  * NOTE: The lifetime of the returned C-string is bound to the AApexInfo object.
75  * So, it has to be copied if it needs to be alive even after AApexInfo_destroy
76  * is called.
77  *
78  * \param info pointer to the AApexInfo object created by AApexInfo_create()
79  *
80  * \return the APEX name.
81  */
82 __attribute__((warn_unused_result))
83 const char *_Nonnull AApexInfo_getName(const AApexInfo *_Nonnull info)
84     __INTRODUCED_IN_LLNDK(202404);
85 
86 /**
87  * Returns the APEX version.
88  *
89  * \param info pointer to the AApexInfo object created by AApexInfo_create()
90  *
91  * \return the APEX version.
92  */
93 int64_t AApexInfo_getVersion(const AApexInfo *_Nonnull info)
94     __INTRODUCED_IN_LLNDK(202404);
95 
96 // AApexSupport_loadLibrary is private to platform yet.
97 #if !defined(__ANDROID_VENDOR__) && !defined(__ANDROID_PRODUCT__)
98 /**
99  * Opens a library from a given apex and returns its handle.
100  *
101  * \param name the name of the library to open
102  *
103  * \param apexName the name of the APEX which to load the library from. Note
104  * that the apex should be visible in linker configuration. You might need to
105  * set `"visible": true` in its etc/linker.config.pb.
106  *
107  * \param flag the same as dlopen() flag.
108  *
109  * \return nonnull handle for the loaded object on success. null otherwise.
110  */
111 __attribute__((warn_unused_result)) void *_Nullable AApexSupport_loadLibrary(
112     const char *_Nonnull name, const char *_Nonnull apexName, int flag);
113 #endif
114 
115 __END_DECLS
116