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