From 6c91e3d4d9c62eb012bff281b762e725c687f018 Mon Sep 17 00:00:00 2001 From: Nullptr Date: Mon, 16 Jan 2023 22:01:28 +0800 Subject: [PATCH] Remove duplicated methods, consummate docs --- .../github/libxposed/api/XposedContext.java | 4 +- .../libxposed/api/XposedContextWrapper.java | 93 ++++++++++++++++--- .../github/libxposed/api/XposedInterface.java | 67 ++++++------- .../io/github/libxposed/api/XposedModule.java | 16 +++- .../libxposed/api/XposedModuleInterface.java | 81 +++++----------- 5 files changed, 153 insertions(+), 108 deletions(-) diff --git a/api/src/main/java/io/github/libxposed/api/XposedContext.java b/api/src/main/java/io/github/libxposed/api/XposedContext.java index 071be79..db2401c 100644 --- a/api/src/main/java/io/github/libxposed/api/XposedContext.java +++ b/api/src/main/java/io/github/libxposed/api/XposedContext.java @@ -3,7 +3,9 @@ package io.github.libxposed.api; import android.content.Context; /** - * The type Xposed context. + * Independent {@link Context} for each Xposed module loaded into the target process.
+ * This class should be extended by the Xposed framework as the implementation of Xposed interfaces.
+ * Modules should not use this class directly. */ public abstract class XposedContext extends Context implements XposedInterface { diff --git a/api/src/main/java/io/github/libxposed/api/XposedContextWrapper.java b/api/src/main/java/io/github/libxposed/api/XposedContextWrapper.java index 0f7357b..aa6b302 100644 --- a/api/src/main/java/io/github/libxposed/api/XposedContextWrapper.java +++ b/api/src/main/java/io/github/libxposed/api/XposedContextWrapper.java @@ -14,170 +14,233 @@ import java.nio.ByteBuffer; import io.github.libxposed.api.utils.DexParser; /** - * The type Xposed context wrapper. + * Wrap of {@link XposedContext} used by the modules for the purpose of shielding framework implementation details. */ -@SuppressWarnings("unused") +@SuppressWarnings({"deprecation", "unused"}) public class XposedContextWrapper extends ContextWrapper implements XposedInterface { - /** - * Instantiates a new Xposed context wrapper. - * - * @param base the base - */ XposedContextWrapper(@NonNull XposedContext base) { super(base); } - /** - * Instantiates a new Xposed context wrapper. - * - * @param base the base - */ - public XposedContextWrapper(@NonNull XposedContextWrapper base) { + XposedContextWrapper(@NonNull XposedContextWrapper base) { super(base); } /** - * Gets api version. + * Get the Xposed API version of current implementation. * - * @return the api version + * @return API version */ final public int getAPIVersion() { return API; } + /** + * {@inheritDoc} + */ @NonNull @Override final public XposedContext getBaseContext() { return (XposedContext) super.getBaseContext(); } + /** + * {@inheritDoc} + */ @NonNull @Override final public String getFrameworkName() { return getBaseContext().getFrameworkName(); } + /** + * {@inheritDoc} + */ @NonNull @Override final public String getFrameworkVersion() { return getBaseContext().getFrameworkVersion(); } + /** + * {@inheritDoc} + */ @Override final public long getFrameworkVersionCode() { return getBaseContext().getFrameworkVersionCode(); } + /** + * {@inheritDoc} + */ @Override final public int getFrameworkPrivilege() { return getBaseContext().getFrameworkPrivilege(); } + /** + * {@inheritDoc} + */ + @Deprecated @Nullable @Override final public Object featuredMethod(String name, Object... args) { return getBaseContext().featuredMethod(name, args); } + /** + * {@inheritDoc} + */ @NonNull @Override final public MethodUnhooker, Method> hookBefore(@NonNull Method origin, @NonNull BeforeHooker hooker) { return getBaseContext().hookBefore(origin, hooker); } + /** + * {@inheritDoc} + */ @NonNull @Override final public MethodUnhooker, Method> hookAfter(@NonNull Method origin, @NonNull AfterHooker hooker) { return getBaseContext().hookAfter(origin, hooker); } + /** + * {@inheritDoc} + */ @NonNull @Override final public MethodUnhooker, Method> hook(@NonNull Method origin, @NonNull Hooker hooker) { return getBaseContext().hook(origin, hooker); } + /** + * {@inheritDoc} + */ @NonNull @Override final public MethodUnhooker, Method> hookBefore(@NonNull Method origin, int priority, @NonNull BeforeHooker hooker) { return getBaseContext().hookBefore(origin, priority, hooker); } + /** + * {@inheritDoc} + */ @NonNull @Override final public MethodUnhooker, Method> hookAfter(@NonNull Method origin, int priority, @NonNull AfterHooker hooker) { return getBaseContext().hookAfter(origin, priority, hooker); } + /** + * {@inheritDoc} + */ @NonNull @Override final public MethodUnhooker, Method> hook(@NonNull Method origin, int priority, @NonNull Hooker hooker) { return getBaseContext().hook(origin, priority, hooker); } + /** + * {@inheritDoc} + */ @NonNull @Override final public MethodUnhooker>, Constructor> hookBefore(@NonNull Constructor origin, @NonNull BeforeHooker> hooker) { return getBaseContext().hookBefore(origin, hooker); } + /** + * {@inheritDoc} + */ @NonNull @Override final public MethodUnhooker>, Constructor> hookAfter(@NonNull Constructor origin, @NonNull AfterHooker> hooker) { return getBaseContext().hookAfter(origin, hooker); } + /** + * {@inheritDoc} + */ @NonNull @Override final public MethodUnhooker>, Constructor> hook(@NonNull Constructor origin, @NonNull Hooker> hooker) { return getBaseContext().hook(origin, hooker); } + /** + * {@inheritDoc} + */ @NonNull @Override final public MethodUnhooker>, Constructor> hookBefore(@NonNull Constructor origin, int priority, @NonNull BeforeHooker> hooker) { return getBaseContext().hookBefore(origin, priority, hooker); } + /** + * {@inheritDoc} + */ @NonNull @Override final public MethodUnhooker>, Constructor> hookAfter(@NonNull Constructor origin, int priority, @NonNull AfterHooker> hooker) { return getBaseContext().hookAfter(origin, priority, hooker); } + /** + * {@inheritDoc} + */ @NonNull @Override final public MethodUnhooker>, Constructor> hook(@NonNull Constructor origin, int priority, @NonNull Hooker> hooker) { return getBaseContext().hook(origin, priority, hooker); } + /** + * {@inheritDoc} + */ @Override final public boolean deoptimize(@NonNull Method method) { return getBaseContext().deoptimize(method); } + /** + * {@inheritDoc} + */ @Override final public boolean deoptimize(@NonNull Constructor constructor) { return getBaseContext().deoptimize(constructor); } + /** + * {@inheritDoc} + */ @Override final public void log(@NonNull String message) { getBaseContext().log(message); } + /** + * {@inheritDoc} + */ @Override final public void log(@NonNull String message, @NonNull Throwable throwable) { getBaseContext().log(message, throwable); } + /** + * {@inheritDoc} + */ @Nullable @Override final public DexParser parseDex(@NonNull ByteBuffer dexData, boolean includeAnnotations) throws IOException { return getBaseContext().parseDex(dexData, includeAnnotations); } + /** + * {@inheritDoc} + */ @Override final protected void attachBaseContext(Context base) { if (base instanceof XposedContext || base instanceof XposedContextWrapper) { diff --git a/api/src/main/java/io/github/libxposed/api/XposedInterface.java b/api/src/main/java/io/github/libxposed/api/XposedInterface.java index ea78ad3..2718f16 100644 --- a/api/src/main/java/io/github/libxposed/api/XposedInterface.java +++ b/api/src/main/java/io/github/libxposed/api/XposedInterface.java @@ -20,29 +20,30 @@ import io.github.libxposed.api.errors.HookFailedError; import io.github.libxposed.api.utils.DexParser; /** - * The interface Xposed interface. + * Xposed interface for modules to operate on application processes. */ @SuppressWarnings("unused") public interface XposedInterface { /** - * The constant API. + * SDK API version. */ int API = 100; /** - * The constant FRAMEWORK_PRIVILEGE_ROOT. + * Indicates that the framework is running as root. */ int FRAMEWORK_PRIVILEGE_ROOT = 0; /** - * The constant FRAMEWORK_PRIVILEGE_CONTAINER. + * Indicates that the framework is running in a container with a fake system_server. */ int FRAMEWORK_PRIVILEGE_CONTAINER = 1; /** - * The constant FRAMEWORK_PRIVILEGE_APP. + * Indicates that the framework is running as a different app, which may have at most shell permission. */ int FRAMEWORK_PRIVILEGE_APP = 2; /** - * The constant FRAMEWORK_PRIVILEGE_EMBEDDED. + * Indicates that the framework is embedded in the hooked app, + * which means {@link #getSharedPreferences} will be null and remote file is unsupported. */ int FRAMEWORK_PRIVILEGE_EMBEDDED = 3; @@ -321,42 +322,46 @@ public interface XposedInterface { } /** - * Gets framework name. + * Get the Xposed framework name of current implementation. * - * @return the framework name + * @return Framework name */ @NonNull String getFrameworkName(); /** - * Gets framework version. + * Get the Xposed framework version of current implementation. * - * @return the framework version + * @return Framework version */ @NonNull String getFrameworkVersion(); /** - * Gets framework version code. + * Get the Xposed framework version code of current implementation. * - * @return the framework version code + * @return Framework version code */ long getFrameworkVersionCode(); /** - * Gets framework privilege. + * Get the Xposed framework privilege of current implementation. * - * @return the framework privilege + * @return Framework privilege */ int getFrameworkPrivilege(); /** - * Featured method object. + * Additional methods provided by specific Xposed framework. * - * @param name the name - * @param args the args - * @return the object + * @param name Featured method name + * @param args Featured method arguments + * @return Featured method result + * @throws UnsupportedOperationException If the framework does not provide a method with given name + * @deprecated Normally, modules should never rely on implementation details about the Xposed framework, + * but if really necessary, this method can be used to acquire such information */ + @Deprecated @Nullable Object featuredMethod(String name, Object... args); @@ -367,7 +372,7 @@ public interface XposedInterface { * @param hooker the hooker * @return the method unhooker * @throws IllegalArgumentException if origin is abstract, framework internal or {@link Method#invoke} - * @throws HookFailedError if hook fails due to framework internal error + * @throws HookFailedError if hook fails due to framework internal error */ @NonNull MethodUnhooker, Method> hookBefore(@NonNull Method origin, @NonNull BeforeHooker hooker); @@ -379,7 +384,7 @@ public interface XposedInterface { * @param hooker the hooker * @return the method unhooker * @throws IllegalArgumentException if origin is abstract, framework internal or {@link Method#invoke} - * @throws HookFailedError if hook fails due to framework internal error + * @throws HookFailedError if hook fails due to framework internal error */ @NonNull MethodUnhooker, Method> hookAfter(@NonNull Method origin, @NonNull AfterHooker hooker); @@ -391,7 +396,7 @@ public interface XposedInterface { * @param hooker the hooker * @return the method unhooker * @throws IllegalArgumentException if origin is abstract, framework internal or {@link Method#invoke} - * @throws HookFailedError if hook fails due to framework internal error + * @throws HookFailedError if hook fails due to framework internal error */ @NonNull MethodUnhooker, Method> hook(@NonNull Method origin, @NonNull Hooker hooker); @@ -404,7 +409,7 @@ public interface XposedInterface { * @param hooker the hooker * @return the method unhooker * @throws IllegalArgumentException if origin is abstract, framework internal or {@link Method#invoke} - * @throws HookFailedError if hook fails due to framework internal error + * @throws HookFailedError if hook fails due to framework internal error */ @NonNull MethodUnhooker, Method> hookBefore(@NonNull Method origin, int priority, @NonNull BeforeHooker hooker); @@ -417,7 +422,7 @@ public interface XposedInterface { * @param hooker the hooker * @return the method unhooker * @throws IllegalArgumentException if origin is abstract, framework internal or {@link Method#invoke} - * @throws HookFailedError if hook fails due to framework internal error + * @throws HookFailedError if hook fails due to framework internal error */ @NonNull MethodUnhooker, Method> hookAfter(@NonNull Method origin, int priority, @NonNull AfterHooker hooker); @@ -430,7 +435,7 @@ public interface XposedInterface { * @param hooker the hooker * @return the method unhooker * @throws IllegalArgumentException if origin is abstract, framework internal or {@link Method#invoke} - * @throws HookFailedError if hook fails due to framework internal error + * @throws HookFailedError if hook fails due to framework internal error */ @NonNull MethodUnhooker, Method> hook(@NonNull Method origin, int priority, @NonNull Hooker hooker); @@ -443,7 +448,7 @@ public interface XposedInterface { * @param hooker the hooker * @return the method unhooker * @throws IllegalArgumentException if origin is abstract, framework internal or {@link Method#invoke} - * @throws HookFailedError if hook fails due to framework internal error + * @throws HookFailedError if hook fails due to framework internal error */ @NonNull MethodUnhooker>, Constructor> hookBefore(@NonNull Constructor origin, @NonNull BeforeHooker> hooker); @@ -456,7 +461,7 @@ public interface XposedInterface { * @param hooker the hooker * @return the method unhooker * @throws IllegalArgumentException if origin is abstract, framework internal or {@link Method#invoke} - * @throws HookFailedError if hook fails due to framework internal error + * @throws HookFailedError if hook fails due to framework internal error */ @NonNull MethodUnhooker>, Constructor> hookAfter(@NonNull Constructor origin, @NonNull AfterHooker> hooker); @@ -469,7 +474,7 @@ public interface XposedInterface { * @param hooker the hooker * @return the method unhooker * @throws IllegalArgumentException if origin is abstract, framework internal or {@link Method#invoke} - * @throws HookFailedError if hook fails due to framework internal error + * @throws HookFailedError if hook fails due to framework internal error */ @NonNull MethodUnhooker>, Constructor> hook(@NonNull Constructor origin, @NonNull Hooker> hooker); @@ -483,7 +488,7 @@ public interface XposedInterface { * @param hooker the hooker * @return the method unhooker * @throws IllegalArgumentException if origin is abstract, framework internal or {@link Method#invoke} - * @throws HookFailedError if hook fails due to framework internal error + * @throws HookFailedError if hook fails due to framework internal error */ @NonNull MethodUnhooker>, Constructor> hookBefore(@NonNull Constructor origin, int priority, @NonNull BeforeHooker> hooker); @@ -497,7 +502,7 @@ public interface XposedInterface { * @param hooker the hooker * @return the method unhooker * @throws IllegalArgumentException if origin is abstract, framework internal or {@link Method#invoke} - * @throws HookFailedError if hook fails due to framework internal error + * @throws HookFailedError if hook fails due to framework internal error */ @NonNull MethodUnhooker>, Constructor> hookAfter(@NonNull Constructor origin, int priority, @NonNull AfterHooker> hooker); @@ -511,7 +516,7 @@ public interface XposedInterface { * @param hooker the hooker * @return the method unhooker * @throws IllegalArgumentException if origin is abstract, framework internal or {@link Method#invoke} - * @throws HookFailedError if hook fails due to framework internal error + * @throws HookFailedError if hook fails due to framework internal error */ @NonNull MethodUnhooker>, Constructor> hook(@NonNull Constructor origin, int priority, @NonNull Hooker> hooker); @@ -560,7 +565,7 @@ public interface XposedInterface { DexParser parseDex(@NonNull ByteBuffer dexData, boolean includeAnnotations) throws IOException; - // Methods the same with context + // Methods the same with Context /** * Gets shared preferences. diff --git a/api/src/main/java/io/github/libxposed/api/XposedModule.java b/api/src/main/java/io/github/libxposed/api/XposedModule.java index 4b3b84c..b77a7d0 100644 --- a/api/src/main/java/io/github/libxposed/api/XposedModule.java +++ b/api/src/main/java/io/github/libxposed/api/XposedModule.java @@ -3,25 +3,33 @@ package io.github.libxposed.api; import androidx.annotation.NonNull; /** - * The type Xposed module. + * Super class which all Xposed module entry classes should extend.
+ * Entry classes will be instantiated exactly once for each process. */ @SuppressWarnings("unused") public abstract class XposedModule extends XposedContextWrapper implements XposedModuleInterface { /** - * Instantiates a new Xposed module. + * Instantiates a new Xposed module.
+ * When the module is loaded into the target process, the constructor will be called. * - * @param base the base - * @param param the param + * @param base The base context provided by the framework, should not be used by the module + * @param param Information about the process in which the module is loaded */ public XposedModule(@NonNull XposedContext base, @NonNull ModuleLoadedParam param) { super(base); } + /** + * {@inheritDoc} + */ @Override public void onPackageLoaded(@NonNull PackageLoadedParam param) { } + /** + * {@inheritDoc} + */ @Override public void onSystemServerLoaded(@NonNull SystemServerLoadedParam param) { diff --git a/api/src/main/java/io/github/libxposed/api/XposedModuleInterface.java b/api/src/main/java/io/github/libxposed/api/XposedModuleInterface.java index 69175b0..52d5cca 100644 --- a/api/src/main/java/io/github/libxposed/api/XposedModuleInterface.java +++ b/api/src/main/java/io/github/libxposed/api/XposedModuleInterface.java @@ -1,128 +1,95 @@ package io.github.libxposed.api; import android.content.pm.ApplicationInfo; -import android.os.Bundle; import androidx.annotation.NonNull; -import androidx.annotation.Nullable; /** - * The interface Xposed module interface. + * Interface for module initialization. */ @SuppressWarnings("unused") public interface XposedModuleInterface { /** - * The interface Module loaded param. + * Wraps information about the process in which the module is loaded. */ interface ModuleLoadedParam { /** - * Is system server boolean. + * Get information about whether the module is running in system server. * - * @return the boolean + * @return {@code true} if the module is running in system server */ boolean isSystemServer(); /** - * Gets process name. + * Get the process name. * - * @return the process name + * @return The process name */ @NonNull String getProcessName(); - - /** - * Gets app data dir. - * - * @return the app data dir - */ - @NonNull - String getAppDataDir(); - - /** - * Gets extras. - * - * @return the extras - */ - @Nullable - Bundle getExtras(); } /** - * The interface System server loaded param. + * Wraps information about system server. */ interface SystemServerLoadedParam { /** - * Gets class loader. + * Get the class loader of system server. * - * @return the class loader + * @return The class loader */ @NonNull ClassLoader getClassLoader(); - - /** - * Gets extras. - * - * @return the extras - */ - @Nullable - Bundle getExtras(); } /** - * The interface Package loaded param. + * Wraps information about the package being loaded. */ interface PackageLoadedParam { /** - * Gets package name. + * Get the package name of the package being loaded. * - * @return the package name + * @return The package name. */ @NonNull String getPackageName(); /** - * Gets app info. + * Get the ApplicationInfo of the package being loaded. * - * @return the app info + * @return The ApplicationInfo. */ @NonNull ApplicationInfo getAppInfo(); /** - * Gets class loader. + * Get the class loader of the package being loaded. * - * @return the class loader + * @return The class loader. */ @NonNull ClassLoader getClassLoader(); /** - * Is first application boolean. + * Get information about whether is this package the first and main package of the app process. * - * @return the boolean + * @return {@code true} if this is the first package. */ - boolean isFirstApplication(); - - /** - * Gets extras. - * - * @return the extras - */ - @Nullable - Bundle getExtras(); + boolean isFirstPackage(); } /** - * On package loaded. + * Get notified when a package is loaded into the app process.
+ * This callback could be invoked multiple times for the same process on each package. * - * @param param the param + * @param param Information about the package being loaded */ void onPackageLoaded(@NonNull PackageLoadedParam param); /** - * On system server loaded. + * Get notified when the system server is loaded. * - * @param param the param + * @param param Information about system server */ void onSystemServerLoaded(@NonNull SystemServerLoadedParam param); }