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