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 avoid
56   * 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 leaks.
73   */
74  PP_VARTYPE_DICTIONARY = 8,
75
76  /**
77   * ArrayBuffer represents a JavaScript ArrayBuffer. This is the type which
78   * represents Typed Arrays in JavaScript. Unlike JavaScript 'Array', it is
79   * only meant to contain basic numeric types, and is always stored
80   * contiguously. See PPB_VarArrayBuffer_Dev for functions special to
81   * ArrayBuffer vars. These objects are reference counted, so AddRef and
82   * Release must be used properly to avoid memory leaks.
83   */
84  PP_VARTYPE_ARRAY_BUFFER = 9,
85
86  /**
87   * Resources are not currently supported but will be added in the future
88   * These objects are reference counted, so AddRef and Release must be used
89   * properly to avoid memory leaks.
90   */
91  PP_VARTYPE_RESOURCE = 10
92};
93
94
95/**
96 * The PP_VarValue union stores the data for any one of the types listed
97 * in the PP_VarType enum.
98 */
99[union] struct PP_VarValue {
100  /**
101   * If <code>type</code> is <code>PP_VARTYPE_BOOL</code>,
102   * <code>as_bool</code> represents the value of this <code>PP_Var</code> as
103   * <code>PP_Bool</code>.
104   */
105  PP_Bool as_bool;
106
107  /**
108   * If <code>type</code> is <code>PP_VARTYPE_INT32</code>,
109   * <code>as_int</code> represents the value of this <code>PP_Var</code> as
110   * <code>int32_t</code>.
111   */
112  int32_t as_int;
113
114  /**
115   * If <code>type</code> is <code>PP_VARTYPE_DOUBLE</code>,
116   * <code>as_double</code> represents the value of this <code>PP_Var</code>
117   * as <code>double</code>.
118   */
119  double_t as_double;
120
121  /**
122   * If <code>type</code> is <code>PP_VARTYPE_STRING</code>,
123   * <code>PP_VARTYPE_OBJECT</code>, <code>PP_VARTYPE_ARRAY</code>,
124   * <code>PP_VARTYPE_DICTIONARY</code>, <code>PP_VARTYPE_ARRAY_BUFFER</code>,
125   * or <code>PP_VARTYPE_RESOURCE</code>, <code>as_id</code> represents the
126   * value of this <code>PP_Var</code> as an opaque handle assigned by the
127   * browser. This handle is guaranteed never to be 0, so a module can
128   * initialize this ID to 0 to indicate a "NULL handle."
129   */
130  int64_t as_id;
131};
132
133/**
134 * The <code>PP_VAR</code> struct is a variant data type and can contain any
135 * value of one of the types named in the <code>PP_VarType</code> enum. This
136 * structure is for passing data between native code which can be strongly
137 * typed and the browser (JavaScript) which isn't strongly typed.
138 *
139 * JavaScript has a "number" type for holding a number, and does not
140 * differentiate between floating point and integer numbers. The
141 * JavaScript operations will try to optimize operations by using
142 * integers when possible, but could end up with doubles. Therefore,
143 * you can't assume a numeric <code>PP_Var</code> will be the type you expect.
144 * Your code should be capable of handling either int32_t or double for numeric
145 * PP_Vars sent from JavaScript.
146 */
147[passByValue, returnByValue, assert_size(16)]
148struct PP_Var {
149  PP_VarType type;
150
151  /**
152   * The <code>padding</code> ensures <code>value</code> is aligned on an
153   * 8-byte boundary relative to the start of the struct. Some compilers
154   * align doubles on 8-byte boundaries for 32-bit x86, and some align on
155   * 4-byte boundaries.
156   */
157  int32_t padding;
158
159  /**
160   * This <code>value</code> represents the contents of the PP_Var. Only one of
161   * the fields of <code>value</code> is valid at a time based upon
162   * <code>type</code>.
163   */
164  PP_VarValue value;
165};
166
167
168#inline c
169/**
170 * @addtogroup Functions
171 * @{
172 */
173
174/**
175 * PP_MakeUndefined() is used to wrap an undefined value into a
176 * <code>PP_Var</code> struct for passing to the browser.
177 *
178 * @return A <code>PP_Var</code> structure.
179 */
180PP_INLINE struct PP_Var PP_MakeUndefined(void) {
181  struct PP_Var result = { PP_VARTYPE_UNDEFINED, 0, {PP_FALSE} };
182  return result;
183}
184
185/**
186 * PP_MakeNull() is used to wrap a null 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_MakeNull(void) {
192  struct PP_Var result = { PP_VARTYPE_NULL, 0, {PP_FALSE} };
193  return result;
194}
195
196/**
197 * PP_MakeBool() is used to wrap a boolean value into a
198 * <code>PP_Var</code> struct for passing to the browser.
199 *
200 * @param[in] value A <code>PP_Bool</code> enumeration to
201 * wrap.
202 *
203 * @return A <code>PP_Var</code> structure.
204 */
205PP_INLINE struct PP_Var PP_MakeBool(PP_Bool value) {
206  struct PP_Var result = { PP_VARTYPE_BOOL, 0, {PP_FALSE} };
207  result.value.as_bool = value;
208  return result;
209}
210
211/**
212 * PP_MakeInt32() is used to wrap a 32 bit integer value
213 * into a <code>PP_Var</code> struct for passing to the browser.
214 *
215 * @param[in] value An int32 to wrap.
216 *
217 * @return A <code>PP_Var</code> structure.
218 */
219PP_INLINE struct PP_Var PP_MakeInt32(int32_t value) {
220  struct PP_Var result = { PP_VARTYPE_INT32, 0, {PP_FALSE} };
221  result.value.as_int = value;
222  return result;
223}
224
225/**
226 * PP_MakeDouble() is used to wrap a double value into a
227 * <code>PP_Var</code> struct for passing to the browser.
228 *
229 * @param[in] value A double to wrap.
230 *
231 * @return A <code>PP_Var</code> structure.
232 */
233PP_INLINE struct PP_Var PP_MakeDouble(double value) {
234  struct PP_Var result = { PP_VARTYPE_DOUBLE, 0, {PP_FALSE} };
235  result.value.as_double = value;
236  return result;
237}
238/**
239 * @}
240 */
241
242#endinl
243
244