Refactor the URLResponseInfo to use new design

ppapi/cpp/file_io.h

Index: ppapi/cpp/file_io.h
diff --git a/ppapi/cpp/file_io.h b/ppapi/cpp/file_io.h
index 0d8dcc910bbd8794be04016e81a40878ebbd3af3..f3f50adab5444570c3fb565b4385d8deffb740e1 100644
--- a/ppapi/cpp/file_io.h
+++ b/ppapi/cpp/file_io.h
@@ -45,8 +45,17 @@ class FileIO : public Resource {
   ///
   /// @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().
   ///
@@ -83,9 +92,28 @@ class FileIO : public Resource {
                 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, it will not issue the callback on your
+  /// class if it goes out of scope, BUT the callback factory can NOT cancel

[bbudge, 2012/10/12 01:27:06]

This sentance is hard to understand, as 'it' is ambiguous. I think you mean the
callback factory goes out of scope. If so, perhaps you could say:

If you use a completion callback factory and it goes out of scope, ...

+  /// 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 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 and the resource
+  /// (and any pending Read calls) will still be pending. This creates the
+  /// possibility for writing into invalid memory.

[bbudge, 2012/10/12 01:27:06]

I may lack some understanding here. I get how the buffer should outlive the
FileIO resource, but I don't understand about 'one class' and how copying the
resource makes any difference.

   ///
   /// @param[in] offset The offset into the file.
   /// @param[in] buffer The buffer to hold the specified number of bytes read.