Refactor the URLResponseInfo to use new design

ppapi/cpp/file_io.h

 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef PPAPI_CPP_FILE_IO_H_
 #define PPAPI_CPP_FILE_IO_H_
 
 #include "ppapi/c/pp_time.h"
 #include "ppapi/cpp/resource.h"
 
@@ skipping 27 matching lines @@
   /// @param[in] other A pointer to a <code>FileIO</code>.
   FileIO(const FileIO& other);
 
   /// Open() opens the specified regular file for I/O according to the given
   /// open flags, which is a bit-mask of the PP_FileOpenFlags values.  Upon
   /// success, the corresponding file is classified as "in use" by this FileIO
   /// object until such time as the FileIO object is closed or destroyed.
   ///
   /// @param[in] file_ref A <code>PP_Resource</code> corresponding to a file
   /// reference.
+  ///
   /// @param[in] open_flags A bit-mask of the <code>PP_FileOpenFlags</code>
-  /// values.
+  /// values. Valid values are:
+  ///  - PP_FILEOPENFLAG_READ
+  ///  - PP_FILEOPENFLAG_WRITE
+  ///  - PP_FILEOPENFLAG_CREATE
+  ///  - PP_FILEOPENFLAG_TRUNCATE
+  ///  - PP_FILEOPENFLAG_EXCLUSIVE
+  /// See <code>PP_FileOpenFlags</code> in <code>ppb_file_io.h</code> for more
+  /// details on these flags.
+  ///
   /// @param[in] cc A <code>CompletionCallback</code> to be called upon
   /// completion of Open().
   ///
   /// @return An int32_t containing an error code from
   /// <code>pp_errors.h</code>.
   int32_t Open(const FileRef& file_ref,
                int32_t open_flags,
                const CompletionCallback& cc);
 
   /// Query() queries info about the file opened by this FileIO object. This
@@ skipping 16 matching lines @@
   /// @param[in] last_modified_time The last time the FileIO was modified.
   /// @param[in] cc A <code>CompletionCallback</code> to be called upon
   /// completion of Touch().
   ///
   /// @return An int32_t containing an error code from
   /// <code>pp_errors.h</code>.
   int32_t Touch(PP_Time last_access_time,
                 PP_Time last_modified_time,
                 const CompletionCallback& cc);
 
-  /// Read() reads from an offset in the file.  The size of the buffer must be
-  /// large enough to hold the specified number of bytes to read.  This
-  /// function might perform a partial read.
+  /// Reads from an offset in the file.
+  ///
+  /// The size of the buffer must be large enough to hold the specified number
+  /// of bytes to read.  This function might perform a partial read, meaning
+  /// that all the requested bytes might not be returned, even if the end of the
+  /// file has not been reached.
+  ///
+  /// This function reads into a buffer that the caller supplies. This buffer
+  /// must remain valid as long as the FileIO resource is alive. If you use
+  /// a completion callback factory and it goes out of scope, it will not issue
+  /// the callback on your class, BUT the callback factory can NOT cancel
+  /// the request from the browser's perspective. This means that the browser
+  /// will still try to write to your buffer even if the callback factory is
+  /// destroyed!
+  ///
+  /// So you must ensure that your buffer outlives the FileIO resource. If you
+  /// have one class and use the FileIO resource exclusively from that class
+  /// and never make any copies, this will be fine: the resource will be
+  /// destroyed when your class is. But keep in mind that copying a pp::FileIO
+  /// object just creates a second reference to the original resource. For
+  /// example, if you have a function like this:
+  ///   pp::FileIO MyClass::GetFileIO();
+  /// where a copy of your FileIO resource could outlive your class, the
+  /// callback will still be pending when your class goes out of scope, creating
+  /// the possibility of writing into invalid memory. So it's recommended to
+  /// keep your FileIO resource and any oubput buffers tightly controlled in
+  /// the same scope.
   ///
   /// @param[in] offset The offset into the file.
   /// @param[in] buffer The buffer to hold the specified number of bytes read.
   /// @param[in] bytes_to_read The number of bytes to read from
   /// <code>offset</code>.
   /// @param[in] cc A <code>CompletionCallback</code> to be called upon
   /// completion of Read().
   ///
   /// @return An The number of bytes read an error code from
   /// <code>pp_errors.h</code>. If the return value is 0, then end-of-file was
@@ skipping 52 matching lines @@
   ///
   /// <strong>Note:</strong> If the FileIO object is destroyed, and it is still
   /// open, then it will be implicitly closed, so you are not required to call
   /// Close().
   void Close();
 };
 
 }  // namespace pp
 
 #endif  // PPAPI_CPP_FILE_IO_H_