Tweaks to PPB_VarArrayBuffer in preperation for taking out of Dev.

ppapi/api/dev/ppb_var_array_buffer_dev.idl

Index: ppapi/api/dev/ppb_var_array_buffer_dev.idl
diff --git a/ppapi/api/dev/ppb_var_array_buffer_dev.idl b/ppapi/api/dev/ppb_var_array_buffer_dev.idl
index 909ad715862da5634087fa458fe61b61bacc3fcb..5e83ac33c90de0a93781bf7fa0aa59946c55994a 100644
--- a/ppapi/api/dev/ppb_var_array_buffer_dev.idl
+++ b/ppapi/api/dev/ppb_var_array_buffer_dev.idl
@@ -8,7 +8,7 @@
  */
 
 label Chrome {
-  M17 = 0.1
+  M18 = 0.2
 };
 
 /**
@@ -29,19 +29,50 @@ interface PPB_VarArrayBuffer_Dev {
    *         with a reference count of 1.
    */
   PP_Var Create([in] uint32_t size_in_bytes);
+
   /**
-   * Returns the length of the VarArrayBuffer in bytes.
+   * Retrieves the length of the VarArrayBuffer in bytes.
+   *
+   * @param[in] array The array whose length should be returned.
+   *
+   * @param[out] byte_length The length of the given array.
    *
-   * @return The length of the VarArrayBuffer in bytes.
+   * @return PP_TRUE on success, PP_FALSE on failure.
    */
-  uint32_t ByteLength([in] PP_Var array);
+  PP_Bool ByteLength([in] PP_Var array, [out] 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.

[bbudge, 2012/01/25 22:19:07]

Buffer in this case is the physical address?

[dmichael (off chromium), 2012/01/25 23:50:11]

Yes.

    *
-   * @return A pointer to the buffer for this array.
+   * @return A pointer to the buffer for this array. Returns NULL if the given
+   *         PP_Var is not of type PP_VARTYPE_ARRAY_BUFFER.
    */
   mem_t Map([in] 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([in] PP_Var array);

[bbudge, 2012/01/25 22:19:07]

Kind of confusing mix of Array, ArrayBuffer and VarArrayBuffer used to describe
the same thing. Could you use ArrayBuffer only?

[dmichael (off chromium), 2012/01/25 23:50:11]

Good point, done.

 };