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