Merge "javaObjectForIBinder: warn rets global and local" am: 2abd02381f

Original change: https://android-review.googlesource.com/c/platform/frameworks/base/+/2067811

Change-Id: If01e9a87aba9c79ae059a8e2dfc174680131a021
Signed-off-by: Automerger Merge Worker <android-build-automerger-merge-worker@system.gserviceaccount.com>

1 files changed, 11 insertions, 1 deletions

diff --git a/core/jni/android_util_Binder.h b/core/jni/android_util_Binder.h
index 9098d46ee29c..d73db6245672 100644
--- a/core/jni/android_util_Binder.h
+++ b/core/jni/android_util_Binder.h
@@ -24,8 +24,18 @@
 
 namespace android {
 
-// Converstion to/from Java IBinder Object and C++ IBinder instance.
+/**
+ * Conversion to Java IBinder Object from C++ IBinder instance.
+ *
+ * WARNING: this function returns global and local references. This can be
+ * figured out using GetObjectRefType. Though, when this function is called
+ * from within a Java context, the local ref will automatically be cleaned
+ * up. If this is called outside of a Java frame,
+ * PushObjectFrame/PopObjectFrame can simulate this automatic cleanup. The
+ * platform provides ScopedLocalFrame as an RAII object for this.
+ */
 extern jobject javaObjectForIBinder(JNIEnv* env, const sp<IBinder>& val);
+/** Conversion from Java IBinder Object to C++ IBinder instance. */
 extern sp<IBinder> ibinderForJavaObject(JNIEnv* env, jobject obj);
 
 extern jobject newParcelFileDescriptor(JNIEnv* env, jobject fileDesc);