1 /*
2  * Copyright (C) 2018 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 #ifndef ART_LIBDEXFILE_EXTERNAL_INCLUDE_ART_API_DEX_FILE_EXTERNAL_H_
18 #define ART_LIBDEXFILE_EXTERNAL_INCLUDE_ART_API_DEX_FILE_EXTERNAL_H_
19 
20 // Dex file external API
21 #include <stdint.h>
22 #include <sys/cdefs.h>
23 #include <sys/types.h>
24 
25 __BEGIN_DECLS
26 
27 // This is the stable C ABI that backs art_api::dex below. Structs and functions
28 // may only be added here. C++ users should use dex_file_support.h instead.
29 
30 struct ADexFile;
31 typedef struct ADexFile ADexFile; // NOLINT
32 
33 struct ADexFile_Method;
34 typedef struct ADexFile_Method ADexFile_Method; // NOLINT
35 
36 enum ADexFile_Error : uint32_t {
37   ADEXFILE_ERROR_OK = 0,
38   ADEXFILE_ERROR_INVALID_DEX = 1,
39   ADEXFILE_ERROR_INVALID_HEADER = 2,
40   ADEXFILE_ERROR_NOT_ENOUGH_DATA = 3,
41 };
42 typedef enum ADexFile_Error ADexFile_Error; // NOLINT
43 
44 // Callback used to return information about a dex method.
45 // The method information is valid only during the callback.
46 // NOLINTNEXTLINE
47 typedef void ADexFile_MethodCallback(void* _Nullable callback_data,
48                                      const ADexFile_Method* _Nonnull method);
49 
50 // Interprets a chunk of memory as a dex file.
51 //
52 // @param address Pointer to the start of dex file data.
53 //                The caller must retain the memory until the object is destroyed.
54 // @param size Size of the memory range. If the size is too small, the method returns
55 //             ADEXFILE_ERROR_NOT_ENOUGH_DATA and sets new_size to some larger size
56 //             (which still might large enough, so several retries might be needed).
57 // @param new_size On successful load, this contains exact dex file size from header.
58 // @param location A string that describes the dex file. Preferably its path.
59 //                 It is mostly used just for log messages and may be "".
60 // @param dex_file The created dex file object, or nullptr on error.
61 //                 It must be later freed with ADexFile_Destroy.
62 //
63 // @return ADEXFILE_ERROR_OK if successful.
64 // @return ADEXFILE_ERROR_NOT_ENOUGH_DATA if the provided dex file is too short (truncated).
65 // @return ADEXFILE_ERROR_INVALID_HEADER if the memory does not seem to represent DEX file.
66 // @return ADEXFILE_ERROR_INVALID_DEX if any other non-specific error occurs.
67 //
68 // Thread-safe (creates new object).
69 ADexFile_Error ADexFile_create(const void* _Nonnull address,
70                                size_t size,
71                                size_t* _Nullable new_size,
72                                const char* _Nonnull location,
73                                /*out*/ ADexFile* _Nullable * _Nonnull out_dex_file);
74 
75 // Find method at given offset and call callback with information about the method.
76 //
77 // @param dex_offset Offset relative to the start of the dex file header.
78 // @param callback The callback to call when method is found. Any data that needs to
79 //                 outlive the execution of the callback must be copied by the user.
80 // @param callback_data Extra user-specified argument for the callback.
81 //
82 // @return Number of methods found (0 or 1).
83 //
84 // Not thread-safe for calls on the same ADexFile instance.
85 size_t ADexFile_findMethodAtOffset(ADexFile* _Nonnull self,
86                                    size_t dex_offset,
87                                    ADexFile_MethodCallback* _Nonnull callback,
88                                    void* _Nullable callback_data);
89 
90 // Call callback for all methods in the DEX file.
91 //
92 // @param flags Specifies which information should be obtained.
93 // @param callback The callback to call for all methods. Any data that needs to
94 //                 outlive the execution of the callback must be copied by the user.
95 // @param callback_data Extra user-specified argument for the callback.
96 //
97 // @return Number of methods found.
98 //
99 // Not thread-safe for calls on the same ADexFile instance.
100 size_t ADexFile_forEachMethod(ADexFile* _Nonnull self,
101                               ADexFile_MethodCallback* _Nonnull callback,
102                               void* _Nullable callback_data);
103 
104 // Free the given object.
105 //
106 // Thread-safe, can be called only once for given instance.
107 void ADexFile_destroy(ADexFile* _Nullable self);
108 
109 // @return Offset of byte-code of the method relative to start of the dex file.
110 // @param out_size Optionally return size of byte-code in bytes.
111 // Not thread-safe for calls on the same ADexFile instance.
112 size_t ADexFile_Method_getCodeOffset(const ADexFile_Method* _Nonnull self,
113                                      size_t* _Nullable out_size);
114 
115 // @return Method name only (without class).
116 //         The encoding is slightly modified UTF8 (see Dex specification).
117 // @param out_size Optionally return string size (excluding null-terminator).
118 //
119 // Returned data may be short lived: it must be copied before calling
120 // this method again within the same ADexFile.
121 // (it is currently long lived, but this is not guaranteed in the future).
122 //
123 // Not thread-safe for calls on the same ADexFile instance.
124 const char* _Nonnull ADexFile_Method_getName(const ADexFile_Method* _Nonnull self,
125                                              size_t* _Nullable out_size);
126 
127 // @return Method name (with class name).
128 //         The encoding is slightly modified UTF8 (see Dex specification).
129 // @param out_size Optionally return string size (excluding null-terminator).
130 // @param with_params Whether to include method parameters and return type.
131 //
132 // Returned data may be short lived: it must be copied before calling
133 // this method again within the same ADexFile.
134 // (it points to pretty printing buffer within the ADexFile instance)
135 //
136 // Not thread-safe for calls on the same ADexFile instance.
137 const char* _Nonnull ADexFile_Method_getQualifiedName(const ADexFile_Method* _Nonnull self,
138                                                       int with_params,
139                                                       size_t* _Nullable out_size);
140 
141 // @return Class descriptor (mangled class name).
142 //         The encoding is slightly modified UTF8 (see Dex specification).
143 // @param out_size Optionally return string size (excluding null-terminator).
144 //
145 // Returned data may be short lived: it must be copied before calling
146 // this method again within the same ADexFile.
147 // (it is currently long lived, but this is not guaranteed in the future).
148 //
149 // Not thread-safe for calls on the same ADexFile instance.
150 const char* _Nonnull ADexFile_Method_getClassDescriptor(const ADexFile_Method* _Nonnull self,
151                                                         size_t* _Nullable out_size);
152 
153 // @return Compile-time literal or nullptr on error.
154 const char* _Nullable ADexFile_Error_toString(ADexFile_Error self);
155 
156 __END_DECLS
157 
158 #endif  // ART_LIBDEXFILE_EXTERNAL_INCLUDE_ART_API_DEX_FILE_EXTERNAL_H_
159