DexKit

https://luckypray.org/DexKit/en/
Admin
DexKit is a high-performance dex runtime parsing library implemented in C++ with a user-friendly...
Tokens:12,193
Snippets:156
Trust Score:5.8
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install macOS Dependencies

Source: https://luckypray.org/DexKit/en/guide/run-on-desktop.html

Install CMake and Ninja on macOS using Homebrew for DexKit desktop execution.

```bash
brew install cmake ninja

```

--------------------------------

### Install Windows Dependencies

Source: https://luckypray.org/DexKit/en/guide/run-on-desktop.html

Use MSYS2 and pacman to install GCC, CMake, and Ninja on Windows. Ensure mingw64/bin is added to environment variables.

```bash
pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-cmake mingw-w64-x86_64-ninja

```

--------------------------------

### Demo PlayActivity Example

Source: https://luckypray.org/DexKit/en/guide/example.html

This is a sample Android Activity demonstrating obfuscated internal properties and methods. It includes UI elements and event handling for a demo application.

```java
package org.luckypray.dexkit.demo;

import android.os.Bundle;
import android.os.Handler;
import android.os.HandlerThread;
import android.util.Log;
import android.view.View;
import android.widget.Button;
import android.widget.TextView;
import androidx.appcompat.app.AppCompatActivity;
import androidx.appcompat.widget.h;
import java.util.Random;
import org.luckypray.dexkit.demo.annotations.Router;

@Router(path = "/play")
public class PlayActivity extends AppCompatActivity {
    private static final String TAG = "PlayActivity";
    private TextView a;
    private Handler b;

    public void d(View view) {
        Handler handler;
        int i;
        Log.d("PlayActivity", "onClick: rollButton");
        float nextFloat = new Random().nextFloat();
        if (nextFloat < 0.01d) {
            handler = this.b;
            i = -1;
        } else if (nextFloat < 0.987f) {
            handler = this.b;
            i = 0;
        } else {
            handler = this.b;
            i = 114514;
        }
        handler.sendEmptyMessage(i);
    }

    public void e(boolean z) {
        int i;
        if (!z) {
            i = RandomUtil.a();
        } else {
            i = 6;
        }
        String a = h.a("You rolled a ", i);
        this.a.setText(a);
        Log.d("PlayActivity", "rollDice: " + a);
    }

    protected void onCreate(Bundle bundle) {
        super/*androidx.fragment.app.FragmentActivity*/.onCreate(bundle);
        setContentView(0x7f0b001d);
        Log.d("PlayActivity", "onCreate");
        HandlerThread handlerThread = new HandlerThread("PlayActivity");
        handlerThread.start();
        this.b = new PlayActivity$1(this, handlerThread.getLooper());
        this.a = (TextView) findViewById(0x7f080134);
        ((Button) findViewById(0x7f08013a)).setOnClickListener(new a(this));
    }
}

```

--------------------------------

### Obfuscated Java Code Example

Source: https://luckypray.org/DexKit/en

This is an example of obfuscated Java code from a host app that may require dynamic hook adaptation.

```java
public class abc {

    public boolean cvc() {
        boolean b = false;
        // ...
        Log.d("VipCheckUtil", "userInfo: xxxx");
        // ...
        return b;
    }

}

```

--------------------------------

### Example Output - Class Name

Source: https://luckypray.org/DexKit/en/guide/example.html

This output shows the fully qualified name of the class found using the complex matching criteria defined in the previous snippet.

```text
org.luckypray.dexkit.demo.PlayActivity

```

--------------------------------

### Direct API for Class Lookup

Source: https://luckypray.org/DexKit/en/guide/cache-bridge.html

Use Direct APIs when a structured query is not feasible. These APIs require an explicit key as they cannot infer a stable key from query semantics. The example shows finding a class directly.

```kotlin
val clazz = bridge.getClassDirect("play_activity_direct") {
    findClass {
        matcher {
            className("org.luckypray.dexkit.demo.PlayActivity")
        }
    }.single()
}

```

--------------------------------

### Xposed Hook with DexKitBridge in Java

Source: https://luckypray.org/DexKit/en

Demonstrates how to use DexKitBridge in Java to find and hook a method dynamically. Ensure DexKitBridge is closed properly to prevent memory leaks, for example, by using a try-with-resources statement.

```java
class AppHooker {
    static {
        System.loadLibrary("dexkit");
    }

    private ClassLoader hostClassLoader;

    public AppHooker(LoadPackageParam loadPackageParam) {
        this.hostClassLoader = loadPackageParam.classLoader;
        String apkPath = loadPackageParam.appInfo.sourceDir;
        // DexKit creation is a time-consuming operation, please do not create the object repeatedly. 
        // If you need to use it globally, please manage the life cycle yourself and ensure 
        // that the .close() method is called when not needed to prevent memory leaks.
        // Here we use `try-with-resources` to automatically close the DexKitBridge instance.
        try (DexKitBridge bridge = DexKitBridge.create(apkPath)) {
            isVipHook(bridge);
            // Other hook ...
        }
    }

    private void isVipHook(DexKitBridge bridge) {
        MethodData methodData = bridge.findMethod(FindMethod.create()
                .matcher(MethodMatcher.create()
                        // All conditions are optional, you can freely combine them
                        .modifiers(Modifier.PUBLIC)
                        .paramCount(0)
                        .returnType("boolean")
                        .usingStrings("VipCheckUtil", "userInfo:")
                )
        ).single();
        Method method = methodData.getMethodInstance(hostClassLoader);
        XposedBridge.hookMethod(method, XC_MethodReplacement.returnConstant(true));
    }

    // ...
}

```

--------------------------------

### Configure Cache Policy

Source: https://luckypray.org/DexKit/en/guide/cache-bridge.html

Configure global cache behavior by setting `DexKitCacheBridge.cachePolicy`. This example shows caching successful results while not caching failed states.

```kotlin
DexKitCacheBridge.cachePolicy = DexKitCacheBridge.CachePolicy(
    cacheSuccess = true,
    failurePolicy = DexKitCacheBridge.CacheFailurePolicy.NONE
)

```

--------------------------------

### Xposed Hook with DexKitBridge in Kotlin

Source: https://luckypray.org/DexKit/en

Demonstrates how to use DexKitBridge in Kotlin to find and hook a method dynamically. Ensure DexKitBridge is closed properly to prevent memory leaks, for example, by using `Closable.use`.

```kotlin
class AppHooker {
    companion object {
        init { System.loadLibrary("dexkit") }
    }

    private var hostClassLoader: ClassLoader

    public constructor(loadPackageParam: LoadPackageParam) {
        this.hostClassLoader = loadPackageParam.classLoader
        val apkPath = loadPackageParam.appInfo.sourceDir
        // DexKit creation is a time-consuming operation, please do not create the object repeatedly. 
        // If you need to use it globally, please manage the life cycle yourself and ensure 
        // that the .close() method is called when not needed to prevent memory leaks.
        // Here we use `Closable.use` to automatically close the DexKitBridge instance.
        DexKitBridge.create(apkPath).use {
            isVipHook(it)
            // Other hook ...
        }
    }

    private fun isVipHook(bridge: DexKitBridge) {
        val methodData = bridge.findMethod {
            matcher {
                // All conditions are optional, you can freely combine them
                modifiers = Modifier.PUBLIC
                returnType = "boolean"
                paramCount = 0
                usingStrings("VipCheckUtil", "userInfo:")
            }
        }.single()
        val method: Method = methodData.getMethodInstance(hostClassLoader)
        XposedBridge.hookMethod(method, XC_MethodReplacement.returnConstant(true))
    }

    // ...
}

```

--------------------------------

### Run DexKit Main Module

Source: https://luckypray.org/DexKit/en/guide/run-on-desktop.html

Execute the main submodule of DexKit using Gradle to perform testing on the desktop.

```gradle
gradle :main:run

```

--------------------------------

### Find Method with Fuzzy Parameter Matching

Source: https://luckypray.org/DexKit/en/guide/example.html

Illustrates how to find a method using fuzzy parameter matching by using `null` for uncertain or obfuscated parameters. This allows matching methods regardless of the parameter's specific type.

```kotlin
private fun findMethodWithFuzzyParam(bridge: DexKitBridge) {
    bridge.findMethod {
        matcher {
            modifiers = Modifier.PUBLIC or Modifier.STATIC
            returnType = "void"
            // Specify the parameters of the method, if the parameters are uncertain, use null
            paramTypes("android.view.View", null)
            // paramCount = 2 // paramTypes length is 2, which has implicitly determined the number of parameters
            usingStrings("onClick")
        }
    }.single().let {
        println(it)
    }
}


```

--------------------------------

### Configure Packaging Options for JNI Libraries

Source: https://luckypray.org/DexKit/en/guide/quick-start.html

If your project's minSdkVersion is less than 23, you may encounter UnsatisfiedLinkError. Add this configuration to app/build.gradle to resolve it.

```gradle
android {
    packagingOptions {
        jniLibs {
            useLegacyPackaging true
        }
    }
}

```

--------------------------------

### StringMatcher Structure

Source: https://luckypray.org/DexKit/en/guide/structural-zoom-table.html

Defines how to match strings with options for value, match type, and case sensitivity.

```APIDOC
## StringMatcher

### Description
Matches strings based on their value, matching mode, and case sensitivity.

### Parameters
#### Query Parameters
- **value** (String) - Required - The string value to match.
- **matchType** (StringMatchType) - Required - The matching mode (e.g., EXACT, CONTAINS, STARTS_WITH, ENDS_WITH).
- **ignoreCase** (Boolean) - Optional - Whether to ignore case sensitivity during matching.
```

--------------------------------

### Minimal In-Memory Cache Implementation

Source: https://luckypray.org/DexKit/en/guide/cache-bridge.html

A basic implementation of the Cache interface using ConcurrentHashMaps for in-memory storage of string and string list data.

```kotlin
import org.luckypray.dexkit.DexKitCacheBridge
import java.util.concurrent.ConcurrentHashMap

object MemoryCache : DexKitCacheBridge.Cache {
    private val values = ConcurrentHashMap<String, String>()
    private val lists = ConcurrentHashMap<String, List<String>>()

    override fun getString(key: String, default: String?): String? = 
        values[key] ?: default

    override fun putString(key: String, value: String) {
        values[key] = value
    }

    override fun getStringList(key: String, default: List<String>?): List<String>? = 
        lists[key] ?: default

    override fun putStringList(key: String, value: List<String>) {
        lists[key] = value
    }

    override fun remove(key: String) {
        values.remove(key)
        lists.remove(key)
    }

    override fun getAllKeys(): Collection<String> = 
        values.keys + lists.keys

    override fun clearAll() {
        values.clear()
        lists.clear()
    }
}
```

--------------------------------

### Composite Matcher Syntax Sugar (Java Chaining API)

Source: https://luckypray.org/DexKit/en/guide/example.html

Shows how to achieve the same composite matcher logic as the Kotlin DSL but using the Java chaining API. This is useful when Kotlin DSL closures are not available.

```java
MethodMatcher matcher = MethodMatcher.create()
        .declaredClass("org.luckypray.dexkit.demo.PlayActivity")
        .anyOf(
                MethodMatcher.create().name("onCreate"),
                MethodMatcher.create().usingStrings(
                        List.of("onClick"),
                        StringMatchType.Contains,
                        false
                )
        )
        .not(
                MethodMatcher.create().usingStrings(
                        List.of("rollDice: "),
                        StringMatchType.Contains,
                        false
                )
        );


```

--------------------------------

### Composite Matcher Syntax Sugar (Kotlin DSL)

Source: https://luckypray.org/DexKit/en/guide/example.html

Demonstrates using composite matchers like `anyOf` and `not` within the Kotlin DSL for method searching. This allows for complex logical conditions.

```kotlin
private fun findOnCreateWithCompositeMatcher(bridge: DexKitBridge) {
    val method = bridge.findMethod {
        matcher {
            declaredClass("org.luckypray.dexkit.demo.PlayActivity")

            anyOf {
                match { name = "onCreate" }
                match { usingStrings("onClick") }
            }

            not {
                usingStrings("rollDice: ")
            }
        }
    }.single()

    println(method.descriptor)
}


```

--------------------------------

### Optimize findMethod by searching classes first

Source: https://luckypray.org/DexKit/en/guide/performance-optimization.html

This code shows an optimized approach by first finding classes that match the criteria and then searching for methods within those specific classes. This significantly improves performance compared to using `declaredClass` directly in `findMethod`.

```kotlin
private fun goodCode(bridge: DexKitBridge) {
    bridge.findClass {
        matcher {
            usingStrings("getUid", "", "_event")
        }
    }.findMethod {
        matcher {
            modifiers = Modifier.PUBLIC or Modifier.STATIC
            returnType = "long"
            addInvoke {
                name = "parseLong"
            }
            addInvoke {
                name = "toString"
            }
        }
    }.single().let {
        println(it)
    }
}

```

--------------------------------

### Create and Use RecyclableBridge

Source: https://luckypray.org/DexKit/en/guide/cache-bridge.html

Creates a RecyclableBridge for a given app tag and APK path, using Kotlin's `use` block for automatic resource management. Demonstrates fetching a class by its name.

```kotlin
fun findPlayActivity(apkPath: String) {
    DexKitCacheBridge.create(
        appTag = "demo:1.0.0",
        path = apkPath
    ).use { bridge ->
        val playActivity = bridge.getClass("play_activity") {
            matcher {
                className("org.luckypray.dexkit.demo.PlayActivity")
            }
        }
        println(playActivity.typeName)
    }
}
```

--------------------------------

### OpcodesMatcher Structure

Source: https://luckypray.org/DexKit/en/guide/structural-zoom-table.html

Defines how to match opcodes by their integer values, names, match type, and size range.

```APIDOC
## OpcodesMatcher

### Description
Matches opcodes based on their integer values, names, matching mode, and size range.

### Parameters
#### Query Parameters
- **opCodes** (Collection<Int>) - Optional - Matched Int values of opcodes.
- **opNames** (Collection<String>) - Optional - Matched names of opcodes (as per smali syntax).
- **matchType** (OpCodeMatchType) - Required - Matching mode.
- **size** (IntRange) - Optional - Total length range of the opcode.
```

--------------------------------

### BatchFindMethodUsingStrings Query Structure

Source: https://luckypray.org/DexKit/en/guide/structural-zoom-table.html

Allows batch searching for methods using a collection of string-based matchers.

```APIDOC
## BatchFindMethodUsingStrings

### Description
Performs a batch search for methods using a list of string-based matching groups.

### Parameters
#### Query Parameters
- **searchPackages** (Collection<String>) - Optional - List of package names to search.
- **excludePackages** (Collection<String>) - Optional - List of excluded package names.
- **ignorePackagesCase** (Boolean) - Optional - Whether to ignore package name case.
- **searchInClasses** (Collection<ClassData>) - Optional - Search for methods in the specified list of classes.
- **searchInMethods** (Collection<MethodData>) - Optional - Search for methods in the specified list of methods.
- **matchers** (Collection<StringMatchersGroup>) - Required - List of query groups using strings.
```

--------------------------------

### Clone DexKit Repository

Source: https://luckypray.org/DexKit/en/guide/run-on-desktop.html

Clone the DexKit project from its GitHub repository to your local machine.

```git
git clone https://github.com/LuckyPray/DexKit.git

```

--------------------------------

### Initialize DexKitCacheBridge

Source: https://luckypray.org/DexKit/en/guide/cache-bridge.html

Globally initializes DexKitCacheBridge with a custom cache implementation. Optional settings for idle timeout and cache policy can be configured before initialization.

```kotlin
fun initDexKitCache() {
    // Optional: configure how long an idle bridge can stay alive
    DexKitCacheBridge.idleTimeoutMillis = 5_000L
    // Optional: configure whether successful / failed results are cached
    DexKitCacheBridge.cachePolicy = DexKitCacheBridge.CachePolicy(
        cacheSuccess = true,
        failurePolicy = DexKitCacheBridge.CacheFailurePolicy.NONE
    )
    DexKitCacheBridge.init(MemoryCache)
}
```

--------------------------------

### Structured Query with Automatic Key Generation

Source: https://luckypray.org/DexKit/en/guide/cache-bridge.html

Use this structured query format when the query condition is stable and manual key management is not required. The cache key is automatically generated based on the query's `hashKey()`.

```kotlin
val clazz = bridge.getClass {
    matcher {
        className("org.luckypray.dexkit.demo.PlayActivity")
    }
}

```

--------------------------------

### BatchFindClassUsingStrings Query Structure

Source: https://luckypray.org/DexKit/en/guide/structural-zoom-table.html

Allows batch searching for classes using a collection of string-based matchers.

```APIDOC
## BatchFindClassUsingStrings

### Description
Performs a batch search for classes using a list of string-based matching groups.

### Parameters
#### Query Parameters
- **searchPackages** (Collection<String>) - Optional - List of package names to search.
- **excludePackages** (Collection<String>) - Optional - List of excluded package names.
- **ignorePackagesCase** (Boolean) - Optional - Whether to ignore package name case.
- **searchIn** (Collection<ClassData>) - Optional - Search for classes in the specified list of classes.
- **matchers** (Collection<StringMatchersGroup>) - Required - List of query groups using strings.
```

--------------------------------

### Add DexKit Dependency (Groovy)

Source: https://luckypray.org/DexKit/en/guide/quick-start.html

Add the DexKit implementation dependency to your app/build.gradle file. Replace <version> with the desired DexKit version.

```gradle
dependencies {
    // replace <version> with your desired version, e.g. '2.0.0'
    implementation 'org.luckypray:dexkit:<version>'
}

```

--------------------------------

### Add DexKit Dependency (Kotlin)

Source: https://luckypray.org/DexKit/en/guide/quick-start.html

Add the DexKit implementation dependency to your app/build.gradle.kts file. Replace <version> with the desired DexKit version.

```gradle
dependencies {
    // replace <version> with your desired version, e.g. '2.0.0'
    implementation("org.luckypray:dexkit:<version>")
}

```

--------------------------------

### Implement Cache Bridge Listener

Source: https://luckypray.org/DexKit/en/guide/cache-bridge.html

Observe query results and bridge lifecycle events by implementing the CacheBridgeListener interface. Add the listener to monitor cache behavior and bridge status.

```kotlin
val listener = object : DexKitCacheBridge.CacheBridgeListener() {
    override fun onQuerySuccess(info: DexKitCacheBridge.QuerySuccessEvent) {
        println("success: source=${info.source}, key=${info.requestKey}, count=${info.matchCount}")
    }

    override fun onQueryFailure(info: DexKitCacheBridge.QueryFailureEvent) {
        println("failure: source=${info.source}, key=${info.requestKey}, error=${info.error}")
    }

    override fun onBridgeCreated(appTag: String) {
        println("created: $appTag")
    }

    override fun onBridgeReleased(appTag: String) {
        println("released: $appTag")
    }

    override fun onBridgeDestroyed(appTag: String) {
        println("destroyed: $appTag")
    }
}

DexKitCacheBridge.addListener(listener)
```

--------------------------------

### IntRange Structure

Source: https://luckypray.org/DexKit/en/guide/structural-zoom-table.html

Defines a range for integer values with minimum and maximum bounds.

```APIDOC
## IntRange

### Description
Specifies a range for integer values, with optional minimum and maximum bounds.

### Parameters
#### Query Parameters
- **min** (Int) - Optional - Minimum value, default is `0`.
- **max** (Int) - Optional - Maximum value, default is `Int.MAX_VALUE`.
```

--------------------------------

### FindMethod Query Structure

Source: https://luckypray.org/DexKit/en/guide/structural-zoom-table.html

Defines the parameters for searching and matching methods within specified packages, classes, or methods.

```APIDOC
## FindMethod

### Description
Searches for methods based on package names, class lists, method lists, and matching conditions.

### Parameters
#### Query Parameters
- **searchPackages** (Collection<String>) - Optional - List of package names to search.
- **excludePackages** (Collection<String>) - Optional - List of excluded package names.
- **ignorePackagesCase** (Boolean) - Optional - Whether to ignore package name case.
- **searchInClasses** (Collection<ClassData>) - Optional - Search for methods in the specified list of classes.
- **searchInMethods** (Collection<MethodData>) - Optional - Search for methods in the specified list of methods.
- **findFirst** (Boolean) - Optional - Return the first result found immediately; results are not guaranteed to be unique due to multi-threading.
- **matcher** (MethodMatcher) - Optional - Matching conditions for methods.
```

--------------------------------

### Find PlayActivity with Multiple Conditions - Kotlin

Source: https://luckypray.org/DexKit/en/guide/example.html

Use this snippet to locate a specific class by defining detailed criteria for its package, fields, methods, and annotations. Ensure DexKitBridge is initialized before use.

```kotlin
private fun findPlayActivity(bridge: DexKitBridge) {
    val classData = bridge.findClass {
        // Search within the specified package name range
        searchPackages("org.luckypray.dexkit.demo")
        // Exclude the specified package name range
        excludePackages("org.luckypray.dexkit.demo.annotations")
        // ClassMatcher Matcher for classes
        matcher {
            // FieldsMatcher Matcher for fields in a class
            fields {
                // Add a matcher for the field
                add {
                    // Specify the modifiers of the field
                    modifiers = Modifier.PRIVATE or Modifier.STATIC or Modifier.FINAL
                    // Specify the type of the field
                    type = "java.lang.String"
                    // Specify the name of the field
                    name = "TAG"
                }
                // Add a matcher for the field of the specified type
                addForType("android.widget.TextView")
                addForType("android.os.Handler")
                // Specify the number of fields in the class
                count = 3
            }
            // MethodsMatcher Matcher for methods in a class
            methods {
                // Add a matcher for the method
                add {
                    // Specify the modifiers of the method
                    modifiers = Modifier.PROTECTED
                    // Specify the name of the method
                    name = "onCreate"
                    // Specify the return type of the method
                    returnType = "void"
                    // Specify the parameter types of the method, if the parameter types are uncertain,
                    // use null, and this method will implicitly declare the number of parameters
                    paramTypes("android.os.Bundle")
                    // Specify the strings used in the method
                    usingStrings("onCreate")
                }
                add {
                    paramTypes("android.view.View")
                    // Specify the numbers used in the method, the type is Byte, Short, Int, Long, Float, Double
                    usingNumbers(0.01, -1, 0.987, 0, 114514)
                }
                add {
                    paramTypes("boolean")
                    // Specify the methods called in the method list
                    invokeMethods {
                        add {
                            modifiers = Modifier.PUBLIC or Modifier.STATIC
                            returnType = "int"
                            // Specify the strings used in the method called in the method,
                            usingStrings(listOf("getRandomDice: "), StringMatchType.Equals)
                        }
                        // Only need to contain the call to the above method
                        matchType = MatchType.Contains
                    }
                }
                count(1..10)
            }
            // AnnotationsMatcher Matcher for annotations in a class
            annotations {
                // Add a matcher for the annotation
                add {
                    // Specify the type of the annotation
                    type = "org.luckypray.dexkit.demo.annotations.Router"
                    // The annotation needs to contain the specified element
                    addElement {
                        // Specify the name of the element
                        name = "path"
                        // Specify the value of the element
                        stringValue("/play")
                    }
                }
            }
            // Strings used by all methods in the class
            usingStrings("PlayActivity", "onClick", "onCreate")
        }
    }.single()
    println(classData.name)
}
```

--------------------------------

### Read and Deserialize DexKit Method

Source: https://luckypray.org/DexKit/en/guide/example.html

Retrieves a serialized method descriptor from SharedPreferences, deserializes it into a DexMethod object, and then obtains the actual Method instance. Handles cases where the descriptor is not found.

```kotlin
private fun readData(): Method {
    val sp = getSharedPreferences("dexkit", Context.MODE_PRIVATE)
    val descriptor = sp.getString("onClickMethod", null)
    if (descriptor != null) {
        val dexMethod = DexMethod(descriptor)
        // val dexMethod = DexMethod.deserialize(serialize)
        // val dexMethod = ISerializable.deserialize(serialize) as DexMethod
        // val dexMethod = ISerializable.deserializeAs<DexMethod>(serialize)
        val method = dexMethod.getMethodInstance(hostClassLoader)
        return method
    }
    error("No saved")
}
```

--------------------------------

### AccessFlagsMatcher Structure

Source: https://luckypray.org/DexKit/en/guide/structural-zoom-table.html

Defines how to match access flags using bit masks and matching types.

```APIDOC
## AccessFlagsMatcher

### Description
Matches access flags using bit masks and specifies the matching mode.

### Parameters
#### Query Parameters
- **modifiers** (Int) - Required - Bit masks for matching modifiers.
- **matchType** (MatchType) - Required - Matching mode.
```

--------------------------------

### Opt-in to DexKitCacheBridge

Source: https://luckypray.org/DexKit/en/guide/cache-bridge.html

Kotlin callers must explicitly opt in to use the experimental DexKitCacheBridge API.

```kotlin
import org.luckypray.dexkit.annotations.DexKitExperimentalApi

@OptIn(DexKitExperimentalApi::class)
fun useCacheBridge() {
    // use DexKitCacheBridge here
}
```

--------------------------------

### Structured Query with Explicit Key

Source: https://luckypray.org/DexKit/en/guide/cache-bridge.html

Use this when you need cache keys with clear meaning for debugging or migration, or to read cache by key later without rebuilding the query. This method caches the result of the query.

```kotlin
val clazz = bridge.getClass("play_activity") {
    matcher {
        className("org.luckypray.dexkit.demo.PlayActivity")
    }
}

```

--------------------------------

### Read from Cache by Explicit Key

Source: https://luckypray.org/DexKit/en/guide/cache-bridge.html

This form reads only from the cache using a pre-defined key. It is useful when a local config or server-provided key determines which cached result to use. If the key does not exist, a NoSuchElementException is thrown.

```kotlin
val clazz = bridge.getClass("play_activity")

```

--------------------------------

### FindField Query Structure

Source: https://luckypray.org/DexKit/en/guide/structural-zoom-table.html

Defines the parameters for searching and matching fields within specified packages, classes, or fields.

```APIDOC
## FindField

### Description
Searches for fields based on package names, class lists, field lists, and matching conditions.

### Parameters
#### Query Parameters
- **searchPackages** (Collection<String>) - Optional - List of package names to search.
- **excludePackages** (Collection<String>) - Optional - List of excluded package names.
- **ignorePackagesCase** (Boolean) - Optional - Whether to ignore package name case.
- **searchInClasses** (Collection<ClassData>) - Optional - Search for fields in the specified list of classes.
- **searchInFields** (Collection<FieldData>) - Optional - Search for fields in the specified list of fields.
- **findFirst** (Boolean) - Optional - Return the first result found immediately; results are not guaranteed to be unique due to multi-threading.
- **matcher** (FieldMatcher) - Optional - Matching conditions for fields.
```

--------------------------------

### FindClass Query Structure

Source: https://luckypray.org/DexKit/en/guide/structural-zoom-table.html

Defines the parameters for searching and matching classes within specified packages or class lists.

```APIDOC
## FindClass

### Description
Searches for classes based on package names, class lists, and matching conditions.

### Parameters
#### Query Parameters
- **searchPackages** (Collection<String>) - Optional - List of package names to search.
- **excludePackages** (Collection<String>) - Optional - List of excluded package names.
- **ignorePackagesCase** (Boolean) - Optional - Whether to ignore package name case.
- **searchIn** (Collection<ClassData>) - Optional - Search for classes in the specified list of classes.
- **findFirst** (Boolean) - Optional - Return the first result found immediately; results are not guaranteed to be unique due to multi-threading.
- **matcher** (ClassMatcher) - Optional - Matching conditions for classes.
```

--------------------------------

### Find Parent Class Condition Nesting

Source: https://luckypray.org/DexKit/en/guide/example.html

Use DexKit to find a class by specifying a chain of parent classes. This is useful when intermediate parent classes are obfuscated.

```kotlin
private fun findActivity(bridge: DexKitBridge) {
    bridge.findClass {
        matcher { // ClassMatcher
            // androidx.appcompat.app.AppCompatActivity
            superClass { // ClassMatcher
                // androidx.fragment.app.FragmentActivity
                superClass { // ClassMatcher
                    // androidx.activity.ComponentActivity
                    superClass { // ClassMatcher
                        // androidx.core.app.ComponentActivity
                        superClass { // ClassMatcher
                            superClass = "android.app.Activity"
                        }
                    }
                }
            }
        }
    }.forEach {
        // org.luckypray.dexkit.demo.MainActivity
        // org.luckypray.dexkit.demo.PlayActivity
        println(it.name)
    }
}


```

--------------------------------

### Save DexKit Method Query Result

Source: https://luckypray.org/DexKit/en/guide/example.html

Saves the serialized descriptor of a found method to SharedPreferences. Requires DexKitBridge and appropriate matchers.

```kotlin
private fun saveData(bridge: DexKitBridge) {
    bridge.findMethod {
        matcher {
            modifiers = Modifier.PUBLIC or Modifier.STATIC
            returnType = "void"
            paramTypes("android.view.View", null)
            usingStrings("onClick")
        }
    }.single().let {
        val dexMethod = it.toDexMethod()
        val serialize = dexMethod.serialize()
        val sp = getSharedPreferences("dexkit", Context.MODE_PRIVATE)
        sp.edit().putString("onClickMethod", serialize).apply()
    }
}
```

--------------------------------

### Clear Cache for a Specific App Tag

Source: https://luckypray.org/DexKit/en/guide/cache-bridge.html

Remove all cached data associated with a given application tag. This is useful for clearing specific namespaces or when host content changes.

```kotlin
DexKitCacheBridge.clearCache(appTag)
```

--------------------------------

### Temporary Direct Access to DexKitBridge

Source: https://luckypray.org/DexKit/en/guide/cache-bridge.html

Use `withBridge` for temporary, direct access to the underlying `DexKitBridge` for operations not covered by cache APIs. It provides a safe borrow for a single operation and does not automatically cache results.

```kotlin
bridge.withBridge { rawBridge ->
    // Use DexKitBridge directly here
}

```

--------------------------------

### Avoid 'declaredClass' in findMethod for better performance

Source: https://luckypray.org/DexKit/en/guide/performance-optimization.html

This code demonstrates a performance-inefficient way to search for methods using the `declaredClass` condition. It traverses all methods and then applies the condition, leading to significant performance degradation.

```kotlin
private fun badCode(bridge: DexKitBridge) {
    bridge.findMethod {
        matcher {
            declaredClass {
                usingStrings("getUid", "", "_event")
            }
            modifiers = Modifier.PUBLIC or Modifier.STATIC
            returnType = "long"
            addInvoke {
                name = "parseLong"
            }
            addInvoke {
                name = "toString"
            }
        }
    }.single().let {
        println(it)
    }
}

```

--------------------------------

### Configure Idle Timeout for Cache Bridge

Source: https://luckypray.org/DexKit/en/guide/cache-bridge.html

Set the idle timeout for a RecyclableBridge to automatically release the underlying native bridge after a specified duration of inactivity. This is a fallback mechanism to prevent resource leaks.

```kotlin
DexKitCacheBridge.idleTimeoutMillis = 5_000L
```

--------------------------------

### AnnotationEncodeValueMatcher Structure

Source: https://luckypray.org/DexKit/en/guide/structural-zoom-table.html

Specifies various types of values that can be matched within annotations.

```APIDOC
## AnnotationEncodeValueMatcher

### Description
Matches different types of encoded values within an annotation, including primitives, strings, methods, enums, arrays, and nested annotations.

### Parameters
#### Query Parameters
- **byteValue** (Byte) - Optional - Matched byte.
- **shortValue** (Short) - Optional - Matched short integer.
- **charValue** (Char) - Optional - Matched character.
- **intValue** (Int) - Optional - Matched integer.
- **longValue** (Long) - Optional - Matched long integer.
- **floatValue** (Float) - Optional - Matched float.
- **doubleValue** (Double) - Optional - Matched double precision float.
- **stringValue** (StringMatcher) - Optional - Matched string.
- **methodValue** (MethodMatcher) - Optional - Matched method.
- **enumValue** (FieldMatcher) - Optional - Matched enumeration.
- **arrayValue** (AnnotationEncodeArrayMatcher) - Optional - Matched array.
- **annotationValue** (AnnotationMatcher) - Optional - Matched annotation.
- **nullValue** (None) - Optional - Match `null`.
- **boolValue** (Boolean) - Optional - Matched boolean.
```

--------------------------------

### NumberEncodeValueMatcher Structure

Source: https://luckypray.org/DexKit/en/guide/structural-zoom-table.html

Specifies various numeric types that can be matched.

```APIDOC
## NumberEncodeValueMatcher

### Description
Matches different types of numeric encoded values.

### Parameters
#### Query Parameters
- **byteValue** (Byte) - Optional - Matched byte.
- **shortValue** (Short) - Optional - Matched short integer.
- **charValue** (Char) - Optional - Matched character.
- **intValue** (Int) - Optional - Matched integer.
- **longValue** (Long) - Optional - Matched long integer.
- **floatValue** (Float) - Optional - Matched float.
- **doubleValue** (Double) - Optional - Matched double precision float.
```

--------------------------------

### Clear All Cache Data

Source: https://luckypray.org/DexKit/en/guide/cache-bridge.html

Remove all cached data across all application tags. Note that this operation only clears cache data and does not affect active bridge instances.

```kotlin
DexKitCacheBridge.clearAllCache()
```

--------------------------------

### Remove Cache Bridge Listener

Source: https://luckypray.org/DexKit/en/guide/cache-bridge.html

Remove a previously added CacheBridgeListener to stop observing events. This is important for managing resources and preventing memory leaks.

```kotlin
DexKitCacheBridge.removeListener(listener)
```
Tokens:
Raw