libdexfile/external/include/art_api/dex_file_external.h - LeafOS-Project/android_art - Gitiles

 /*
  * 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; // NOLINT

 struct ADexFile_Method;
 typedef struct ADexFile_Method ADexFile_Method; // NOLINT

 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; // NOLINT

 // Callback used to return information about a dex method.
 // The method information is valid only during the callback.
 // NOLINTNEXTLINE
 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_
	/*
	* 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; // NOLINT

	struct ADexFile_Method;
	typedef struct ADexFile_Method ADexFile_Method; // NOLINT

	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; // NOLINT

	// Callback used to return information about a dex method.
	// The method information is valid only during the callback.
	// NOLINTNEXTLINE
	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_