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 262
