Provide a safer URLLoader ReadResponseBody API

ppapi/c/ppb_url_loader.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.
  */
 
-/* From ppb_url_loader.idl modified Wed Oct  5 14:06:02 2011. */
+/* From ppb_url_loader.idl modified Thu Nov 22 16:52:29 2012. */
 
 #ifndef PPAPI_C_PPB_URL_LOADER_H_
 #define PPAPI_C_PPB_URL_LOADER_H_
 
+#include "ppapi/c/pp_array_output.h"
 #include "ppapi/c/pp_bool.h"
 #include "ppapi/c/pp_completion_callback.h"
 #include "ppapi/c/pp_instance.h"
 #include "ppapi/c/pp_macros.h"
 #include "ppapi/c/pp_resource.h"
 #include "ppapi/c/pp_stdint.h"
 
 #define PPB_URLLOADER_INTERFACE_1_0 "PPB_URLLoader;1.0"
-#define PPB_URLLOADER_INTERFACE PPB_URLLOADER_INTERFACE_1_0
+#define PPB_URLLOADER_INTERFACE_1_1 "PPB_URLLoader;1.1"
+#define PPB_URLLOADER_INTERFACE PPB_URLLOADER_INTERFACE_1_1
 
 /**
  * @file
  * This file defines the <strong>PPB_URLLoader</strong> interface for loading
  * URLs.
  */
 
 
 /**
  * @addtogroup Interfaces
@@ skipping 11 matching lines @@
  * headers. Refer to <code>PPB_URLResponseInfo</code> for further information.
  * -# Call ReadResponseBody() to stream the data for the response.
  *
  * Alternatively, if <code>PP_URLREQUESTPROPERTY_STREAMTOFILE</code> was set on
  * the <code>URLRequestInfo</code> in step #2:
  * - Call FinishStreamingToFile(), after examining the response headers
  * (step #4),  to wait for the downloaded file to be complete.
  * - Then, access the downloaded file using the GetBodyAsFileRef() function of
  * the <code>URLResponseInfo</code> returned in step #4.
  */
-struct PPB_URLLoader_1_0 {
+struct PPB_URLLoader_1_1 {
   /**
    * Create() creates a new <code>URLLoader</code> object. The
    * <code>URLLoader</code> is associated with a particular instance, so that
    * any UI dialogs that need to be shown to the user can be positioned
    * relative to the window containing the instance.
    *
    * @param[in] instance A <code>PP_Instance</code> identifying one instance
    * of a module.
    *
    * @return A <code>PP_Resource</code> corresponding to a URLLoader if
@@ skipping 97 matching lines @@
    * @return A <code>PP_Resource</code> corresponding to the
    * <code>URLResponseInfo</code> if successful, 0 if the loader is not a valid
    * resource or if Open() has not been called.
    */
   PP_Resource (*GetResponseInfo)(PP_Resource loader);
   /**
    * ReadResponseBody() is used to read the response body. 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.
    *
+   * ReadResponseBodyToArray() is preferred to ReadResponseBody() when doing
+   * asynchronous operations.
+   *
    * @param[in] loader A <code>PP_Resource</code> corresponding to a
    * <code>URLLoader</code>.
    * @param[in,out] buffer A pointer to the buffer for the response body.
    * @param[in] bytes_to_read The number of bytes to read.
    * @param[in] callback A <code>PP_CompletionCallback</code> to run on
    * asynchronous completion. The callback will run if the bytes (full or
    * partial) are read or an error occurs asynchronously. This callback will
    * run only if this function returns <code>PP_OK_COMPLETIONPENDING</code>.
    *
    * @return An int32_t containing the number of bytes read or an error code
@@ skipping 29 matching lines @@
    * It is NOT valid to call Open() again after a call to this function.
    *
    * <strong>Note:</strong> If the <code>URLLoader</code> object is destroyed
    * while it is still open, then it will be implicitly closed so you are not
    * required to call Close().
    *
    * @param[in] loader A <code>PP_Resource</code> corresponding to a
    * <code>URLLoader</code>.
    */
   void (*Close)(PP_Resource loader);
+  /**
+   * ReadResponseBody() is used to read the response body. 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.
+   *
+   * @param[in] loader A <code>PP_Resource</code> corresponding to a
+   * <code>URLLoader</code>.
+   * @param[in,out] output A <code>PP_ArrayOutput</code> to hold the output.
+   * @param[in] max_read_length The number of bytes to read.
+   * @param[in] callback A <code>PP_CompletionCallback</code> to run on
+   * asynchronous completion. The callback will run if the bytes (full or
+   * partial) are read or an error occurs asynchronously. This callback will
+   * run only if this function returns <code>PP_OK_COMPLETIONPENDING</code>.
+   *
+   * @return An int32_t containing the number of bytes read or an error code
+   * from <code>pp_errors.h</code>.
+   */
+  int32_t (*ReadResponseBodyToArray)(PP_Resource loader,
+                                     int32_t max_read_length,
+                                     struct PP_ArrayOutput* output,
+                                     struct PP_CompletionCallback callback);
 };
 
-typedef struct PPB_URLLoader_1_0 PPB_URLLoader;
+typedef struct PPB_URLLoader_1_1 PPB_URLLoader;
+
+struct PPB_URLLoader_1_0 {
+  PP_Resource (*Create)(PP_Instance instance);
+  PP_Bool (*IsURLLoader)(PP_Resource resource);
+  int32_t (*Open)(PP_Resource loader,
+                  PP_Resource request_info,
+                  struct PP_CompletionCallback callback);
+  int32_t (*FollowRedirect)(PP_Resource loader,
+                            struct PP_CompletionCallback callback);
+  PP_Bool (*GetUploadProgress)(PP_Resource loader,
+                               int64_t* bytes_sent,
+                               int64_t* total_bytes_to_be_sent);
+  PP_Bool (*GetDownloadProgress)(PP_Resource loader,
+                                 int64_t* bytes_received,
+                                 int64_t* total_bytes_to_be_received);
+  PP_Resource (*GetResponseInfo)(PP_Resource loader);
+  int32_t (*ReadResponseBody)(PP_Resource loader,
+                              void* buffer,
+                              int32_t bytes_to_read,
+                              struct PP_CompletionCallback callback);
+  int32_t (*FinishStreamingToFile)(PP_Resource loader,
+                                   struct PP_CompletionCallback callback);
+  void (*Close)(PP_Resource loader);
+};
 /**
  * @}
  */
 
 #endif  /* PPAPI_C_PPB_URL_LOADER_H_ */