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 */
30typedef 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;
108PP_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 */
121union 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 */
166struct 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};
182PP_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 */
198PP_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 */
209PP_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 */
223PP_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 */
237PP_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 */
251PP_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