From e200ae81573f41e9e1261c6cdc4f9114baab112b Mon Sep 17 00:00:00 2001
From: Daichi Hirono <hirono@google.com>
Date: Tue, 4 Apr 2017 13:13:24 +0900
Subject: [PATCH] Address API review for ProxyFileDescriptorCallback

The CL revise the documentation for ProxyFileDescriptorCallback.

 * Added explanation to onFsync.
 * Added explanation about offset.
 * Mentioned ErrnoException should contain E constants in OsConstants.

Bug: 35813046
Test: Build succeed
Change-Id: Ied2490b1913445ea8240eb3aaf7c12170ae4e42d
(cherry picked from commit 9555e30288fe984dcb788c496e7582c14faa66da)
---
 .../android/os/ProxyFileDescriptorCallback.java    | 24 ++++++++++++++--------
 1 file changed, 16 insertions(+), 8 deletions(-)

diff --git a/core/java/android/os/ProxyFileDescriptorCallback.java b/core/java/android/os/ProxyFileDescriptorCallback.java
index 2e9f8d9a6439..e69fb55abe8a 100644
--- a/core/java/android/os/ProxyFileDescriptorCallback.java
+++ b/core/java/android/os/ProxyFileDescriptorCallback.java
@@ -21,12 +21,14 @@ import android.system.OsConstants;
 
 /**
  * Callback that handles file system requests from ProxyFileDescriptor.
+ *
+ * @see android.os.storage.StorageManager#openProxyFileDescriptor(int, ProxyFileDescriptorCallback)
  */
 public abstract class ProxyFileDescriptorCallback {
     /**
      * Returns size of bytes provided by the file descriptor.
-     * @return Size of bytes
-     * @throws ErrnoException
+     * @return Size of bytes.
+     * @throws ErrnoException ErrnoException containing E constants in OsConstants.
      */
     public long onGetSize() throws ErrnoException {
         throw new ErrnoException("onGetSize", OsConstants.EBADF);
@@ -35,11 +37,13 @@ public abstract class ProxyFileDescriptorCallback {
     /**
      * Provides bytes read from file descriptor.
      * It needs to return exact requested size of bytes unless it reaches file end.
-     * @param offset Where to read bytes from.
+     * @param offset Offset in bytes from the file head specifying where to read bytes. If a seek
+     *     operation is conducted on the file descriptor, then a read operation is requested, the
+     *     offset refrects the proper position of requested bytes.
      * @param size Size for read bytes.
      * @param data Byte array to store read bytes.
      * @return Size of bytes returned by the function.
-     * @throws ErrnoException
+     * @throws ErrnoException ErrnoException containing E constants in OsConstants.
      */
     public int onRead(long offset, int size, byte[] data) throws ErrnoException {
         throw new ErrnoException("onRead", OsConstants.EBADF);
@@ -47,19 +51,23 @@ public abstract class ProxyFileDescriptorCallback {
 
     /**
      * Handles bytes written to file descriptor.
-     * @param offset Where to write bytes to.
+     * @param offset Offset in bytes from the file head specifying where to write bytes. If a seek
+     *     operation is conducted on the file descriptor, then a write operation is requested, the
+     *     offset refrects the proper position of requested bytes.
      * @param size Size for write bytes.
      * @param data Byte array to be written to somewhere.
      * @return Size of bytes processed by the function.
-     * @throws ErrnoException
+     * @throws ErrnoException ErrnoException containing E constants in OsConstants.
      */
     public int onWrite(long offset, int size, byte[] data) throws ErrnoException {
         throw new ErrnoException("onWrite", OsConstants.EBADF);
     }
 
     /**
-     * Processes fsync request.
-     * @throws ErrnoException
+     * Ensures all the written data are stored in permanent storage device.
+     * For example, if it has data stored in on memory cache, it needs to flush data to storage
+     * device.
+     * @throws ErrnoException ErrnoException containing E constants in OsConstants.
      */
     public void onFsync() throws ErrnoException {
         throw new ErrnoException("onFsync", OsConstants.EINVAL);
-- 
2.11.0