EzXHelper Documentation

EzXHelper is modular. You must include the core library, and then choose the appropriate Xposed API compatibility layer and optional utilities based on your target environment.

Modules:

• core: The main library.
• xposed-api-82: For Xposed API 82 compatibility.
• xposed-api-101: For Xposed API 101 compatibility.
• android-utils: (Optional) Provides Android-specific utility extensions.

// build.gradle
dependencies {
    def ezxhelperVersion = '<version>'
    implementation "io.github.kyuubiran.ezxhelper:core:$ezxhelperVersion"
    implementation "io.github.kyuubiran.ezxhelper:xposed-api-82:$ezxhelperVersion"
    implementation "io.github.kyuubiran.ezxhelper:android-utils:$ezxhelperVersion"
}

// build.gradle.kts
dependencies {
    val ezxhelperVersion = "<version>"
    implementation("io.github.kyuubiran.ezxhelper:core:$ezxhelperVersion")
    implementation("io.github.kyuubiran.ezxhelper:xposed-api-82:$ezxhelperVersion")
    implementation("io.github.kyuubiran.ezxhelper:android-utils:$ezxhelperVersion")
}

The HookFactory provides a Kotlin DSL to simplify hooking methods and constructors using the Xposed API. Instead of manually implementing XC_MethodHook, you use a builder-style pattern to define behavior before or after the target execution.

Core DSL Operations:

• before(callback): Executes logic before the method/constructor is called.
• after(callback): Executes logic after the method/constructor has finished.
• replace(callback): Replaces the method's return value by providing a new result via the callback. This is a wrapper around before.
• returnConstant(constant): Forces the method to return a specific constant value. This is a wrapper around before.
• interrupt(): Forces the method to return null.
  • WARNING: This may cause exceptions if the target method is defined to return a non-nullable type.

All these operations are applied to a Method or Constructor and return an XC_MethodHook.Unhook object, which can be used to remove the hook later.

// Example of using the DSL to hook a method
myMethod.createHook {
    before = IMethodHookCallback { param -> 
        // logic before
    }
    replace { param -> 
        // return a new value
        "new value"
    }
}

The HookFactory provides a Kotlin DSL for defining hook behaviors for Java Method or Constructor objects using the Xposed API 101. You can define a chain of execution stages including before, after, and replace logic.

Available DSL Stages

• before { param -> ... }: Executes logic before the target method/constructor is invoked. Receives a HookParam object.
• after { param -> ... }: Executes logic after the target method/constructor has been invoked. Receives a HookParam object.
• replace { param -> return value }: Replaces the original method result with the value returned by the callback.
• returnConstant(value): A shorthand to replace the method result with a specific constant.
• interrupt(): A shorthand to interrupt the method and return null.
• exceptionMode(mode): Sets the XposedInterface.ExceptionMode for the hook.

Hooking Methods

You can use extension functions on Method objects to create various types of hooks:

• createHook: Full control over the execution chain via a HookFactory block.
• createBeforeHook: Specifically for before logic.
• createAfterHook: Specifically for after logic.
• hook: Low-level intercept using an XposedInterface.Hooker.

// Example: Hooking a method with a before and after stage
val targetMethod: Method = ...
targetMethod.createHook(priority = 10) {
    before { param -> 
        // Do something before invocation
    }
    after { param -> 
        // Do something after invocation
    }
    replace { param -> 
        // Return a custom result
        "new result"
    }
}

// Example: Simple before hook
targetMethod.createBeforeHook { param ->
    println("Method called with args: ${param.args}")
}

The ConstructorFinder class is a utility for finding and locating constructors within a class or a collection of constructors using sequences. You can initialize it using several static factory methods in the companion object or via extension functions on standard Kotlin/Java types.

Initialization Methods

• From a Class: Use fromClass(clazz: Class<*>) or fromClass(kclazz: KClass<*>) to find constructors declared in a specific class.
• From a Class Name: Use fromClass(clazzName: String, classLoader: ClassLoader) to look up a class by its name string.
• From Collections: Use fromSequence(seq: Sequence<Constructor<*>>), fromArray(array: Array<Constructor<*>>), fromVararg(vararg array: Constructor<*>), or fromIterable(iterable: Iterable<Constructor<*>>) to wrap existing constructor collections.
• Extension Functions: If you have the appropriate imports, you can call .constructorFinder() directly on Class<*>, Array<Constructor<*>>, Iterable<Constructor<*>>, or Sequence<Constructor<*>>.

import io.github.kyuubiran.ezxhelper.core.finder.ConstructorFinder

// Using Class
val finderFromClass = ConstructorFinder.fromClass(MyClass::class.java)

// Using Class Name
val finderByName = ConstructorFinder.fromClass("com.example.MyClass")

// Using Extension Functions
val finderFromExt = MyClass::class.java.constructorFinder()

// Using an Iterable
val myConstructors: List<Constructor<*>> = // ...
val finderFromList = myConstructors.constructorFinder()