Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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 | |
Ben Murdoch | a02191e | 2014-04-16 11:17:03 +0100 | [diff] [blame] | 6 | /* From pp_var.idl modified Thu Apr 10 14:52:30 2014. */ |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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 |
Torne (Richard Coles) | 58537e2 | 2013-09-12 12:10:22 +0100 | [diff] [blame] | 56 | * <code>PPB_Var</code> interface. These objects are reference counted, so |
Ben Murdoch | a02191e | 2014-04-16 11:17:03 +0100 | [diff] [blame] | 57 | * AddRef() and Release() must be used properly to avoid memory leaks. |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 58 | */ |
| 59 | PP_VARTYPE_STRING = 5, |
| 60 | /** |
| 61 | * Represents a JavaScript object. This vartype is not currently usable |
Torne (Richard Coles) | 58537e2 | 2013-09-12 12:10:22 +0100 | [diff] [blame] | 62 | * from modules, although it is used internally for some tasks. These objects |
Ben Murdoch | a02191e | 2014-04-16 11:17:03 +0100 | [diff] [blame] | 63 | * are reference counted, so AddRef() and Release() must be used properly to |
| 64 | * avoid memory leaks. |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 65 | */ |
| 66 | PP_VARTYPE_OBJECT = 6, |
| 67 | /** |
Torne (Richard Coles) | 58537e2 | 2013-09-12 12:10:22 +0100 | [diff] [blame] | 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, |
Ben Murdoch | a02191e | 2014-04-16 11:17:03 +0100 | [diff] [blame] | 71 | * so AddRef() and Release() must be used properly to avoid memory leaks. |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 72 | */ |
| 73 | PP_VARTYPE_ARRAY = 7, |
Torne (Richard Coles) | 58537e2 | 2013-09-12 12:10:22 +0100 | [diff] [blame] | 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 |
Ben Murdoch | a02191e | 2014-04-16 11:17:03 +0100 | [diff] [blame] | 78 | * counted, so AddRef() and Release() must be used properly to avoid memory |
| 79 | * leaks. |
Torne (Richard Coles) | 58537e2 | 2013-09-12 12:10:22 +0100 | [diff] [blame] | 80 | */ |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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 |
Ben Murdoch | a02191e | 2014-04-16 11:17:03 +0100 | [diff] [blame] | 87 | * ArrayBuffer vars. These objects are reference counted, so AddRef() and |
| 88 | * Release() must be used properly to avoid memory leaks. |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 89 | */ |
Torne (Richard Coles) | d0247b1 | 2013-09-19 22:36:51 +0100 | [diff] [blame] | 90 | PP_VARTYPE_ARRAY_BUFFER = 9, |
| 91 | /** |
Ben Murdoch | a02191e | 2014-04-16 11:17:03 +0100 | [diff] [blame] | 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. |
Torne (Richard Coles) | d0247b1 | 2013-09-19 22:36:51 +0100 | [diff] [blame] | 105 | */ |
| 106 | PP_VARTYPE_RESOURCE = 10 |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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>, |
Torne (Richard Coles) | d0247b1 | 2013-09-19 22:36:51 +0100 | [diff] [blame] | 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." |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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 | */ |
Torne (Richard Coles) | 2a99a7e | 2013-03-28 15:31:22 +0000 | [diff] [blame] | 198 | PP_INLINE struct PP_Var PP_MakeUndefined(void) { |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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 | */ |
Torne (Richard Coles) | 2a99a7e | 2013-03-28 15:31:22 +0000 | [diff] [blame] | 209 | PP_INLINE struct PP_Var PP_MakeNull(void) { |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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 | |