lsplant::v2 Namespace Reference

Data Structures
struct	InitInfo
	Information and configuration that are needed to call Init() More...

Functions
bool	Init (JNIEnv *env, const InitInfo &info)
	Initialize LSPlant for the proceeding hook. It mainly prefetch needed symbols and hook some functions. The env should not have any restriction for accessing hidden APIs. You can obtain such a JNIEnv in JNI_OnLoad(). More...
jobject	Hook (JNIEnv *env, jobject target_method, jobject hooker_object, jobject callback_method)
	Hook a Java method by providing the target_method together with the context object hooker_object and its callback callback_method. More...
bool	UnHook (JNIEnv *env, jobject target_method)
	Unhook a Java function that is previously hooked. More...
bool	IsHooked (JNIEnv *env, jobject method)
	Check if a Java function is hooked by LSPlant or not. More...
bool	Deoptimize (JNIEnv *env, jobject method)
	Deoptimize a method to avoid hooked callee not being called because of inline. More...
void *	GetNativeFunction (JNIEnv *env, jobject method)
	Get the registered native function pointer of a native function. It helps user to hook native methods directly by backing up the native function pointer this function returns and env->registerNatives another native function pointer. More...
bool	MakeClassInheritable (JNIEnv *env, jclass target)
	Make a class inheritable. It will make the class non-final and make all its private constructors protected. More...
bool	MakeDexFileTrusted (JNIEnv *env, jobject cookie)
	Make a DexFile trustable so that it can access hidden APIs. This is useful because we likely need to access hidden APIs when hooking system methods. A concern of this function is that cookie of the DexFile maybe a hidden APIs. So get please get the needed jfieldID beforehand (like in JNI_OnLoad as Init()). More...

Function Documentation

Deoptimize()

bool lsplant::v2::Deoptimize	(	JNIEnv *	env,
		jobject	method
	)

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

Parameters

[in]	env	The Java environment.
[in]	method	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 (but you can still search all callers by using DexHelper). 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).

Returns

Indicate whether the deoptimizing succeed or not.

Note

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

GetNativeFunction()

void* lsplant::v2::GetNativeFunction	(	JNIEnv *	env,
		jobject	method
	)

Get the registered native function pointer of a native function. It helps user to hook native methods directly by backing up the native function pointer this function returns and env->registerNatives another native function pointer.

Parameters

[in]	env	The Java environment.
[in]	method	The native method to get the native function pointer.

Returns

The native function pointer the method previously registered. If it has not been registered or it is not a native method, null is returned instead.

Hook()

jobject lsplant::v2::Hook	(	JNIEnv *	env,
		jobject	target_method,
		jobject	hooker_object,
		jobject	callback_method
	)

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

Parameters

[in]	env	The Java environment. Must not be null.
[in]	target_method	The method id to the method you want to hook. Must not be null.
[in]	hooker_object	The hooker 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.
[in]	callback_method	The callback method to the hooker_object is 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: public Object callback_method(Object []args) That is, the return type must be Object and the parameter type must be Object[]. Behavior is undefined if the signature does not match the requirement. args[0] is the this object for non-static methods and there is NOT null this object placeholder for static methods. Extra info can be provided by defining member variables of hooker_object. This method must be a method to hooker_object.

Returns

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

Note

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 IsHooked() 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.

The behavior of getting the jmethodID of the backup method is undfined.

Init()

bool lsplant::v2::Init	(	JNIEnv *	env,
		const InitInfo &	info
	)

Initialize LSPlant for the proceeding hook. It mainly prefetch needed symbols and hook some functions. The env should not have any restriction for accessing hidden APIs. You can obtain such a JNIEnv in JNI_OnLoad().

Parameters

[in]	env	The Java environment. Must not be null.
[in]	info	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.

Returns

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

See also

InitInfo.

IsHooked()

bool lsplant::v2::IsHooked	(	JNIEnv *	env,
		jobject	method
	)

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

Parameters

[in]	env	The Java environment.
[in]	method	The method to check if it was hooked or not.

Returns

If method hooked, ture; otherwise, false. Please read Hook()'s note for more details.

See also

Hook()

MakeClassInheritable()

bool lsplant::v2::MakeClassInheritable	(	JNIEnv *	env,
		jclass	target
	)

Make a class inheritable. It will make the class non-final and make all its private constructors protected.

Parameters

[in]	env	The Java environment.
[in]	target	The target class that is to make inheritable.

Returns

Indicate whether the operation has succeed.

MakeDexFileTrusted()

bool lsplant::v2::MakeDexFileTrusted	(	JNIEnv *	env,
		jobject	cookie
	)

Make a DexFile trustable so that it can access hidden APIs. This is useful because we likely need to access hidden APIs when hooking system methods. A concern of this function is that cookie of the DexFile maybe a hidden APIs. So get please get the needed jfieldID beforehand (like in JNI_OnLoad as Init()).

Parameters

[in]	env	The Java environment.
[in]	cookie	The cookie of the DexFile.

Returns

Indicate whether the operation has succeed.

UnHook()

bool lsplant::v2::UnHook	(	JNIEnv *	env,
		jobject	target_method
	)

Unhook a Java function that is previously hooked.

Parameters

[in]	env	The Java environment.
[in]	target_method	The target method that is previously hooked.

Returns

Indicate whether the unhook succeed.

Note

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

See also

Hook()