C Core API

In order to provide a simple API that developers can use for writing a binding in other languages we took the decision of writing a Core API in C (exporting the symbols as extern "C"). This API returns objects as structures, and these structures contain C types which are easy to transform to other types in other languages.

Next we will provide the documentation of the Core API, for the moment this Core API is on its own branch, but soon we hope merging it in main branch. The header for the C Core API can be found in the next link: shuriken_core.h.

C Core API Documentation

C Core Dex API

For implementing the Core DEX API, we rely in an opaque context object with the type hDexContext, internally this object can be modified so it's better not to rely on accessing the fields from this opaque object. All the methods from this API receive this object as first parameter, and depending on the API function another parameters are included.

Structures from the Dex API

hdvmfield_t

This structure represent a field from a class, next variables are available from the field structure:

• name - name of the field.
• type - an htype_e value representing the type of the field.
• fundamental_value - in case the base type is a fundamental, this value contains which type of fundamental value.
• type_value - the value of the type from the field as a const char*
• access_flags - access flags from the field

hdvmmethod_t

Structure that represents a method from a class, next variables are available from the method structure:

• method_name - name of the method (without parameters, return types nor class name)
• prototype - prototype of the method (e.g. (II)I)
• access_flags - access flags from the method
• code_size - number of bytes of method's bytecode
• code - pointer to a byte array with the bytecode from the method
• dalvik_name - dalvik representation of a method name (e.g. Lfoo;->test(II)I)
• demangled_name - demangled version from previous value (e.g. int foo->test(int,int))

hdvmclass_t

Structure that represents a Dalvik class, next variables are available from the class structure:

• class_name - name of the class (e.g. foo)
• super_class - name of the super class from the current class
• source_file - in case of having this information, this variable stores the name of the source file
• access_flags - access flags from the class
• direct_methods_size - number of direct methods in the class
• direct_methods - list of direct methods, each one is a pointer to an structure of the type hdvmmethod_t
• virtual_methods_size - number of virtual methods in the class
• virtual_methods - list of virtual methods, each one is a pointer to an structure of the type hdvmmethod_t
• instance_fields_size - number of instance fields in the class
• instance_fields - list of instance fields, each one is a pointer to an structure of the type hdvmfield_t
• static_fields_size - number of static fields in the class
• static_fields - list of static fields, each one is a pointer to an structure of the type hdvmfield_t

Functions from the Dex API

parse_dex

SHURIKENCOREAPI hDexContext parse_dex(const char* filePath);

Main method from the DEX Core API. Parses the DEX file and retrieves a context object.

• Parameters:

  • filePath: Path to the DEX file to analyze.

• Return:

  • Returns a context object (hDexContext) to obtain information from the DEX file.

destroy_dex

SHURIKENCOREAPI void destroy_dex(hDexContext context);

Destroys the context object used to obtain information from the DEX file.

• Parameters:

  • context: The context object to be destroyed.

• Return:

  • No return value. This function only destroys the context object.

get_number_of_strings

SHURIKENCOREAPI size_t get_number_of_strings(hDexContext context);

Retrieves the number of strings from the DEX file.

• Parameters:

  • context: The DEX context from which to retrieve the number of strings.

• Return:

  • Returns the number of strings present in the DEX file associated with the given context.

get_string_by_id

SHURIKENCOREAPI const char* get_string_by_id(hDexContext context, size_t i);

Retrieves a string from the DEX file by its ID.

• Parameters:

  • context: The DEX context from which to retrieve the string.
  • i: The ID of the string to retrieve.

• Return:

  • Returns the string from the provided ID.

get_number_of_classes

SHURIKENCOREAPI uint16_t get_number_of_classes(hDexContext context);

Retrieves the number of classes from the DEX file.

• Parameters:

  • context: The DEX context from which to retrieve the number of classes.

• Return:

  • Returns the number of classes available in the DEX file associated with the given context.

get_class_by_id

SHURIKENCOREAPI hdvmclass_t * get_class_by_id(hDexContext context, uint16_t i);

Retrieves a class structure from the DEX file by its ID.

• Parameters:

  • context: The DEX context from which to retrieve the class.
  • i: The ID of the class to retrieve.

• Return:

  • Returns a pointer to the class structure (hdvmclass_t) from the DEX file.

get_class_by_name

SHURIKENCOREAPI hdvmclass_t * get_class_by_name(hDexContext context, const char *class_name);

Retrieves a class structure from the DEX file by its name.

• Parameters:

  • context: The DEX context from which to retrieve the class.
  • class_name: The name of the class to retrieve.

• Return:

  • Returns a pointer to the class structure (hdvmclass_t) from the DEX file.

get_method_by_name

SHURIKENCOREAPI hdvmmethod_t * get_method_by_name(hDexContext context, const char *method_name);

Retrieves a method structure from the DEX file by its full Dalvik name.

• Parameters:

  • context: The DEX context from which to retrieve the method.
  • method_name: The full Dalvik name of the method to retrieve.

• Return:

  • Returns a pointer to the method structure (hdvmmethod_t) from the DEX file. Returns NULL if the method does not exist.