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