ppapi/c/ppb_var_array_buffer.h

   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 /* From ppb_var_array_buffer.idl modified Thu Feb 28 09:24:06 2013. */
   7
   8 #ifndef PPAPI_C_PPB_VAR_ARRAY_BUFFER_H_
   9 #define PPAPI_C_PPB_VAR_ARRAY_BUFFER_H_
  10
  11 #include "ppapi/c/pp_bool.h"
  12 #include "ppapi/c/pp_macros.h"
  13 #include "ppapi/c/pp_stdint.h"
  14 #include "ppapi/c/pp_var.h"
  15
  16 #define PPB_VAR_ARRAY_BUFFER_INTERFACE_1_0 "PPB_VarArrayBuffer;1.0"
  17 #define PPB_VAR_ARRAY_BUFFER_INTERFACE PPB_VAR_ARRAY_BUFFER_INTERFACE_1_0
  18
  19 /**
  20  * @file
  21  * This file defines the <code>PPB_VarArrayBuffer</code> struct providing
  22  * a way to interact with JavaScript ArrayBuffers.
  23  */
  24
  25
  26 /**
  27  * @addtogroup Interfaces
  28  * @{
  29  */
  30 /**
  31  * The <code>PPB_VarArrayBuffer</code> interface provides a way to interact
  32  * with JavaScript ArrayBuffers, which represent a contiguous sequence of
  33  * bytes. Use <code>PPB_Var</code> to manage the reference count for a
  34  * <code>VarArrayBuffer</code>. Note that these Vars are not part of the
  35  * embedding page's DOM, and can only be shared with JavaScript using the
  36  * <code>PostMessage</code> and <code>HandleMessage</code> functions of
  37  * <code>pp::Instance</code>.
  38  */
  39 struct PPB_VarArrayBuffer_1_0 {
  40   /**
  41    * Create() creates a zero-initialized <code>VarArrayBuffer</code>.
  42    *
  43    * @param[in] size_in_bytes The size of the <code>ArrayBuffer</code> to
  44    * be created.
  45    *
  46    * @return A <code>PP_Var</code> representing a <code>VarArrayBuffer</code>
  47    * of the requested size and with a reference count of 1.
  48    */
  49   struct PP_Var (*Create)(uint32_t size_in_bytes);
  50   /**
  51    * ByteLength() retrieves the length of the <code>VarArrayBuffer</code> in
  52    * bytes. On success, <code>byte_length</code> is set to the length of the
  53    * given <code>ArrayBuffer</code> var. On failure, <code>byte_length</code>
  54    * is unchanged (this could happen, for instance, if the given
  55    * <code>PP_Var</code> is not of type <code>PP_VARTYPE_ARRAY_BUFFER</code>).
  56    * Note that ByteLength() will successfully retrieve the size of an
  57    * <code>ArrayBuffer</code> even if the <code>ArrayBuffer</code> is not
  58    * currently mapped.
  59    *
  60    * @param[in] array The <code>ArrayBuffer</code> whose length should be
  61    * returned.
  62    *
  63    * @param[out] byte_length A variable which is set to the length of the given
  64    * <code>ArrayBuffer</code> on success.
  65    *
  66    * @return <code>PP_TRUE</code> on success, <code>PP_FALSE</code> on failure.
  67    */
  68   PP_Bool (*ByteLength)(struct PP_Var array, uint32_t* byte_length);
  69   /**
  70    * Map() maps the <code>ArrayBuffer</code> in to the module's address space
  71    * and returns a pointer to the beginning of the buffer for the given
  72    * <code>ArrayBuffer PP_Var</code>. ArrayBuffers are copied when transmitted,
  73    * so changes to the underlying memory are not automatically available to
  74    * the embedding page.
  75    *
  76    * Note that calling Map() can be a relatively expensive operation. Use care
  77    * when calling it in performance-critical code. For example, you should call
  78    * it only once when looping over an <code>ArrayBuffer</code>.
  79    *
  80    * <strong>Example:</strong>
  81    *
  82    * @code
  83    * char* data = (char*)(array_buffer_if.Map(array_buffer_var));
  84    * uint32_t byte_length = 0;
  85    * PP_Bool ok = array_buffer_if.ByteLength(array_buffer_var, &byte_length);
  86    * if (!ok)
  87    *   return DoSomethingBecauseMyVarIsNotAnArrayBuffer();
  88    * for (uint32_t i = 0; i < byte_length; ++i)
  89    *   data[i] = 'A';
  90    * @endcode
  91    *
  92    * @param[in] array The <code>ArrayBuffer</code> whose internal buffer should
  93    * be returned.
  94    *
  95    * @return A pointer to the internal buffer for this
  96    * <code>ArrayBuffer</code>. Returns <code>NULL</code>
  97    * if the given <code>PP_Var</code> is not of type
  98    * <code>PP_VARTYPE_ARRAY_BUFFER</code>.
  99    */
 100   void* (*Map)(struct PP_Var array);
 101   /**
 102    * Unmap() unmaps the given <code>ArrayBuffer</code> var from the module
 103    * address space. Use this if you want to save memory but might want to call
 104    * Map() to map the buffer again later. The <code>PP_Var</code> remains valid
 105    * and should still be released using <code>PPB_Var</code> when you are done
 106    * with the <code>ArrayBuffer</code>.
 107    *
 108    * @param[in] array The <code>ArrayBuffer</code> to be released.
 109    */
 110   void (*Unmap)(struct PP_Var array);
 111 };
 112
 113 typedef struct PPB_VarArrayBuffer_1_0 PPB_VarArrayBuffer;
 114 /**
 115  * @}
 116  */
 117
 118 #endif  /* PPAPI_C_PPB_VAR_ARRAY_BUFFER_H_ */
 119