Package io.github.libxposed.api

Interface XposedModuleInterface

All Known Implementing Classes:
XposedModule
public interface XposedModuleInterface
Interface for module initialization.

  • Method Details

    • onModuleLoaded

      default void onModuleLoaded(@NonNull XposedModuleInterface.ModuleLoadedParam param)
      Gets notified when a module generation is loaded into the target process.

      This callback is called for the initial module load. Hot reload does not automatically replay this callback or package lifecycle callbacks; modules that opt into hot reload should override onHotReloaded(HotReloadedParam) and explicitly install or replace the hooks they need.

      Parameters:
      param - Information about the process in which the module is loaded
      Throws:
      RuntimeException - Everything the callback throws is caught and logged.

    • onPackageLoaded

      @RequiresApi(29) default void onPackageLoaded(@NonNull XposedModuleInterface.PackageLoadedParam param)
      Gets notified when a R.attr.hasCode package is loaded into the process. This is the time when the default classloader is ready but before the instantiation of AppComponentFactory.

      This callback is invoked only once for each package name loaded into the process, note that a process may load multiple packages, such as R.attr.sharedUserId and Context.createPackageContext(String, int) with Context.CONTEXT_INCLUDE_CODE.

      In system server, the first callback is replaced by onSystemServerStarting(SystemServerStartingParam), so param.isFirstPackage() is never true here.

      Parameters:
      param - Information about the package being loaded
      Throws:
      RuntimeException - Everything the callback throws is caught and logged.

    • onPackageReady

      default void onPackageReady(@NonNull XposedModuleInterface.PackageReadyParam param)
      Gets notified when AppComponentFactory has instantiated the classloader and is ready to create Application.

      This callback is invoked only once for each package name loaded into the process, note that a process may load multiple packages, such as R.attr.sharedUserId and Context.createPackageContext(String, int) with Context.CONTEXT_INCLUDE_CODE.

      In system server, the first callback is replaced by onSystemServerStarting(SystemServerStartingParam), so param.isFirstPackage() is never true here.

      Parameters:
      param - Information about the package being loaded
      Throws:
      RuntimeException - Everything the callback throws is caught and logged.

    • onSystemServerStarting

      default void onSystemServerStarting(@NonNull XposedModuleInterface.SystemServerStartingParam param)
      Gets notified when system server is ready to start critical services. In system server, this callback replaces the first callback phase of onPackageLoaded(PackageLoadedParam) and onPackageReady(PackageReadyParam).
      Parameters:
      param - Information about system server
      Throws:
      RuntimeException - Everything the callback throws is caught and logged.

    • onHotReloading

      @SinceApi(102) default boolean onHotReloading(@NonNull XposedModuleInterface.HotReloadingParam param)
      Gets notified when the module is about to be reloaded. This callback is called when hot reloading is triggered through the service, or by app updating if autoHotReload is set to true in module.prop. App-update hot reloading still proceeds only if this callback returns true.

      This callback runs in old code.

      Hot reloads are serialized per target. Before the old hook handle list is captured, the framework freezes old code so further hook registrations from old code fail. In-flight hook calls keep using the hook chain snapshot that was active when they started.

      Returning true declares that the old generation is ready to be retired. Before returning true, modules must stop all module-owned Java and native threads, unregister native hooks and external callbacks, release JNI global references to module-classloader objects, and clear references to module objects stored by system or app classes.

      Returning false rejects the hot reload request. For service-triggered requests, this is reported as HotReloadResult.Status.FAILED with a null message. If this callback or the subsequent reload operation throws, the request is reported as failed with a framework-provided diagnostic message.

      Parameters:
      param - Information about the hot reloading event
      Returns:
      true to allow hot reloading to proceed, false to cancel hot reloading

    • onHotReloaded

      @SinceApi(102) default void onHotReloaded(@NonNull XposedModuleInterface.HotReloadedParam param)
      Gets notified when the module has been reloaded.

      This callback runs in new code.

      Package lifecycle callbacks are not automatically replayed after hot reload. Override this method to atomically replace old hooks through XposedInterface.HookHandle.replaceHook(XposedInterface.Hooker), remove hooks that should not survive, or perform reload-specific initialization. The default implementation only unhooks all old hooks.

      The framework keeps the previous module generation strongly reachable until this callback finishes. After this callback returns or throws, the framework releases all references it owns to the old generation, except for references required by old hooks that remain installed and any references kept by module code. Classloader collection and unloading of native libraries associated with it are runtime-dependent and are not guaranteed to happen immediately.

      The framework does not call UnregisterNatives, JNI_OnUnload, or dlclose as part of hot reload. If all old Java references are removed while old native threads, callbacks, hooks, or JNI global references are still active, any resulting crash or undefined behavior is a module bug.

      Parameters:
      param - Information about the hot reloaded event