Tweaks to PPB_VarArrayBuffer in preperation for taking out of Dev.

ppapi/api/dev/ppb_var_array_buffer_dev.idl

 /* 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.
  */
 
 /**
  * This file defines the <code>PPB_VarArrayBuffer_Dev</code> struct.
  */
 
 label Chrome {
-  M17 = 0.1
+  M18 = 0.2
 };
 
 /**
  * PPB_VarArrayBuffer_Dev API. This provides a way to interact with JavaScript
  * ArrayBuffers, which represent a contiguous sequence of bytes. To manage the
  * reference count for a VarArrayBuffer, please see PPB_Var. Note that
  * 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.
  */
 [macro="PPB_VAR_ARRAY_BUFFER_DEV_INTERFACE"]
 interface PPB_VarArrayBuffer_Dev {
   /**
    * 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
    *         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. On success,

[darin (slow to review), 2012/01/26 05:01:44]

In a previous version, you had it so that ByteLength would fail if the
ArrayBuffer is not successfully mapped.  I think we shouldn't require the
ArrayBuffer to be mapped in order to report its length.  Since you don't specify
the behavior of calling ByteLength before Map, maybe it would be good to specify
what happens?  Hopefully, you agree that it should give a non-error :)

[dmichael (off chromium), 2012/01/26 05:43:39]

That was a brief moment of insanity; the patch didn't work that way but I forgot
to fix the comment before uploading :-)
Agreed, done.

+   * 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).
    *
-   * @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([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:
    *
-   * @param[in] array The array whose buffer should be returned.
+   * <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>
    *
-   * @return A pointer to the buffer for this array.
+   * @param[in] array The ArrayBuffer whose internal buffer should be returned.
+   *
+   * @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.
    */
   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);
 };