ppapi/c/pp_var.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 pp_var.idl modified Thu Apr 10 14:52:30 2014. */
   7
   8 #ifndef PPAPI_C_PP_VAR_H_
   9 #define PPAPI_C_PP_VAR_H_
  10
  11 #include "ppapi/c/pp_bool.h"
  12 #include "ppapi/c/pp_macros.h"
  13 #include "ppapi/c/pp_stdint.h"
  14
  15 /**
  16  * @file
  17  * This file defines the API for handling the passing of data types between
  18  * your module and the page.
  19  */
  20
  21
  22 /**
  23  * @addtogroup Enums
  24  * @{
  25  */
  26 /**
  27  * The <code>PP_VarType</code> is an enumeration of the different types that
  28  * can be contained within a <code>PP_Var</code> structure.
  29  */
  30 typedef enum {
  31   /**
  32    * An undefined value.
  33    */
  34   PP_VARTYPE_UNDEFINED = 0,
  35   /**
  36    * A NULL value. This is similar to undefined, but JavaScript differentiates
  37    * the two so it is exposed here as well.
  38    */
  39   PP_VARTYPE_NULL = 1,
  40   /**
  41    * A boolean value, use the <code>as_bool</code> member of the var.
  42    */
  43   PP_VARTYPE_BOOL = 2,
  44   /**
  45    * A 32-bit integer value. Use the <code>as_int</code> member of the var.
  46    */
  47   PP_VARTYPE_INT32 = 3,
  48   /**
  49    * A double-precision floating point value. Use the <code>as_double</code>
  50    * member of the var.
  51    */
  52   PP_VARTYPE_DOUBLE = 4,
  53   /**
  54    * The Var represents a string. The <code>as_id</code> field is used to
  55    * identify the string, which may be created and retrieved from the
  56    * <code>PPB_Var</code> interface. These objects are reference counted, so
  57    * AddRef() and Release() must be used properly to avoid memory leaks.
  58    */
  59   PP_VARTYPE_STRING = 5,
  60   /**
  61    * Represents a JavaScript object. This vartype is not currently usable
  62    * from modules, although it is used internally for some tasks. These objects
  63    * are reference counted, so AddRef() and Release() must be used properly to
  64    * avoid memory leaks.
  65    */
  66   PP_VARTYPE_OBJECT = 6,
  67   /**
  68    * Represents an array of Vars. The <code>as_id</code> field is used to
  69    * identify the array, which may be created and manipulated from the
  70    * <code>PPB_VarArray</code> interface. These objects are reference counted,
  71    * so AddRef() and Release() must be used properly to avoid memory leaks.
  72    */
  73   PP_VARTYPE_ARRAY = 7,
  74   /**
  75    * Represents a mapping from strings to Vars. The <code>as_id</code> field is
  76    * used to identify the dictionary, which may be created and manipulated from
  77    * the <code>PPB_VarDictionary</code> interface. These objects are reference
  78    * counted, so AddRef() and Release() must be used properly to avoid memory
  79    * leaks.
  80    */
  81   PP_VARTYPE_DICTIONARY = 8,
  82   /**
  83    * ArrayBuffer represents a JavaScript ArrayBuffer. This is the type which
  84    * represents Typed Arrays in JavaScript. Unlike JavaScript 'Array', it is
  85    * only meant to contain basic numeric types, and is always stored
  86    * contiguously. See PPB_VarArrayBuffer_Dev for functions special to
  87    * ArrayBuffer vars. These objects are reference counted, so AddRef() and
  88    * Release() must be used properly to avoid memory leaks.
  89    */
  90   PP_VARTYPE_ARRAY_BUFFER = 9,
  91   /**
  92    * This type allows the <code>PP_Var</code> to wrap a <code>PP_Resource
  93    * </code>. This can be useful for sending or receiving some types of
  94    * <code>PP_Resource</code> using <code>PPB_Messaging</code> or
  95    * <code>PPP_Messaging</code>.
  96    *
  97    * These objects are reference counted, so AddRef() and Release() must be used
  98    * properly to avoid memory leaks. Under normal circumstances, the
  99    * <code>PP_Var</code> will implicitly hold a reference count on the
 100    * <code>PP_Resource</code> on your behalf. For example, if you call
 101    * VarFromResource(), it implicitly calls PPB_Core::AddRefResource() on the
 102    * <code>PP_Resource</code>. Likewise, PPB_Var::Release() on a Resource
 103    * <code>PP_Var</code> will invoke PPB_Core::ReleaseResource() when the Var
 104    * reference count goes to zero.
 105    */
 106   PP_VARTYPE_RESOURCE = 10
 107 } PP_VarType;
 108 PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_VarType, 4);
 109 /**
 110  * @}
 111  */
 112
 113 /**
 114  * @addtogroup Structs
 115  * @{
 116  */
 117 /**
 118  * The PP_VarValue union stores the data for any one of the types listed
 119  * in the PP_VarType enum.
 120  */
 121 union PP_VarValue {
 122   /**
 123    * If <code>type</code> is <code>PP_VARTYPE_BOOL</code>,
 124    * <code>as_bool</code> represents the value of this <code>PP_Var</code> as
 125    * <code>PP_Bool</code>.
 126    */
 127   PP_Bool as_bool;
 128   /**
 129    * If <code>type</code> is <code>PP_VARTYPE_INT32</code>,
 130    * <code>as_int</code> represents the value of this <code>PP_Var</code> as
 131    * <code>int32_t</code>.
 132    */
 133   int32_t as_int;
 134   /**
 135    * If <code>type</code> is <code>PP_VARTYPE_DOUBLE</code>,
 136    * <code>as_double</code> represents the value of this <code>PP_Var</code>
 137    * as <code>double</code>.
 138    */
 139   double as_double;
 140   /**
 141    * If <code>type</code> is <code>PP_VARTYPE_STRING</code>,
 142    * <code>PP_VARTYPE_OBJECT</code>, <code>PP_VARTYPE_ARRAY</code>,
 143    * <code>PP_VARTYPE_DICTIONARY</code>, <code>PP_VARTYPE_ARRAY_BUFFER</code>,
 144    * or <code>PP_VARTYPE_RESOURCE</code>, <code>as_id</code> represents the
 145    * value of this <code>PP_Var</code> as an opaque handle assigned by the
 146    * browser. This handle is guaranteed never to be 0, so a module can
 147    * initialize this ID to 0 to indicate a "NULL handle."
 148    */
 149   int64_t as_id;
 150 };
 151
 152 /**
 153  * The <code>PP_VAR</code> struct is a variant data type and can contain any
 154  * value of one of the types named in the <code>PP_VarType</code> enum. This
 155  * structure is for passing data between native code which can be strongly
 156  * typed and the browser (JavaScript) which isn't strongly typed.
 157  *
 158  * JavaScript has a "number" type for holding a number, and does not
 159  * differentiate between floating point and integer numbers. The
 160  * JavaScript operations will try to optimize operations by using
 161  * integers when possible, but could end up with doubles. Therefore,
 162  * you can't assume a numeric <code>PP_Var</code> will be the type you expect.
 163  * Your code should be capable of handling either int32_t or double for numeric
 164  * PP_Vars sent from JavaScript.
 165  */
 166 struct PP_Var {
 167   PP_VarType type;
 168   /**
 169    * The <code>padding</code> ensures <code>value</code> is aligned on an
 170    * 8-byte boundary relative to the start of the struct. Some compilers
 171    * align doubles on 8-byte boundaries for 32-bit x86, and some align on
 172    * 4-byte boundaries.
 173    */
 174   int32_t padding;
 175   /**
 176    * This <code>value</code> represents the contents of the PP_Var. Only one of
 177    * the fields of <code>value</code> is valid at a time based upon
 178    * <code>type</code>.
 179    */
 180   union PP_VarValue value;
 181 };
 182 PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_Var, 16);
 183 /**
 184  * @}
 185  */
 186
 187 /**
 188  * @addtogroup Functions
 189  * @{
 190  */
 191
 192 /**
 193  * PP_MakeUndefined() is used to wrap an undefined value into a
 194  * <code>PP_Var</code> struct for passing to the browser.
 195  *
 196  * @return A <code>PP_Var</code> structure.
 197  */
 198 PP_INLINE struct PP_Var PP_MakeUndefined(void) {
 199   struct PP_Var result = { PP_VARTYPE_UNDEFINED, 0, {PP_FALSE} };
 200   return result;
 201 }
 202
 203 /**
 204  * PP_MakeNull() is used to wrap a null value into a
 205  * <code>PP_Var</code> struct for passing to the browser.
 206  *
 207  * @return A <code>PP_Var</code> structure,
 208  */
 209 PP_INLINE struct PP_Var PP_MakeNull(void) {
 210   struct PP_Var result = { PP_VARTYPE_NULL, 0, {PP_FALSE} };
 211   return result;
 212 }
 213
 214 /**
 215  * PP_MakeBool() is used to wrap a boolean value into a
 216  * <code>PP_Var</code> struct for passing to the browser.
 217  *
 218  * @param[in] value A <code>PP_Bool</code> enumeration to
 219  * wrap.
 220  *
 221  * @return A <code>PP_Var</code> structure.
 222  */
 223 PP_INLINE struct PP_Var PP_MakeBool(PP_Bool value) {
 224   struct PP_Var result = { PP_VARTYPE_BOOL, 0, {PP_FALSE} };
 225   result.value.as_bool = value;
 226   return result;
 227 }
 228
 229 /**
 230  * PP_MakeInt32() is used to wrap a 32 bit integer value
 231  * into a <code>PP_Var</code> struct for passing to the browser.
 232  *
 233  * @param[in] value An int32 to wrap.
 234  *
 235  * @return A <code>PP_Var</code> structure.
 236  */
 237 PP_INLINE struct PP_Var PP_MakeInt32(int32_t value) {
 238   struct PP_Var result = { PP_VARTYPE_INT32, 0, {PP_FALSE} };
 239   result.value.as_int = value;
 240   return result;
 241 }
 242
 243 /**
 244  * PP_MakeDouble() is used to wrap a double value into a
 245  * <code>PP_Var</code> struct for passing to the browser.
 246  *
 247  * @param[in] value A double to wrap.
 248  *
 249  * @return A <code>PP_Var</code> structure.
 250  */
 251 PP_INLINE struct PP_Var PP_MakeDouble(double value) {
 252   struct PP_Var result = { PP_VARTYPE_DOUBLE, 0, {PP_FALSE} };
 253   result.value.as_double = value;
 254   return result;
 255 }
 256 /**
 257  * @}
 258  */
 259
 260 #endif  /* PPAPI_C_PP_VAR_H_ */
 261