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 235
