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