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 - 13 (API level 21 - 33)
- Support armeabi-v7a, arm64-v8a, x86, x86-64
- Support customized inline hook framework and ART symbol resolver
https://lsposed.org/LSPlant/namespacelsplant.html
repositories {
mavenCentral()
}
dependencies {
implementation "org.lsposed.lsplant:lsplant:4.0"
}
android {
buildFeatures {
prefab true
}
}
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 anMethod
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 thehooker_object
can be used to store all the callbacks to allow multiple modules work simultaneously without conflict. -
callback_method
is anMethod
object, the callback method to thehooker_object
used to replace thetarget_method
.Whenever the
target_method
is invoked, the callback_method will be invoked instead of the originaltarget_method
. The signature of thecallback_method
must be:public Object callback_method(Object []args)
.That is, the return type must be
Object
and the parameter type must beObject[]
. Behavior is undefined if the signature does not match the requirement. Extra info can be provided by defining member variables ofhooker_object
. This method must be a method tohooker_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, its source 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 anMethod
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 anMethod
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: