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