Xposed Method Hooking

Introduction

Xposed method hooking allows your plugin to intercept calls to methods (or constructors) within the application, modify their parameters, change their behavior, or replace their implementation entirely. This is a powerful technique for altering app functionality at a low level.

Hooking Concepts

To hook a method, you need to provide a "hook handler" — a Python class that defines what code to run when the target method is called. The system supports three main ways to interact with a method call.

The Hook Handler Base Classes

For clarity and correctness, you should create your handler by inheriting from one of the abstract base classes provided in base_plugin.py:

MethodHook: Use this when you want to run code before and/or after the original method executes, but still allow the original method to run.
MethodReplacement: Use this when you want to completely replace the original method's logic with your own.

The `param` Object

All hook callback methods receive a param object (de.robv.android.xposed.XC_MethodHook.MethodHookParam) which is your key to interacting with the method call:

param.thisObject: The instance on which the method was called (None for static methods).
param.args: A list-like object of the arguments passed to the method. You can read and modify these. Changes made in before_hooked_method will affect the original call.
param.getResult(): The value returned by the original method. Available in after_hooked_method. You can read and modify this.
param.method: A java.lang.reflect.Member object representing the hooked method or constructor.

A special and very useful feature is param.setResult(new_result). If you set this in before_hooked_method, the original method and any after_hooked_method logic will be skipped entirely. If you want (and it is possible) for the method to return a null result, do param.setResult(None).

Reference: LSPosed XC_MethodHook.java

Filters

You can set filters to control whether your hook callback methods execute. You use filters by applying the @hook_filters decorator to your before_hooked_method or after_hooked_method.

base_plugin.HookFilter:

RESULT_IS_NULL: check if the result is null.
RESULT_IS_TRUE: check if the result is true.
RESULT_IS_FALSE: check if the result is false.
RESULT_NOT_NULL: check if result != null.
ResultIsInstanceOf(clazz): check if result instanceof clazz.
ResultEqual(value): check if result.equals(value).
ResultNotEqual(value): check if !result.equals(value).
ArgumentIsNull(index): check if param.args[index] == null.
ArgumentNotNull(index): check if param.args[index] != null.
ArgumentIsFalse(index): check if param.args[index] == false.
ArgumentIsTrue(index): check if param.args[index] == true.
ArgumentIsInstanceOf(index, clazz): check if param.args[index] instanceof clazz.
ArgumentEqual(index, value): check if param.args[index].equals(value).
ArgumentNotEqual(index, value): check if !param.args[index].equals(value).
Condition(condition, object: Any = None): A MVEL expression. (e.g., "param.args[0] == 1" or "param.args[0] == object" if object is provided to filter function)
Or(*filters): check if at least one of the filters is true.

Examples of usage filters

from base_plugin import MethodHook, hook_filters, HookFilter
 
class Example1(MethodHook):
    # Run `before_hooked_method` only if first argument is null
    @hook_filters(HookFilter.ArgumentIsNull(0))
    def before_hooked_method(self, param):
        ...
    
    # Run `after_hooked_method` only if result of original method is null
    @hook_filters(HookFilter.RESULT_IS_NULL)
    def after_hooked_method(self, param):
        ...
 
class Example2(MethodHook):
    # Run `before_hooked_method` only if first argument is string "TEST" or second argument is true
    @hook_filters(HookFilter.Or(HookFilter.ArgumentEqual(0, "TEST"), HookFilter.ArgumentIsTrue(1)))
    def before_hooked_method(self, param):
        ...
 
        # you can change arguments to your value
        param.args[0] = "EDITED_VALUE"
    
    # Run `after_hooked_method` only if result of original method != null and first arg is edited
    @hook_filters(HookFilter.RESULT_IS_NOT_NULL, HookFilter.ArgumentEqual(0, "EDITED_VALUE"))
    def after_hooked_method(self, param):
        ...
 
 
class Example3(MethodHook):
    # Run `before_hooked_method` only if condition is true
    @hook_filters(HookFilter.Condition(
        "this.attr1 == object || param.args[1] == \"ok\"" # this = param.thisObject
        " || param.args[1] instanceof java.nio.ByteBuffer",
        object=500
    ))
    def before_hooked_method(self, param):
        ...
    
    # Run `after_hooked_method` only if condition is true
    @hook_filters(HookFilter.Condition( # check currect account has premium and class' private value equals value of plugin setting)
        "org.telegram.messenger.AccountInstance.getInstance(org.telegram.messenger.UserConfig.selectedAccount).getUserConfig().isPremium()"
        " || com.exteragram.messenger.utils.AppUtils.getPrivateField(this, \"target_field\") == "
        "com.exteragram.messenger.plugins.PluginsController.getInstance().getPluginSettingString(\"plugin_id\", \"setting_key\", \"default_value\")"
    ))
    def after_hooked_method(self, param):
        ...

The Hooking Process (Step-by-Step)

1. Find the Target Method or Constructor

First, you need a reference to the java.lang.reflect.Method or java.lang.reflect.Constructor you want to hook. This is done using Java reflection.

from hook_utils import find_class
 
# Use find_class for safety. It returns None if the class is not found.
ActionBarClass = find_class("org.telegram.ui.ActionBar.ActionBar")
if not ActionBarClass:
    self.log("ActionBar class not found!")
    return
 
# --- Finding a Method ---
# Example: public void setTitle(CharSequence title)
try:
    # Get the class for the parameter type
    CharSequenceClass = find_class("java.lang.CharSequence")
    # Get the method
    method_to_hook = ActionBarClass.getClass().getDeclaredMethod("setTitle", CharSequenceClass)
    method_to_hook.setAccessible(True)  # Important for non-public methods
except Exception as e:
    self.log(f"Failed to find method 'setTitle': {e}")
 
# --- Finding a Constructor ---
# Example: public ActionBar(Context context)
try:
    ContextClass = find_class("android.content.Context")
    constructor_to_hook = ActionBarClass.getClass().getDeclaredConstructor(ContextClass)
    constructor_to_hook.setAccessible(True) # Important for non-public constructors
except Exception as e:
    self.log(f"Failed to find constructor: {e}")

2. Implement the Hook Handler

Create a Python class that inherits from MethodHook or MethodReplacement and implements the required callback(s).

from base_plugin import MethodHook, MethodReplacement
 
# For running code before/after the original method
class TitleLoggerHook(MethodHook):
    def __init__(self, plugin):
        self.plugin = plugin # Pass your plugin instance for logging, etc.
 
    def before_hooked_method(self, param):
        title = param.args[0]
        self.plugin.log(f"ActionBar title is being set to: {title}")
        # Let's add a prefix to every title
        param.args[0] = f"[Hooked] {title}"
 
    def after_hooked_method(self, param):
        self.plugin.log(f"ActionBar title has been set.")
 
 
# For completely replacing the original method
class TitleReplacer(MethodReplacement):
    def __init__(self, plugin):
        self.plugin = plugin
 
    def replace_hooked_method(self, param):
        self.plugin.log("ActionBar.setTitle() was called, but we are blocking it.")
        # The original method is NOT called.
        # Since the original method returns void, we don't need to return anything.
        return None

3. Apply the Hook

From your BasePlugin class, instantiate your handler and call self.hook_method().

# In your on_plugin_load method or another appropriate place:
 
# Get the method to hook (as shown in Step 1)
try:
    ActionBarClass = find_class("org.telegram.ui.ActionBar.ActionBar")
    CharSequenceClass = find_class("java.lang.CharSequence")
    set_title_method = ActionBarClass.getClass().getDeclaredMethod("setTitle", CharSequenceClass)
 
    # Instantiate your handler and apply the hook
    handler_instance = TitleLoggerHook(self)
    self.unhook_obj = self.hook_method(set_title_method, handler_instance, priority=10)
 
    if self.unhook_obj:
        self.log("Successfully hooked ActionBar.setTitle()")
    else:
        self.log("Failed to hook ActionBar.setTitle()")
 
except Exception as e:
    self.log(f"Error during hooking setup: {e}")
 
# Hooks are automatically removed when your plugin is unloaded.
# If you need to remove a hook manually, you can use the returned object:
# if self.unhook_obj:
#   self.unhook_method(self.unhook_obj)

4. Hooking Multiple Methods/Constructors

If you need to apply the same hook to all methods with a specific name within a class, or to all of a class's constructors, you can use these convenient helper methods.

self.hook_all_methods(hook_class, method_name, xposed_hook, priority): Hooks all methods with the given method_name in hook_class.
self.hook_all_constructors(hook_class, xposed_hook, priority): Hooks all constructors in hook_class.

These methods return a list of Unhook objects, one for each method/constructor that was hooked.

# Example: Hook all methods named "onMeasure" in a custom View class
try:
    MyViewClass = find_class("com.example.MyCustomView")
    on_measure_handler = MyOnMeasureHook(self)
    unhook_list = self.hook_all_methods(MyViewClass, "onMeasure", on_measure_handler)
    if unhook_list:
        self.log(f"Successfully hooked {len(unhook_list)} 'onMeasure' methods.")
except Exception as e:
    self.log(f"Failed to hook 'onMeasure' methods: {e}")

5. Unhooking Methods

Hooks are automatically removed when your plugin is disabled or unloaded. However, if you need to remove a hook manually, you can call self.unhook_method() and pass it the Unhook object that was returned by the original hook_method() call.

# In your on_plugin_load:
# ... (find method_to_hook) ...
# self.my_unhook_object = self.hook_method(method_to_hook, handler)
 
# Later, in your plugin's logic (e.g., in response to a setting change):
if self.my_unhook_object:
    self.unhook_method(self.my_unhook_object)
    self.log("Manually unhooked the method.")
    self.my_unhook_object = None

If you used hook_all_methods or hook_all_constructors, you would iterate through the returned list and call unhook_method for each item if you need to manually unhook them.

Practical Examples

Example 1: Modifying Arguments (Before Hook)

Let's modify every "Toast" message to add a prefix.

from base_plugin import MethodHook
from hook_utils import find_class
from java import jint
 
class ToastHook(MethodHook):
    def before_hooked_method(self, param):
        # Method signature: makeText(Context context, CharSequence text, int duration)
        original_text = param.args[1]
        param.args[1] = f"(Plugin) {original_text}"
 
# In your plugin's on_plugin_load:
try:
    ToastClass = find_class("android.widget.Toast")
    ContextClass = find_class("android.content.Context")
    CharSequenceClass = find_class("java.lang.CharSequence")
 
    make_text_method = ToastClass.getClass().getDeclaredMethod(
        "makeText", ContextClass, CharSequenceClass, jint
    )
    self.hook_method(make_text_method, ToastHook())
    self.log("Hooked Toast.makeText() successfully.")
except Exception as e:
    self.log(f"Failed to hook Toast: {e}")

Example 2: Changing the Return Value (After Hook)

This example hooks BuildVars.isMainApp() and makes it always return False.

from base_plugin import MethodHook
from hook_utils import find_class
 
class BuildVarsHook(MethodHook):
    def after_hooked_method(self, param):
        # Original result is in param.getResult(), let's change it
        original_result = param.getResult()
 
        # You can pass any value you want here
        param.setResult(False)
 
# In your plugin's on_plugin_load:
try:
    BuildVarsClass = find_class("org.telegram.messenger.BuildVars")
    is_main_app_method = BuildVarsClass.getClass().getDeclaredMethod("isMainApp")
    self.hook_method(is_main_app_method, BuildVarsHook())
    self.log("Hooked BuildVars.isMainApp() to always return False.")
except Exception as e:
    self.log(f"Failed to hook BuildVars: {e}")

Example 3: Skipping the Original Method and return custom value (Before Hook)

This example hooks AndroidUtilities.formatFileSize(size) and skips the original method if the size is less than 1024. (This is a simplified example, you can add more conditions and logic.)

from base_plugin import MethodHook
from hook_utils import find_class
from java.lang import Long, Boolean
 
class FormatFileSizeHook(MethodHook):
    def before_hooked_method(self, param):
        size = param.args[0]
 
        if size < 1024:
            # Сheck your conditions and return your value immediately, skipping the original method and all after_hooked_method
            param.setResult(f"{size} bytes (edited)")
 
# In your plugin's on_plugin_load:
try:
    AndroidUtilitiesClass = find_class("org.telegram.messenger.AndroidUtilities")
    # Target method: public static String formatFileSize(long size, boolean removeZero, boolean makeShort)
    format_file_size_method = AndroidUtilitiesClass.getClass().getDeclaredMethod("formatFileSize", Long.TYPE, Boolean.TYPE, Boolean.TYPE)
    self.hook_method(format_file_size_method, FormatFileSizeHook())
    self.log("Hooked AndroidUtilities.formatFileSize() to edit text output.")
except Exception as e:
    self.log(f"Failed to hook AndroidUtilities: {e}")

Example 4: Replacing a Method (MethodReplacement)

This example completely disables a specific internal logging method to reduce logcat spam.

from base_plugin import MethodReplacement
from hook_utils import find_class
from java.lang import String as JString
 
class NoOpLogger(MethodReplacement):
    def replace_hooked_method(self, param):
        # Do nothing. The original logging method is never called.
        # It's a void method, so we return None.
        return None
 
# In your plugin's on_plugin_load:
try:
    FileLogClass = find_class("org.telegram.messenger.FileLog")
    # Target method: public static void d(String message)
    log_method = FileLogClass.getClass().getDeclaredMethod("d", JString)
    self.hook_method(log_method, NoOpLogger())
    self.log("Disabled FileLog.d(String) method.")
except Exception as e:
    self.log(f"Failed to disable FileLog.d: {e}")

Return Values in MethodReplacement

When using MethodReplacement, your Python replace_hooked_method is the new implementation. You are responsible for returning a value of the correct type.

For void Java methods, return or return None.
For methods returning primitives (e.g., int, boolean), return a standard Python int or bool.
For methods returning objects (e.g., String), return a compatible Python object or None (which becomes null in Java).

Xposed Method Hooking

On this page