constructor);
+ /**
+ * Scans the Java heap for live objects matching the supplied class.
+ *
+ * This can be used to obtain already-created target objects directly instead of installing nested hooks
+ * only to capture them from later calls.
+ *
+ * Returned object references are strong references. Keeping the returned results reachable also keeps
+ * returned objects reachable.
+ *
+ * The framework does not run a garbage collection before scanning. Non-reachable but not-yet-collected objects
+ * will be returned as well. If you need to exclude objects that are only waiting to be collected, you should trigger
+ * garbage collection before calling this method.
+ *
+ * The overload of scanning one class is the same as scanning multiple classes with the batched API.
+ * If you need to scan multiple classes, it is recommended to use the batched API to reduce the number
+ * of heap walks and improve performance.
+ *
+ * @param clazz The class to match. Primitive classes and {@code void.class} are not valid.
+ * @param assignable Whether to match subclasses of the class.
+ * @param The expected type of matching objects
+ * @return An array of matching objects. The array is empty if no matching objects are found.
+ * @throws IllegalArgumentException if the class is primitive or void
+ */
+ @SinceApi(API_103)
+ @NonNull
+ T[] findInstances(@NonNull Class clazz, boolean assignable);
+
+ /**
+ * Scans the Java heap for live objects matching the supplied classes.
+ *
+ * @param classes The classes to match. Primitive classes and {@code void.class} are not valid.
+ * @param assignable Whether to match subclasses of the classes.
+ * @return An array of arrays of matching objects. Each inner array corresponds to the matching objects for the class
+ * at the same index in the input array. The inner arrays are empty if no matching objects are found for that class.
+ * @throws IllegalArgumentException if any class is primitive, void or null
+ * @see #findInstances(Class, boolean)
+ */
+ @SinceApi(API_103)
+ @NonNull
+ Object[][] findInstances(@NonNull Class[] classes, boolean assignable);
+
/**
* Writes a message to the Xposed log.
*
diff --git a/api/src/main/java/io/github/libxposed/api/XposedInterfaceWrapper.java b/api/src/main/java/io/github/libxposed/api/XposedInterfaceWrapper.java
index fdfc9ae..2d0085e 100644
--- a/api/src/main/java/io/github/libxposed/api/XposedInterfaceWrapper.java
+++ b/api/src/main/java/io/github/libxposed/api/XposedInterfaceWrapper.java
@@ -150,6 +150,20 @@ public final CtorInvoker getInvoker(@NonNull Constructor constructor)
return mBase.getInvoker(constructor);
}
+ @NonNull
+ @Override
+ public T[] findInstances(@NonNull Class clazz, boolean assignable) {
+ ensureAttached();
+ return mBase.findInstances(clazz, assignable);
+ }
+
+ @NonNull
+ @Override
+ public Object[][] findInstances(@NonNull Class[] classes, boolean assignable) {
+ ensureAttached();
+ return mBase.findInstances(classes, assignable);
+ }
+
@Override
public final void log(int priority, @Nullable String tag, @NonNull String msg) {
ensureAttached();
diff --git a/api/src/main/java/io/github/libxposed/api/package-info.java b/api/src/main/java/io/github/libxposed/api/package-info.java
index 74a07ca..4bd4036 100644
--- a/api/src/main/java/io/github/libxposed/api/package-info.java
+++ b/api/src/main/java/io/github/libxposed/api/package-info.java
@@ -97,6 +97,15 @@
* getInvoker(Constructor)}. The invoker type controls what part of the hook chain is executed
* (see {@link io.github.libxposed.api.XposedInterface.Invoker.Type Invoker.Type}).
*
+ * Object Scanning (API 103+)
+ *
+ * Find already-created objects by class with
+ * {@link io.github.libxposed.api.XposedInterface#findInstances(java.lang.Class, boolean)} or
+ * {@link io.github.libxposed.api.XposedInterface#findInstances(java.lang.Class[], boolean)}.
+ * This is useful when a module needs a target object that may already exist before its hooks are
+ * installed, avoiding extra nested hooks whose only purpose is to capture that object from later
+ * calls.
+ *
* Module Lifecycle Callbacks
*
* Override the following callbacks in {@link io.github.libxposed.api.XposedModule}: