Tweaks to PPB_VarArrayBuffer in preperation for taking out of Dev.

* Add Unmap.
* Make ByteLength more consistent with the rest of PPAPI.
* Make C++ wrapper not cache the buffer.

BUG=
TEST=


Review URL: http://codereview.chromium.org/9169052

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@119286 0039d316-1c4b-4281-b951-d872f2087c98

1 files changed, 47 insertions, 13 deletions

diff --git a/ppapi/c/dev/ppb_var_array_buffer_dev.h b/ppapi/c/dev/ppb_var_array_buffer_dev.h
index e4daf90..272c8e2 100644
--- a/ppapi/c/dev/ppb_var_array_buffer_dev.h
+++ b/ppapi/c/dev/ppb_var_array_buffer_dev.h
@@ -3,7 +3,7 @@
  * found in the LICENSE file.
  */
 
-/* From dev/ppb_var_array_buffer_dev.idl modified Wed Dec 14 18:08:00 2011. */
+/* From dev/ppb_var_array_buffer_dev.idl modified Thu Jan 26 11:25:54 2012. */
 
 #ifndef PPAPI_C_DEV_PPB_VAR_ARRAY_BUFFER_DEV_H_
 #define PPAPI_C_DEV_PPB_VAR_ARRAY_BUFFER_DEV_H_
@@ -13,9 +13,9 @@
 #include "ppapi/c/pp_stdint.h"
 #include "ppapi/c/pp_var.h"
 
-#define PPB_VAR_ARRAY_BUFFER_DEV_INTERFACE_0_1 "PPB_VarArrayBuffer(Dev);0.1"
+#define PPB_VAR_ARRAY_BUFFER_DEV_INTERFACE_0_2 "PPB_VarArrayBuffer(Dev);0.2"
 #define PPB_VAR_ARRAY_BUFFER_DEV_INTERFACE \
-    PPB_VAR_ARRAY_BUFFER_DEV_INTERFACE_0_1
+    PPB_VAR_ARRAY_BUFFER_DEV_INTERFACE_0_2
 
 /**
  * @file
@@ -34,33 +34,67 @@
  * these Vars are not part of the embedding page's DOM, and can only be shared
  * with JavaScript via pp::Instance's PostMessage and HandleMessage functions.
  */
-struct PPB_VarArrayBuffer_Dev_0_1 {
+struct PPB_VarArrayBuffer_Dev_0_2 {
   /**
    * Create a zero-initialized VarArrayBuffer.
    *
-   * @param[in] size_in_bytes The size of the array buffer that will be created.
+   * @param[in] size_in_bytes The size of the ArrayBuffer that will be created.
    *
-   * @return A PP_Var which represents an VarArrayBuffer of the requested size
+   * @return A PP_Var which represents a VarArrayBuffer of the requested size
    *         with a reference count of 1.
    */
   struct PP_Var (*Create)(uint32_t size_in_bytes);
   /**
-   * Returns the length of the VarArrayBuffer in bytes.
+   * Retrieves the length of the VarArrayBuffer in bytes. On success,
+   * byte_length is set to the length of the given ArrayBuffer var. On failure,
+   * byte_length is unchanged (this could happen, for instance, if the given
+   * PP_Var is not of type PP_VARTYPE_ARRAY_BUFFER). Note that ByteLength() will
+   * successfully retrieve the the size of an ArrayBuffer even if the
+   * ArrayBuffer is not currently mapped.
    *
-   * @return The length of the VarArrayBuffer in bytes.
+   * @param[in] array The ArrayBuffer whose length should be returned.
+   *
+   * @param[out] byte_length A variable which is set to the length of the given
+   *             ArrayBuffer on success.
+   *
+   * @return PP_TRUE on success, PP_FALSE on failure.
    */
-  uint32_t (*ByteLength)(struct PP_Var array);
+  PP_Bool (*ByteLength)(struct PP_Var array, uint32_t* byte_length);
   /**
-   * Returns a pointer to the beginning of the buffer for the given array.
+   * Maps the ArrayBuffer in to the module's address space and returns a pointer
+   * to the beginning of the buffer for the given ArrayBuffer PP_Var. Note that
+   * calling Map() can be a relatively expensive operation. Use care when
+   * calling it in performance-critical code. For example, you should call it
+   * only once when looping over an ArrayBuffer:
+   *
+   * <code>
+   *   char* data = (char*)(array_buffer_if.Map(array_buffer_var));
+   *   uint32_t byte_length = 0;
+   *   PP_Bool ok = array_buffer_if.ByteLength(array_buffer_var, &byte_length);
+   *   if (!ok)
+   *     return DoSomethingBecauseMyVarIsNotAnArrayBuffer();
+   *   for (uint32_t i = 0; i < byte_length; ++i)
+   *     data[i] = 'A';
+   * </code>
    *
-   * @param[in] array The array whose buffer should be returned.
+   * @param[in] array The ArrayBuffer whose internal buffer should be returned.
    *
-   * @return A pointer to the buffer for this array.
+   * @return A pointer to the internal buffer for this ArrayBuffer. Returns NULL
+   *         if the given PP_Var is not of type PP_VARTYPE_ARRAY_BUFFER.
    */
   void* (*Map)(struct PP_Var array);
+  /**
+   * Unmaps the given ArrayBuffer var from the module address space. Use this if
+   * you want to save memory but might want to Map the buffer again later. The
+   * PP_Var remains valid and should still be released using PPB_Var when you
+   * are done with the ArrayBuffer.
+   *
+   * @param[in] array The ArrayBuffer which should be released.
+   */
+  void (*Unmap)(struct PP_Var array);
 };
 
-typedef struct PPB_VarArrayBuffer_Dev_0_1 PPB_VarArrayBuffer_Dev;
+typedef struct PPB_VarArrayBuffer_Dev_0_2 PPB_VarArrayBuffer_Dev;
 /**
  * @}
  */