Substrate C API Overview

Substrate provides a set of APIs designed to solve the varied challenges that arise when attempting to instrument code on each of its target platforms and languages. Whether you are interested in modifying the behavior of C/C++, Objective-C (iOS), or Java (Android/Dalvik), Substrate has a workflow for making your changes in a way that coordinates with other developers who may be modifying similar functionality.

Conceptually, each platform consists of three common steps.

  1. get a reference to the container (class/module/image)
  2. look up a specific function/method in that container
  3. replace that code with your modified implementation

After which, you likely care about being able to "proceed" to the original implementation (the one that existed before your modifications), possibly at a different time, or passing different arguments. Each of the APIs provided provide a way to do this, often by way of a pointer-to-a-function.

The developer calling these APIs, no matter which platform they are attempting to manipulate, does so at the level of C. The usual runtime-provided language bindings can then be used to transition back/forth between C and the higher-level language (such as to call Java code from your JNI-level hooks).

C / C++ / Assembly

With MSHookFunction, developers easily take control of native code on x86 (32/64-bit) or ARM systems, using MSGetImageByName to look up loaded binary images and MSFindSymbol to access their private symbols.

Objective-C (iOS)

Using MSHookMessageEx takes care of the irritating corner cases that can arise when attempting to "swizzle" messages using Objective-C runtime functions in an environment where you are not the only developer making changes (or Apple's behavior changes).

Java (Android/Dalvik)

After being notified of classes being loaded by MSJavaHookClassLoad, developers use MSJavaHookMethod to swap in their new functionality. Finally, MSJavaBlessClassLoader can be used to transition back to Java while still being able to access private members.