# HookParam - class | Yuki Hook API
一个使用 Kotlin 构建的高效 Hook API 与 Xposed 模块解决方案

# # HookParam - class

    class HookParam internal constructor(
        private val creatorInstance: YukiMemberHookCreator,
        private var paramId: String,
        private var param: YukiHookCallback.Param?
    )

变更记录

`v1.0` `添加`

`v1.1.0` `修改`

移动 `HookParamWrapper` 到 `YukiHookCallback.Param`

修正拼写错误的 creater 命名到 creator

`v1.1.5` `修改`

新增 `paramId` 参数

功能描述

> Hook 方法、构造方法的目标对象实现类。

## # args - field

    val args: Array<Any?>

变更记录

在 `v1.0` 添加

功能描述

> 获取当前 Hook 对象 `member` 或 `constructor` 的参数对象数组。

这里的数组每项类型默认为 `Any`，你可以使用 `args` 方法来实现 `ArgsModifyer.cast` 功能。

## firstArgs - field

变更记录

`v1.0` `添加`

`v1.0.75` `移除`

请使用 `args(index = 0)` 或 `args().first()`

## lastArgs - field

变更记录

`v1.0` `添加`

`v1.0.75` `移除`

请使用 `args().last()`

## # instance - field

    val instance: Any

变更记录

`v1.0` `添加`

功能描述

> 获取当前 Hook 实例的对象。

特别注意

如果你当前 Hook 的对象是一个静态，那么它将不存在实例的对象。

如果你不确定当前实例的对象是否为 `null`，你可以使用 `instanceOrNull`。

## # instanceOrNull - field

    val instanceOrNull: Any?

变更记录

`v1.1.8` `新增`

功能描述

> 获取当前 Hook 实例的对象。

特别注意

如果你当前 Hook 的对象是一个静态，那么它将不存在实例的对象。

## # instanceClass - field

    val instanceClass: Class<*>

变更记录

`v1.0` `添加`

功能描述

> 获取当前 Hook 实例的类对象。

## # member - field

    val member: Member

变更记录

`v1.1.0` `新增`

功能描述

> 获取当前 Hook 对象的 `Member`。

在不确定 `Member` 类型为 `Method` 或 `Constructor` 时可以使用此方法。

## # method - field

    val method: Method

变更记录

`v1.0` `添加`

功能描述

> 获取当前 Hook 对象的方法。

## # constructor - field

    val constructor: Constructor

变更记录

`v1.0` `添加`

功能描述

> 获取当前 Hook 对象的构造方法。

## # result - field

    var result: Any?

变更记录

`v1.0` `添加`

功能描述

> 获取、设置当前 Hook 对象的 `method` 或 `constructor` 的返回值。

## # dataExtra - field

    val dataExtra: Bundle

变更记录

`v1.1.5` `新增`

功能描述

> 获取当前回调方法体范围内的数据存储实例。

## # hasThrowable - field

    val hasThrowable: Boolean

变更记录

`v1.1.0` `新增`

功能描述

> 判断是否存在设置过的方法调用抛出异常。

## # throwable - field

    val throwable: Throwable?

变更记录

`v1.1.0` `新增`

功能描述

> 获取设置的方法调用抛出异常。

## # Throwable.throwToApp - i-ext-method

    fun Throwable.throwToApp()

变更记录

`v1.1.0` `新增`

功能描述

> 向 Hook APP 抛出异常。

使用 `hasThrowable` 判断当前是否存在被抛出的异常。

使用 `throwable` 获取当前设置的方法调用抛出异常。

仅会在回调方法的 `MemberHookCreator.beforeHook` 或 `MemberHookCreator.afterHook` 中生效。

特别注意

设置后会同时执行 resultNull 方法并将异常抛出给当前 Hook APP。

功能示例

Hook 过程中的异常仅会作用于 (Xposed) 宿主环境，目标 Hook APP 不会受到影响。

若想将异常抛给 Hook APP，可以直接使用如下方法。

> 示例如下

    injectMember {
        method {
            // ...
        }
        beforeHook {
            RuntimeException("Test Exception").throwToApp()
        }
    }

特别注意

向 Hook APP 抛出异常会对其暴露被 Hook 的事实，是不安全的，容易被检测，请按实际场景合理使用。

## # result - method

    inline fun <reified T> result(): T?

变更记录

`v1.0.75` `新增`

功能描述

> 获取当前 Hook 对象的 `method` 或 `constructor` 的返回值 `T`。

## firstArg - method

变更记录

`v1.0.66` `新增`

`v1.0.75` `移除`

## lastArgs - method

变更记录

`v1.0.66` `新增`

`v1.0.75` `移除`

## # instance - method

    inline fun <reified T> instance(): T

变更记录

`v1.0` `添加`

功能描述

> 获取当前 Hook 实例的对象 `T`。

功能示例

你可以通过 `instance` 方法轻松使用泛型 `cast` 为目标对象的类型。

> 示例如下

    instance<Activity>().finish()

## # instanceOrNull - method

    inline fun <reified T> instanceOrNull(): T?

变更记录

`v1.1.8` `新增`

功能描述

> 获取当前 Hook 实例的对象 `T`。

功能示例

用法请参考 instance 方法。

## # args - method

    fun args(): ArgsIndexCondition

变更记录

`v1.0.75` `新增`

功能描述

> 获取当前 Hook 对象的 `method` 或 `constructor` 的参数数组下标实例化类。

## # args - method

    fun args(index: Int): ArgsModifyer

变更记录

`v1.0` `添加`

`v1.0.75` `修改`

默认值 `index = 0` 移动到新的使用方法 `args().first()`

功能描述

> 获取当前 Hook 对象的 `method` 或 `constructor` 的参数实例化对象类。

功能示例

你可以通过 `args` 方法修改当前 Hook 实例的方法、构造方法的参数内容。

你可以直接使用 `set` 方法设置 `param` 为你的目标实例，接受 `Any` 类型。

特别注意

请确保 param 类型为你的目标实例类型。

> 示例如下

    args(index = 0).set("modify the value")

你可以这样直接设置第一位 `param` 的值。

> 示例如下

    args().first().set("modify the value")

你还可以直接设置最后一位 `param` 的值。

> 示例如下

    args().last().set("modify the value")

你还可以使用 `setNull` 方法设置 `param` 为空。

> 示例如下

    args(index = 1).setNull()

你还可以使用 `setTrue` 方法设置 `param` 为 `true`。

特别注意

请确保 param 类型为 Boolean。

> 示例如下

    args(index = 1).setTrue()

你还可以使用 `setFalse` 方法设置 `param` 为 `false`。

特别注意

请确保 param 类型为 Boolean。

> 示例如下

    args(index = 1).setFalse()

## # callOriginal - method

    fun callOriginal(): Any?

    fun <T> callOriginal(): T?

变更记录

`v1.1.0` `新增`

功能描述

> 执行原始 `Member`。

调用自身未进行 Hook 的原始 `Member` 并调用原始参数执行。

功能实例

此方法可以 `invoke` 原始未经 Hook 的 `Member` 对象，取决于原始 `Member` 的参数。

调用自身原始的方法不会再经过当前 `beforeHook`、`afterHook` 以及 `replaceUnit`、`replaceAny`。

比如我们 Hook 的这个方法被这样调用 `test("test value")`，使用此方法会调用其中的 `"test value"` 作为参数。

> 示例如下

    injectMember {
        method {
            name = "test"
            param(StringClass)
            returnType = StringClass
        }
        afterHook {
            // <方案1> 不使用泛型，不获取方法执行结果，调用将使用原方法传入的 args 自动传参
            callOriginal()
            // <方案2> 使用泛型，已知方法执行结果参数类型进行 cast
            // 假设返回值为 String，失败会返回 null，调用将使用原方法传入的 args 自动传参
            val value = callOriginal<String>()
        }
    }

## # invokeOriginal - method

    fun invokeOriginal(vararg args: Any?): Any?

    fun <T> invokeOriginal(vararg args: Any?): T?

变更记录

`v1.0` `添加`

`v1.1.0` `修改`

不再需要使用 `member.invokeOriginal` 进行调用

功能描述

> 执行原始 `Member`。

调用自身未进行 Hook 的原始 `Member` 并自定义 `args` 执行。

功能实例

此方法可以 `invoke` 原始未经 Hook 的 `Member` 对象，可自定义需要调用的参数内容。

调用自身原始的方法不会再经过当前 `beforeHook`、`afterHook` 以及 `replaceUnit`、`replaceAny`。

比如我们 Hook 的这个方法被这样调用 `test("test value")`，使用此方法可自定义其中的 `args` 作为参数。

> 示例如下

    injectMember {
        method {
            name = "test"
            param(StringClass)
            returnType = StringClass
        }
        afterHook {
            // <方案1> 不使用泛型，不获取方法执行结果
            invokeOriginal("test value")
            // <方案2> 使用泛型，已知方法执行结果参数类型进行 cast，假设返回值为 String，失败会返回 null
            val value = invokeOriginal<String>("test value")
        }
    }

## # resultTrue - method

    fun resultTrue()

变更记录

`v1.0` `添加`

功能描述

> 设置当前 Hook 对象方法的 `result` 返回值为 `true`。

特别注意

请确保 result 类型为 Boolean。

## # resultFalse - method

    fun resultFalse()

变更记录

`v1.0` `添加`

功能描述

> 设置当前 Hook 对象方法的 `result` 返回值为 `false`。

特别注意

请确保 result 类型为 Boolean。

## # resultNull - method

    fun resultNull()

变更记录

`v1.0` `添加`

功能描述

注意

此方法将强制设置 Hook 对象方法的 result 为 null。

## # ArgsIndexCondition - class

    inner class ArgsIndexCondition internal constructor()

变更记录

`v1.0.75` `新增`

功能描述

> 对方法参数的数组下标进行实例化类。

### # first - method

    fun first(): ArgsModifyer

变更记录

`v1.0.75` `新增`

功能描述

> 获取当前 Hook 对象的 `method` 或 `constructor` 的参数数组第一位。

### # last - method

    fun last(): ArgsModifyer

变更记录

`v1.0.75` `新增`

功能描述

> 获取当前 Hook 对象的 `method` 或 `constructor` 的参数数组最后一位。

## # ArgsModifyer - class

    inner class ArgsModifyer internal constructor(private val index: Int)

变更记录

`v1.0` `添加`

功能描述

> 对方法参数的修改进行实例化类。

### # cast - method

    fun <T> cast(): T?

变更记录

`v1.0.66` `新增`

`v1.0.68` `修改`

修改 `of` 为 `cast`

功能描述

> 得到方法参数的实例对象 `T`。

### # byte - method

    fun byte(): Byte?

变更记录

`v1.0.68` `新增`

功能描述

> 得到方法参数的实例对象 Byte。

### # int - method

    fun int(): Int

变更记录

`v1.0.66` `新增`

`v1.0.68` `修改`

修改 `ofInt` 为 `int`

功能描述

> 得到方法参数的实例对象 Int。

### # long - method

    fun long(): Long

变更记录

`v1.0.66` `新增`

`v1.0.68` `修改`

修改 `ofLong` 为 `long`

功能描述

> 得到方法参数的实例对象 Long。

### # short - method

    fun short(): Short

变更记录

`v1.0.66` `新增`

`v1.0.68` `修改`

修改 `ofShort` 为 `short`

功能描述

> 得到方法参数的实例对象 Short。

### # double - method

    fun double(): Double

变更记录

`v1.0.66` `新增`

`v1.0.68` `修改`

修改 `ofDouble` 为 `double`

功能描述

> 得到方法参数的实例对象 Double。

### # float - method

    fun float(): Float

变更记录

`v1.0.66` `新增`

`v1.0.68` `修改`

修改 `ofFloat` 为 `float`

功能描述

> 得到方法参数的实例对象 Float。

### # string - method

    fun string(): String

变更记录

`v1.0.66` `新增`

`v1.0.68` `修改`

修改 `ofString` 为 `string`

功能描述

> 得到方法参数的实例对象 String。

### # char - method

    fun char(): Char

变更记录

`v1.0.68` `新增`

功能描述

> 得到方法参数的实例对象 Char。

### # boolean - method

    fun boolean(): Boolean

变更记录

`v1.0.66` `新增`

`v1.0.68` `修改`

修改 `ofBoolean` 为 `boolean`

功能描述

> 得到方法参数的实例对象 Boolean。

### # any - method

    fun any(): Any?

变更记录

`v1.0.77` `新增`

功能描述

> 得到方法参数的实例对象 Any。

### # array - method

    inline fun <reified T> array(): Array<T>

变更记录

`v1.0.68` `新增`

功能描述

> 得到方法参数的实例对象 Array。

### # list - method

    inline fun <reified T> list(): List<T>

变更记录

`v1.0.68` `新增`

功能描述

> 得到方法参数的实例对象 List。

### # set - method

    fun <T> set(any: T?)

变更记录

`v1.0` `添加`

功能描述

> 设置方法参数的实例对象。

### # setNull - method

    fun setNull()

变更记录

`v1.0` `添加`

功能描述

> 设置方法参数的实例对象为 `null`。

### # setTrue - method

    fun setTrue()

变更记录

`v1.0` `添加`

功能描述

> 设置方法参数的实例对象为 `true`。

特别注意

请确保目标对象的类型是 Boolean。

### # setFalse - method

    fun setFalse()

变更记录

`v1.0` `添加`

功能描述

> 设置方法参数的实例对象为 `false`。

特别注意

请确保目标对象的类型是 Boolean。