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 Mon Feb 11 15:41:10 2013. */
   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.
  57    */
  58   PP_VARTYPE_STRING = 5,
  59   /**
  60    * Represents a JavaScript object. This vartype is not currently usable
  61    * from modules, although it is used internally for some tasks.
  62    */
  63   PP_VARTYPE_OBJECT = 6,
  64   /**
  65    * Arrays and dictionaries are not currently supported but will be added
  66    * in future revisions. These objects are reference counted so be sure
  67    * to properly AddRef/Release them as you would with strings to ensure your
  68    * module will continue to work with future versions of the API.
  69    */
  70   PP_VARTYPE_ARRAY = 7,
  71   PP_VARTYPE_DICTIONARY = 8,
  72   /**
  73    * ArrayBuffer represents a JavaScript ArrayBuffer. This is the type which
  74    * represents Typed Arrays in JavaScript. Unlike JavaScript 'Array', it is
  75    * only meant to contain basic numeric types, and is always stored
  76    * contiguously. See PPB_VarArrayBuffer_Dev for functions special to
  77    * ArrayBuffer vars.
  78    */
  79   PP_VARTYPE_ARRAY_BUFFER = 9
  80 } PP_VarType;
  81 PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_VarType, 4);
  82 /**
  83  * @}
  84  */
  85
  86 /**
  87  * @addtogroup Structs
  88  * @{
  89  */
  90 /**
  91  * The PP_VarValue union stores the data for any one of the types listed
  92  * in the PP_VarType enum.
  93  */
  94 union PP_VarValue {
  95   /**
  96    * If <code>type</code> is <code>PP_VARTYPE_BOOL</code>,
  97    * <code>as_bool</code> represents the value of this <code>PP_Var</code> as
  98    * <code>PP_Bool</code>.
  99    */
 100   PP_Bool as_bool;
 101   /**
 102    * If <code>type</code> is <code>PP_VARTYPE_INT32</code>,
 103    * <code>as_int</code> represents the value of this <code>PP_Var</code> as
 104    * <code>int32_t</code>.
 105    */
 106   int32_t as_int;
 107   /**
 108    * If <code>type</code> is <code>PP_VARTYPE_DOUBLE</code>,
 109    * <code>as_double</code> represents the value of this <code>PP_Var</code>
 110    * as <code>double</code>.
 111    */
 112   double as_double;
 113   /**
 114    * If <code>type</code> is <code>PP_VARTYPE_STRING</code>,
 115    * <code>PP_VARTYPE_OBJECT</code>, <code>PP_VARTYPE_ARRAY</code>, or
 116    * <code>PP_VARTYPE_DICTIONARY</code>,
 117    * <code>as_id</code> represents the value of this <code>PP_Var</code> as
 118    * an opaque handle assigned by the browser. This handle is guaranteed
 119    * never to be 0, so a module can initialize this ID to 0 to indicate a
 120    * "NULL handle."
 121    */
 122   int64_t as_id;
 123 };
 124
 125 /**
 126  * The <code>PP_VAR</code> struct is a variant data type and can contain any
 127  * value of one of the types named in the <code>PP_VarType</code> enum. This
 128  * structure is for passing data between native code which can be strongly
 129  * typed and the browser (JavaScript) which isn't strongly typed.
 130  *
 131  * JavaScript has a "number" type for holding a number, and does not
 132  * differentiate between floating point and integer numbers. The
 133  * JavaScript operations will try to optimize operations by using
 134  * integers when possible, but could end up with doubles. Therefore,
 135  * you can't assume a numeric <code>PP_Var</code> will be the type you expect.
 136  * Your code should be capable of handling either int32_t or double for numeric
 137  * PP_Vars sent from JavaScript.
 138  */
 139 struct PP_Var {
 140   PP_VarType type;
 141   /**
 142    * The <code>padding</code> ensures <code>value</code> is aligned on an
 143    * 8-byte boundary relative to the start of the struct. Some compilers
 144    * align doubles on 8-byte boundaries for 32-bit x86, and some align on
 145    * 4-byte boundaries.
 146    */
 147   int32_t padding;
 148   /**
 149    * This <code>value</code> represents the contents of the PP_Var. Only one of
 150    * the fields of <code>value</code> is valid at a time based upon
 151    * <code>type</code>.
 152    */
 153   union PP_VarValue value;
 154 };
 155 PP_COMPILE_ASSERT_STRUCT_SIZE_IN_BYTES(PP_Var, 16);
 156 /**
 157  * @}
 158  */
 159
 160 /**
 161  * @addtogroup Functions
 162  * @{
 163  */
 164
 165 /**
 166  * PP_MakeUndefined() is used to wrap an undefined value into a
 167  * <code>PP_Var</code> struct for passing to the browser.
 168  *
 169  * @return A <code>PP_Var</code> structure.
 170  */
 171 PP_INLINE struct PP_Var PP_MakeUndefined(void) {
 172   struct PP_Var result = { PP_VARTYPE_UNDEFINED, 0, {PP_FALSE} };
 173   return result;
 174 }
 175
 176 /**
 177  * PP_MakeNull() is used to wrap a null value into a
 178  * <code>PP_Var</code> struct for passing to the browser.
 179  *
 180  * @return A <code>PP_Var</code> structure,
 181  */
 182 PP_INLINE struct PP_Var PP_MakeNull(void) {
 183   struct PP_Var result = { PP_VARTYPE_NULL, 0, {PP_FALSE} };
 184   return result;
 185 }
 186
 187 /**
 188  * PP_MakeBool() is used to wrap a boolean value into a
 189  * <code>PP_Var</code> struct for passing to the browser.
 190  *
 191  * @param[in] value A <code>PP_Bool</code> enumeration to
 192  * wrap.
 193  *
 194  * @return A <code>PP_Var</code> structure.
 195  */
 196 PP_INLINE struct PP_Var PP_MakeBool(PP_Bool value) {
 197   struct PP_Var result = { PP_VARTYPE_BOOL, 0, {PP_FALSE} };
 198   result.value.as_bool = value;
 199   return result;
 200 }
 201
 202 /**
 203  * PP_MakeInt32() is used to wrap a 32 bit integer value
 204  * into a <code>PP_Var</code> struct for passing to the browser.
 205  *
 206  * @param[in] value An int32 to wrap.
 207  *
 208  * @return A <code>PP_Var</code> structure.
 209  */
 210 PP_INLINE struct PP_Var PP_MakeInt32(int32_t value) {
 211   struct PP_Var result = { PP_VARTYPE_INT32, 0, {PP_FALSE} };
 212   result.value.as_int = value;
 213   return result;
 214 }
 215
 216 /**
 217  * PP_MakeDouble() is used to wrap a double value into a
 218  * <code>PP_Var</code> struct for passing to the browser.
 219  *
 220  * @param[in] value A double to wrap.
 221  *
 222  * @return A <code>PP_Var</code> structure.
 223  */
 224 PP_INLINE struct PP_Var PP_MakeDouble(double value) {
 225   struct PP_Var result = { PP_VARTYPE_DOUBLE, 0, {PP_FALSE} };
 226   result.value.as_double = value;
 227   return result;
 228 }
 229 /**
 230  * @}
 231  */
 232
 233 #endif  /* PPAPI_C_PP_VAR_H_ */
 234