English | 中文

LSPlant is an Android ART hook library, providing Java method hook/unhook and inline deoptimization.

This project is part of LSPosed framework under GNU Lesser General Public License.

• Support Android 5.0 - 16 (API level 21 - 36)
• Support armeabi-v7a, arm64-v8a, x86, x86-64, riscv64
• Support customized inline hook framework and ART symbol resolver

• The namespace of exported functions has changed from lsplant::v2 to lsplant::v3.
• By default, only the shared library is compiled. If you need to compile the static library, set the CMake option LSPLANT_BUILD_STATIC to ON.
• InitInfo::inline_hooker Now takes three arguments and returns a handle for the current hook operation.
• InitInfo::inline_unhooker Can be null, takes a handle returned from a previous hook operation.
• InitInfo::art_symbol_resolver Takes two arguments, with the second being the current symbol’s GNU hash.
• InitInfo::art_symbol_prefix_resolver Can be null.
• InitInfo::dexfile_symbol_resolver Can be null, used to find function addresses in libdexfile.so. It is used only on Android 9 and above to load and hide DEX files in memory.
• InitInfo::generated_class_name Changed from the default "LSPHooker_" to "LSPHooker$", indicating a generated class name prefix.
• InitInfo::generated_source_name Can be empty. If empty, the generated stub class will be hidden in the stack trace.
• InitInfo::generated_field_name Changed from "hooker" to "data".
• InitInfo::generated_* These values can be updated by re-calling the Init() function.
• Hook() The returned jobject is no longer a global reference, but a local reference. Callback methods support two signatures, more details can be found in Hook.

https://eirv.github.io/LSPlant/namespacelsplant.html

repositories {
    mavenCentral()
}

android {
    buildFeatures {
        prefab true
    }
}

dependencies {
    implementation "org.lsposed.lsplant:lsplant:+"
}

If you don't want to include libc++_shared.so in your APK, you can use lsplant-standalone instead:

dependencies {
    implementation "org.lsposed.lsplant:lsplant-standalone:+"
}

Initialize LSPlant for the proceeding hook. It mainly prefetch needed symbols and hook some functions.

• env is the Java environment.

• info is the information for initialized.

  Basically, the info provides the inline hooker and unhooker together with a symbol resolver of libart.so to hook and extract needed native functions of ART.

bool Init(JNIEnv *env,
          const InitInfo &info);

Returns whether initialization succeed. Behavior is undefined if calling other LSPlant interfaces before initialization or after a fail initialization.

Hook a Java method by providing the target_method together with the context object hooker_object and its callback callback_method.

• env is the Java environment.

• target_method is an Method object to the method you want to hook.

• hooker_object is an object to store the context of the hook.

  The most likely usage is to store the backup method into it so that when callback_method is invoked, it can call the original method. Another scenario is that, for example, in Xposed framework, multiple modules can hook the same Java method and the hooker_object can be used to store all the callbacks to allow multiple modules work simultaneously without conflict.

• callback_method is an Method object, the callback method to the hooker_object used to replace the target_method.

  Whenever the target_method is invoked, the callback_method will be invoked instead of the original target_method. The signature of the callback_method must be one of these two methods:

public Object callback_method(Object receiver, Object[] args)
public Object callback_method(Object[] packedArgs)

That is, the return type must be Object and the parameter type must be Object, Object[] or Object[]. Behavior is undefined if the signature does not match the requirement. Extra info can be provided by defining member variables of hooker_object. This method must be a method to hooker_object.

jobject Hook(JNIEnv *env,
             jobject target_method,
             jobject hooker_object,
             jobject callback_method);

Returns the backup method. You can invoke it by reflection to invoke the original method. null if fails.

This function will automatically generate a stub class for hook. To help debug, you can set the generated class name, its field name and its method name by setting generated_* in InitInfo.

This function thread safe (you can call it simultaneously from multiple thread) but it's not atomic to the same target_method. That means UnHook or IsUnhook does not guarantee to work properly on the same target_method before it returns. Also, simultaneously call on this function with the same target_method does not guarantee only one will success. If you call this with different hooker_object on the same target_method simultaneously, the behavior is undefined.

Check if a Java function is hooked by LSPlant or not.

bool IsHooked(JNIEnv *env,
              jobject method);

Returns whether the method is hooked.

Unhook a Java function that is previously hooked.

• env is the Java environment.

• target_method is an Method object to the method you want to hook.

bool UnHook(JNIEnv *env,
            jobject target_method);

Returns whether the unhook succeed.

Calling backup (the return method of Hook()) after unhooking is undefined behavior. Please read Hook()'s note for more details.

Deoptimize a method to avoid hooked callee not being called because of inline.

• env is the Java environment.

• method is an Method object to the method to deoptimize.

  By deoptimizing the method, the method will back all callee without inlining. For example, if you hooked a short method B that is invoked by method A, and you find that your callback to B is not invoked after hooking, then it may mean A has inlined B inside its method body. To force A to call your hooked B, you can deoptimize A and then your hook can take effect. Generally, you need to find all the callers of your hooked callee and that can be hardly achieve. Use this function if you are sure the deoptimized callers are all you need. Otherwise, it would be better to change the hook point or to deoptimize the whole app manually (by simple reinstall the app without uninstalled).

bool Deoptimize(JNIEnv *env,
                jobject method);

Returns whether the deoptimizing succeed or not.

It is safe to call deoptimizing on a hooked method because the deoptimization will perform on the backup method instead.

Inspired by the following frameworks:

• YAHFA
• SandHook
• Pine
• Epic

You can support development by submitting PRs or donating to the original projects.