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)] 16enum 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)] 159struct 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 */ 191PP_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 */ 202PP_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 */ 216PP_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 */ 230PP_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 */ 244PP_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 255