From 8cd8c9901d4420ce523eb5e0496826859d5877d7 Mon Sep 17 00:00:00 2001 From: Corina Date: Tue, 18 May 2021 13:53:16 +0000 Subject: [PATCH] Clarify javadocs about mode to parse file. Bug: 185900460 Test: atest Change-Id: I72b743affd9c1c47650c4249e855676203033f5e --- .../java/android/content/ContentProvider.java | 32 ++++++------------- .../java/android/content/ContentResolver.java | 19 +++++------ .../java/android/os/ParcelFileDescriptor.java | 22 +++++++++++-- 3 files changed, 40 insertions(+), 33 deletions(-) diff --git a/core/java/android/content/ContentProvider.java b/core/java/android/content/ContentProvider.java index 7e1df1b0e59cf..88686a309ee40 100644 --- a/core/java/android/content/ContentProvider.java +++ b/core/java/android/content/ContentProvider.java @@ -1885,9 +1885,8 @@ public abstract class ContentProvider implements ContentInterface, ComponentCall * in {@link android.provider.MediaStore.MediaColumns}.

* * @param uri The URI whose file is to be opened. - * @param mode Access mode for the file. May be "r" for read-only access, - * "rw" for read and write access, or "rwt" for read and write access - * that truncates any existing file. + * @param mode The string representation of the file mode. Can be "r", "w", "wt", "wa", "rw" + * or "rwt". See{@link ParcelFileDescriptor#parseMode} for more details. * * @return Returns a new ParcelFileDescriptor which you can use to access * the file. @@ -1948,10 +1947,8 @@ public abstract class ContentProvider implements ContentInterface, ComponentCall * in {@link android.provider.MediaStore.MediaColumns}.

* * @param uri The URI whose file is to be opened. - * @param mode Access mode for the file. May be "r" for read-only access, - * "w" for write-only access, "rw" for read and write access, or - * "rwt" for read and write access that truncates any existing - * file. + * @param mode The string representation of the file mode. Can be "r", "w", "wt", "wa", "rw" + * or "rwt". See{@link ParcelFileDescriptor#parseMode} for more details. * @param signal A signal to cancel the operation in progress, or * {@code null} if none. For example, if you are downloading a * file from the network to service a "rw" mode request, you @@ -2011,11 +2008,8 @@ public abstract class ContentProvider implements ContentInterface, ComponentCall * containing at least the columns specified by {@link android.provider.OpenableColumns}.

* * @param uri The URI whose file is to be opened. - * @param mode Access mode for the file. May be "r" for read-only access, - * "w" for write-only access (erasing whatever data is currently in - * the file), "wa" for write-only access to append to any existing data, - * "rw" for read and write access on any existing data, and "rwt" for read - * and write access that truncates any existing file. + * @param mode The string representation of the file mode. Can be "r", "w", "wt", "wa", "rw" + * or "rwt". See{@link ParcelFileDescriptor#parseMode} for more details. * * @return Returns a new AssetFileDescriptor which you can use to access * the file. @@ -2068,11 +2062,8 @@ public abstract class ContentProvider implements ContentInterface, ComponentCall * containing at least the columns specified by {@link android.provider.OpenableColumns}.

* * @param uri The URI whose file is to be opened. - * @param mode Access mode for the file. May be "r" for read-only access, - * "w" for write-only access (erasing whatever data is currently in - * the file), "wa" for write-only access to append to any existing data, - * "rw" for read and write access on any existing data, and "rwt" for read - * and write access that truncates any existing file. + * @param mode The string representation of the file mode. Can be "r", "w", "wt", "wa", "rw" + * or "rwt". See{@link ParcelFileDescriptor#parseMode} for more details. * @param signal A signal to cancel the operation in progress, or * {@code null} if none. For example, if you are downloading a * file from the network to service a "rw" mode request, you @@ -2103,11 +2094,8 @@ public abstract class ContentProvider implements ContentInterface, ComponentCall * by looking up a column named "_data" at the given URI. * * @param uri The URI to be opened. - * @param mode The file mode. May be "r" for read-only access, - * "w" for write-only access (erasing whatever data is currently in - * the file), "wa" for write-only access to append to any existing data, - * "rw" for read and write access on any existing data, and "rwt" for read - * and write access that truncates any existing file. + * @param mode The string representation of the file mode. Can be "r", "w", "wt", "wa", "rw" + * or "rwt". See{@link ParcelFileDescriptor#parseMode} for more details. * * @return Returns a new ParcelFileDescriptor that can be used by the * client to access the file. diff --git a/core/java/android/content/ContentResolver.java b/core/java/android/content/ContentResolver.java index aec39da973f08..265ff331ffa06 100644 --- a/core/java/android/content/ContentResolver.java +++ b/core/java/android/content/ContentResolver.java @@ -1551,7 +1551,8 @@ public abstract class ContentResolver implements ContentInterface { * on these schemes. * * @param uri The desired URI. - * @param mode May be "w", "wa", "rw", or "rwt". + * @param mode The string representation of the file mode. Can be "r", "w", "wt", "wa", "rw" + * or "rwt". See{@link ParcelFileDescriptor#parseMode} for more details. * @return an OutputStream or {@code null} if the provider recently crashed. * @throws FileNotFoundException if the provided URI could not be opened. * @see #openAssetFileDescriptor(Uri, String) @@ -1607,8 +1608,8 @@ public abstract class ContentResolver implements ContentInterface { * provider, use {@link ParcelFileDescriptor#closeWithError(String)}. * * @param uri The desired URI to open. - * @param mode The file mode to use, as per {@link ContentProvider#openFile - * ContentProvider.openFile}. + * @param mode The string representation of the file mode. Can be "r", "w", "wt", "wa", "rw" + * or "rwt". See{@link ParcelFileDescriptor#parseMode} for more details. * @return Returns a new ParcelFileDescriptor pointing to the file or {@code null} if the * provider recently crashed. You own this descriptor and are responsible for closing it * when done. @@ -1650,8 +1651,8 @@ public abstract class ContentResolver implements ContentInterface { * provider, use {@link ParcelFileDescriptor#closeWithError(String)}. * * @param uri The desired URI to open. - * @param mode The file mode to use, as per {@link ContentProvider#openFile - * ContentProvider.openFile}. + * @param mode The string representation of the file mode. Can be "r", "w", "wt", "wa", "rw" + * or "rwt". See{@link ParcelFileDescriptor#parseMode} for more details. * @param cancellationSignal A signal to cancel the operation in progress, * or null if none. If the operation is canceled, then * {@link OperationCanceledException} will be thrown. @@ -1744,8 +1745,8 @@ public abstract class ContentResolver implements ContentInterface { * from any built-in data conversion that a provider implements. * * @param uri The desired URI to open. - * @param mode The file mode to use, as per {@link ContentProvider#openAssetFile - * ContentProvider.openAssetFile}. + * @param mode The string representation of the file mode. Can be "r", "w", "wt", "wa", "rw" + * or "rwt". See{@link ParcelFileDescriptor#parseMode} for more details. * @return Returns a new ParcelFileDescriptor pointing to the file or {@code null} if the * provider recently crashed. You own this descriptor and are responsible for closing it * when done. @@ -1798,8 +1799,8 @@ public abstract class ContentResolver implements ContentInterface { * from any built-in data conversion that a provider implements. * * @param uri The desired URI to open. - * @param mode The file mode to use, as per {@link ContentProvider#openAssetFile - * ContentProvider.openAssetFile}. + * @param mode The string representation of the file mode. Can be "r", "w", "wt", "wa", "rw" + * or "rwt". See{@link ParcelFileDescriptor#parseMode} for more details. * @param cancellationSignal A signal to cancel the operation in progress, or null if * none. If the operation is canceled, then * {@link OperationCanceledException} will be thrown. diff --git a/core/java/android/os/ParcelFileDescriptor.java b/core/java/android/os/ParcelFileDescriptor.java index c0847872a45a0..810bd636de074 100644 --- a/core/java/android/os/ParcelFileDescriptor.java +++ b/core/java/android/os/ParcelFileDescriptor.java @@ -33,7 +33,6 @@ import static android.system.OsConstants.S_IWOTH; import android.annotation.NonNull; import android.annotation.SuppressLint; -import android.annotation.SystemApi; import android.annotation.TestApi; import android.compat.annotation.UnsupportedAppUsage; import android.content.BroadcastReceiver; @@ -46,7 +45,6 @@ import android.system.Os; import android.system.OsConstants; import android.system.StructStat; import android.util.Log; -import android.util.Size; import dalvik.system.CloseGuard; import dalvik.system.VMRuntime; @@ -626,6 +624,26 @@ public class ParcelFileDescriptor implements Parcelable, Closeable { * Converts a string representing a file mode, such as "rw", into a bitmask suitable for use * with {@link #open}. *

+ * The argument must define at least one of the following base access modes: + *

+ * In addition to a base access mode, the following additional modes may + * requested: + * + * * @param mode The string representation of the file mode. Can be "r", "w", "wt", "wa", "rw" * or "rwt". * @return A bitmask representing the given file mode.