am c78f9a0e: am 3c1363be: am 2f0dc6d9: Merge "COMMENT ONLY change to add some warnings about ParcelFileDescriptor behavior with Parcel.writeValue()." into froyo
Merge commit 'c78f9a0e1ba931988144a52c54bc05a7e1521f67'
* commit 'c78f9a0e1ba931988144a52c54bc05a7e1521f67':
COMMENT ONLY change to add some warnings about ParcelFileDescriptor
diff --git a/core/java/android/os/Parcel.java b/core/java/android/os/Parcel.java
index b9c9565..31f8719 100644
--- a/core/java/android/os/Parcel.java
+++ b/core/java/android/os/Parcel.java
@@ -440,6 +440,12 @@
/**
* Write a FileDescriptor into the parcel at the current dataPosition(),
* growing dataCapacity() if needed.
+ *
+ * <p class="caution">The file descriptor will not be closed, which may
+ * result in file descriptor leaks when objects are returned from Binder
+ * calls. Use {@link ParcelFileDescriptor#writeToParcel} instead, which
+ * accepts contextual flags and will close the original file descriptor
+ * if {@link Parcelable#PARCELABLE_WRITE_RETURN_VALUE} is set.</p>
*/
public final native void writeFileDescriptor(FileDescriptor val);
@@ -1003,7 +1009,7 @@
/**
* Flatten a generic object in to a parcel. The given Object value may
* currently be one of the following types:
- *
+ *
* <ul>
* <li> null
* <li> String
@@ -1026,7 +1032,7 @@
* <li> Parcelable[]
* <li> CharSequence (as supported by {@link TextUtils#writeToParcel}).
* <li> List (as supported by {@link #writeList}).
- * <li> {@link SparseArray} (as supported by {@link #writeSparseArray}).
+ * <li> {@link SparseArray} (as supported by {@link #writeSparseArray(SparseArray)}).
* <li> {@link IBinder}
* <li> Any object that implements Serializable (but see
* {@link #writeSerializable} for caveats). Note that all of the
@@ -1035,6 +1041,13 @@
* approach is much less efficient and should be avoided whenever
* possible.
* </ul>
+ *
+ * <p class="caution">{@link Parcelable} objects are written with
+ * {@link Parcelable#writeToParcel} using contextual flags of 0. When
+ * serializing objects containing {@link ParcelFileDescriptor}s,
+ * this may result in file descriptor leaks when they are returned from
+ * Binder calls (where {@link Parcelable#PARCELABLE_WRITE_RETURN_VALUE}
+ * should be used).</p>
*/
public final void writeValue(Object v) {
if (v == null) {
@@ -1123,7 +1136,7 @@
/**
* Flatten the name of the class of the Parcelable and its contents
* into the parcel.
- *
+ *
* @param p The Parcelable object to be written.
* @param parcelableFlags Contextual flags as per
* {@link Parcelable#writeToParcel(Parcel, int) Parcelable.writeToParcel()}.
diff --git a/core/java/android/os/ParcelFileDescriptor.java b/core/java/android/os/ParcelFileDescriptor.java
index d26f066..9d213b3 100644
--- a/core/java/android/os/ParcelFileDescriptor.java
+++ b/core/java/android/os/ParcelFileDescriptor.java
@@ -250,6 +250,11 @@
return Parcelable.CONTENTS_FILE_DESCRIPTOR;
}
+ /**
+ * {@inheritDoc}
+ * If {@link Parcelable#PARCELABLE_WRITE_RETURN_VALUE} is set in flags,
+ * the file descriptor will be closed after a copy is written to the Parcel.
+ */
public void writeToParcel(Parcel out, int flags) {
out.writeFileDescriptor(mFileDescriptor);
if ((flags&PARCELABLE_WRITE_RETURN_VALUE) != 0 && !mClosed) {