Avoid memory allocation for PPB_FileIO Read when callback is blocking.

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/completion_callback.h"
 #include "ppapi/cpp/resource.h"
@@ skipping 53 matching lines @@
   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
   /// function will fail if the FileIO object has not been opened.
   ///
   /// @param[in] result_buf The <code>PP_FileInfo</code> structure representing
   /// all information about the file.
   /// @param[in] cc A <code>CompletionCallback</code> to be called upon
-  /// completion of Query().
+  /// completion of Query(). <code>result_buf</code> must remain valid until
+  /// after the callback runs. If you pass a blocking callback,
+  /// <code>result_buf</code> must remain valid until after Query() returns.
   ///
   /// @return An int32_t containing an error code from
   /// <code>pp_errors.h</code>.
   int32_t Query(PP_FileInfo* result_buf,
                 const CompletionCallback& cc);
 
   /// Touch() Updates time stamps for the file opened by this FileIO object.
   /// This function will fail if the FileIO object has not been opened.
   ///
   /// @param[in] last_access_time The last time the FileIO was accessed.
@@ skipping 46 matching lines @@
   ///
   /// See the other version of Read() which avoids this problem by writing into
   /// CompletionCallbackWithOutput, where the output buffer is automatically
   /// managed by the callback.
   ///
   /// @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().
+  /// completion of Read(). <code>buffer</code> must remain valid until after
+  /// the callback runs. If you pass a blocking callback, <code>buffer</code>
+  /// must remain valid until after Read() returns.
   ///
   /// @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
   /// reached. It is valid to call Read() multiple times with a completion
   /// callback to queue up parallel reads from the file at different offsets.
   int32_t Read(int64_t offset,
                char* buffer,
                int32_t bytes_to_read,
                const CompletionCallback& cc);
 
@@ skipping 82 matching lines @@
   // interface in 1.1.
   //
   // This takes a heap-allocated CallbackData1_0 struct passed as the user data
   // and deletes it when the call completes.
   static void CallbackConverter(void* user_data, int32_t result);
 };
 
 }  // namespace pp
 
 #endif  // PPAPI_CPP_FILE_IO_H_