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 */
PP_MakeUndefined(void)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 */
PP_MakeNull(void)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 */
PP_MakeBool(PP_Bool value)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 */
PP_MakeInt32(int32_t value)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 */
PP_MakeDouble(double value)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