ppapi/api/ppb_var_array_buffer.idl

   1 /* Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2  * Use of this source code is governed by a BSD-style license that can be
   3  * found in the LICENSE file.
   4  */
   5
   6 /**
   7  * This file defines the <code>PPB_VarArrayBuffer</code> struct providing
   8  * a way to interact with JavaScript ArrayBuffers.
   9  */
  10
  11 label Chrome {
  12   M18 = 1.0
  13 };
  14
  15 /**
  16  * The <code>PPB_VarArrayBuffer</code> interface provides a way to interact
  17  * with JavaScript ArrayBuffers, which represent a contiguous sequence of
  18  * bytes. Use <code>PPB_Var</code> to manage the reference count for a
  19  * <code>VarArrayBuffer</code>. Note that these Vars are not part of the
  20  * embedding page's DOM, and can only be shared with JavaScript using the
  21  * <code>PostMessage</code> and <code>HandleMessage</code> functions of
  22  * <code>pp::Instance</code>.
  23  */
  24 [macro="PPB_VAR_ARRAY_BUFFER_INTERFACE"]
  25 interface PPB_VarArrayBuffer {
  26   /**
  27    * Create() creates a zero-initialized <code>VarArrayBuffer</code>.
  28    *
  29    * @param[in] size_in_bytes The size of the <code>ArrayBuffer</code> to
  30    * be created.
  31    *
  32    * @return A <code>PP_Var</code> representing a <code>VarArrayBuffer</code>
  33    * of the requested size and with a reference count of 1.
  34    */
  35   PP_Var Create([in] uint32_t size_in_bytes);
  36
  37   /**
  38    * ByteLength() retrieves the length of the <code>VarArrayBuffer</code> in
  39    * bytes. On success, <code>byte_length</code> is set to the length of the
  40    * given <code>ArrayBuffer</code> var. On failure, <code>byte_length</code>
  41    * is unchanged (this could happen, for instance, if the given
  42    * <code>PP_Var</code> is not of type <code>PP_VARTYPE_ARRAY_BUFFER</code>).
  43    * Note that ByteLength() will successfully retrieve the size of an
  44    * <code>ArrayBuffer</code> even if the <code>ArrayBuffer</code> is not
  45    * currently mapped.
  46    *
  47    * @param[in] array The <code>ArrayBuffer</code> whose length should be
  48    * returned.
  49    *
  50    * @param[out] byte_length A variable which is set to the length of the given
  51    * <code>ArrayBuffer</code> on success.
  52    *
  53    * @return <code>PP_TRUE</code> on success, <code>PP_FALSE</code> on failure.
  54    */
  55   PP_Bool ByteLength([in] PP_Var array, [out] uint32_t byte_length);
  56
  57   /**
  58    * Map() maps the <code>ArrayBuffer</code> in to the module's address space
  59    * and returns a pointer to the beginning of the buffer for the given
  60    * <code>ArrayBuffer PP_Var</code>. ArrayBuffers are copied when transmitted,
  61    * so changes to the underlying memory are not automatically available to
  62    * the embedding page.
  63    *
  64    * Note that calling Map() can be a relatively expensive operation. Use care
  65    * when calling it in performance-critical code. For example, you should call
  66    * it only once when looping over an <code>ArrayBuffer</code>.
  67    *
  68    * <strong>Example:</strong>
  69    *
  70    * @code
  71    * char* data = (char*)(array_buffer_if.Map(array_buffer_var));
  72    * uint32_t byte_length = 0;
  73    * PP_Bool ok = array_buffer_if.ByteLength(array_buffer_var, &byte_length);
  74    * if (!ok)
  75    *   return DoSomethingBecauseMyVarIsNotAnArrayBuffer();
  76    * for (uint32_t i = 0; i < byte_length; ++i)
  77    *   data[i] = 'A';
  78    * @endcode
  79    *
  80    * @param[in] array The <code>ArrayBuffer</code> whose internal buffer should
  81    * be returned.
  82    *
  83    * @return A pointer to the internal buffer for this
  84    * <code>ArrayBuffer</code>. Returns <code>NULL</code>
  85    * if the given <code>PP_Var</code> is not of type
  86    * <code>PP_VARTYPE_ARRAY_BUFFER</code>.
  87    */
  88   mem_t Map([in] PP_Var array);
  89
  90   /**
  91    * Unmap() unmaps the given <code>ArrayBuffer</code> var from the module
  92    * address space. Use this if you want to save memory but might want to call
  93    * Map() to map the buffer again later. The <code>PP_Var</code> remains valid
  94    * and should still be released using <code>PPB_Var</code> when you are done
  95    * with the <code>ArrayBuffer</code>.
  96    *
  97    * @param[in] array The <code>ArrayBuffer</code> to be released.
  98    */
  99   void Unmap([in] PP_Var array);
 100 };
 101