[email protected] | 2272ed3 | 2011-03-30 17:37:54 | [diff] [blame] | 1 | /* Copyright (c) 2011 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 | |
[email protected] | 745b0d4 | 2011-07-16 23:53:22 | [diff] [blame] | 6 | /** |
| 7 | * This file defines the API for handling the passing of data types between |
[email protected] | 2272ed3 | 2011-03-30 17:37:54 | [diff] [blame] | 8 | * your module and the page. |
| 9 | */ |
| 10 | |
[email protected] | 745b0d4 | 2011-07-16 23:53:22 | [diff] [blame] | 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. |
[email protected] | 2272ed3 | 2011-03-30 17:37:54 | [diff] [blame] | 14 | */ |
[email protected] | 745b0d4 | 2011-07-16 23:53:22 | [diff] [blame] | 15 | [assert_size(4)] |
[email protected] | 2272ed3 | 2011-03-30 17:37:54 | [diff] [blame] | 16 | enum PP_VarType { |
[email protected] | 745b0d4 | 2011-07-16 23:53:22 | [diff] [blame] | 17 | /** |
[email protected] | cfe868c | 2011-06-20 18:03:06 | [diff] [blame] | 18 | * An undefined value. |
| 19 | */ |
[email protected] | 745b0d4 | 2011-07-16 23:53:22 | [diff] [blame] | 20 | PP_VARTYPE_UNDEFINED, |
[email protected] | cfe868c | 2011-06-20 18:03:06 | [diff] [blame] | 21 | |
[email protected] | 745b0d4 | 2011-07-16 23:53:22 | [diff] [blame] | 22 | /** |
[email protected] | cfe868c | 2011-06-20 18:03:06 | [diff] [blame] | 23 | * A NULL value. This is similar to undefined, but JavaScript differentiates |
[email protected] | 745b0d4 | 2011-07-16 23:53:22 | [diff] [blame] | 24 | * the two so it is exposed here as well. |
[email protected] | cfe868c | 2011-06-20 18:03:06 | [diff] [blame] | 25 | */ |
[email protected] | 745b0d4 | 2011-07-16 23:53:22 | [diff] [blame] | 26 | PP_VARTYPE_NULL, |
[email protected] | cfe868c | 2011-06-20 18:03:06 | [diff] [blame] | 27 | |
[email protected] | 745b0d4 | 2011-07-16 23:53:22 | [diff] [blame] | 28 | /** |
| 29 | * A boolean value, use the <code>as_bool</code> member of the var. |
[email protected] | cfe868c | 2011-06-20 18:03:06 | [diff] [blame] | 30 | */ |
[email protected] | 745b0d4 | 2011-07-16 23:53:22 | [diff] [blame] | 31 | PP_VARTYPE_BOOL, |
[email protected] | cfe868c | 2011-06-20 18:03:06 | [diff] [blame] | 32 | |
[email protected] | 745b0d4 | 2011-07-16 23:53:22 | [diff] [blame] | 33 | /** |
| 34 | * A 32-bit integer value. Use the <code>as_int</code> member of the var. |
[email protected] | cfe868c | 2011-06-20 18:03:06 | [diff] [blame] | 35 | */ |
[email protected] | 745b0d4 | 2011-07-16 23:53:22 | [diff] [blame] | 36 | PP_VARTYPE_INT32, |
[email protected] | cfe868c | 2011-06-20 18:03:06 | [diff] [blame] | 37 | |
[email protected] | 745b0d4 | 2011-07-16 23:53:22 | [diff] [blame] | 38 | /** |
| 39 | * A double-precision floating point value. Use the <code>as_double</code> |
| 40 | * member of the var. |
[email protected] | cfe868c | 2011-06-20 18:03:06 | [diff] [blame] | 41 | */ |
[email protected] | 745b0d4 | 2011-07-16 23:53:22 | [diff] [blame] | 42 | PP_VARTYPE_DOUBLE, |
[email protected] | cfe868c | 2011-06-20 18:03:06 | [diff] [blame] | 43 | |
[email protected] | 745b0d4 | 2011-07-16 23:53:22 | [diff] [blame] | 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. |
[email protected] | cfe868c | 2011-06-20 18:03:06 | [diff] [blame] | 48 | */ |
[email protected] | 745b0d4 | 2011-07-16 23:53:22 | [diff] [blame] | 49 | PP_VARTYPE_STRING, |
[email protected] | cfe868c | 2011-06-20 18:03:06 | [diff] [blame] | 50 | |
[email protected] | 745b0d4 | 2011-07-16 23:53:22 | [diff] [blame] | 51 | /** |
[email protected] | cfe868c | 2011-06-20 18:03:06 | [diff] [blame] | 52 | * Represents a JavaScript object. This vartype is not currently usable |
[email protected] | 745b0d4 | 2011-07-16 23:53:22 | [diff] [blame] | 53 | * from modules, although it is used internally for some tasks. |
[email protected] | cfe868c | 2011-06-20 18:03:06 | [diff] [blame] | 54 | */ |
[email protected] | 745b0d4 | 2011-07-16 23:53:22 | [diff] [blame] | 55 | PP_VARTYPE_OBJECT, |
[email protected] | cfe868c | 2011-06-20 18:03:06 | [diff] [blame] | 56 | |
[email protected] | 745b0d4 | 2011-07-16 23:53:22 | [diff] [blame] | 57 | /** |
[email protected] | cfe868c | 2011-06-20 18:03:06 | [diff] [blame] | 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 |
[email protected] | 745b0d4 | 2011-07-16 23:53:22 | [diff] [blame] | 61 | * module will continue to work with future versions of the API. |
[email protected] | cfe868c | 2011-06-20 18:03:06 | [diff] [blame] | 62 | */ |
[email protected] | 745b0d4 | 2011-07-16 23:53:22 | [diff] [blame] | 63 | PP_VARTYPE_ARRAY, |
| 64 | PP_VARTYPE_DICTIONARY |
[email protected] | 2272ed3 | 2011-03-30 17:37:54 | [diff] [blame] | 65 | }; |
| 66 | |
[email protected] | cfe868c | 2011-06-20 18:03:06 | [diff] [blame] | 67 | |
[email protected] | 745b0d4 | 2011-07-16 23:53:22 | [diff] [blame] | 68 | /** |
| 69 | * The PP_VarValue union stores the data for any one of the types listed |
| 70 | * in the PP_VarType enum. |
| 71 | */ |
[email protected] | 2272ed3 | 2011-03-30 17:37:54 | [diff] [blame] | 72 | [union] struct PP_VarValue { |
[email protected] | 745b0d4 | 2011-07-16 23:53:22 | [diff] [blame] | 73 | /** |
| 74 | * If <code>type</code> is <code>PP_VARTYPE_BOOL</code>, |
| 75 | * <code>as_bool</code> represents the value of this <code>PP_Var</code> as |
| 76 | * <code>PP_Bool</code>. |
| 77 | */ |
[email protected] | 2272ed3 | 2011-03-30 17:37:54 | [diff] [blame] | 78 | PP_Bool as_bool; |
[email protected] | 745b0d4 | 2011-07-16 23:53:22 | [diff] [blame] | 79 | |
| 80 | /** |
| 81 | * If <code>type</code> is <code>PP_VARTYPE_INT32</code>, |
| 82 | * <code>as_int</code> represents the value of this <code>PP_Var</code> as |
| 83 | * <code>int32_t</code>. |
| 84 | */ |
[email protected] | 2272ed3 | 2011-03-30 17:37:54 | [diff] [blame] | 85 | int32_t as_int; |
[email protected] | 745b0d4 | 2011-07-16 23:53:22 | [diff] [blame] | 86 | |
| 87 | /** |
| 88 | * If <code>type</code> is <code>PP_VARTYPE_DOUBLE</code>, |
| 89 | * <code>as_double</code> represents the value of this <code>PP_Var</code> |
| 90 | * as <code>double</code>. |
| 91 | */ |
[email protected] | 2272ed3 | 2011-03-30 17:37:54 | [diff] [blame] | 92 | double_t as_double; |
[email protected] | 745b0d4 | 2011-07-16 23:53:22 | [diff] [blame] | 93 | |
| 94 | /** |
| 95 | * If <code>type</code> is <code>PP_VARTYPE_STRING</code>, |
| 96 | * <code>PP_VARTYPE_OBJECT</code>, <code>PP_VARTYPE_ARRAY</code>, or |
| 97 | * <code>PP_VARTYPE_DICTIONARY</code>, |
| 98 | * <code>as_id</code> represents the value of this <code>PP_Var</code> as |
| 99 | * an opaque handle assigned by the browser. This handle is guaranteed |
| 100 | * never to be 0, so a module can initialize this ID to 0 to indicate a |
| 101 | * "NULL handle." |
[email protected] | 2272ed3 | 2011-03-30 17:37:54 | [diff] [blame] | 102 | */ |
| 103 | int64_t as_id; |
| 104 | }; |
| 105 | |
[email protected] | 745b0d4 | 2011-07-16 23:53:22 | [diff] [blame] | 106 | /** |
| 107 | * The <code>PP_VAR</code> struct is a variant data type and can contain any |
| 108 | * value of one of the types named in the <code>PP_VarType</code> enum. This |
| 109 | * structure is for passing data between native code which can be strongly |
| 110 | * typed and the browser (JavaScript) which isn't strongly typed. |
[email protected] | 2272ed3 | 2011-03-30 17:37:54 | [diff] [blame] | 111 | * |
| 112 | * JavaScript has a "number" type for holding a number, and does not |
| 113 | * differentiate between floating point and integer numbers. The |
| 114 | * JavaScript operations will try to optimize operations by using |
| 115 | * integers when possible, but could end up with doubles. Therefore, |
[email protected] | 745b0d4 | 2011-07-16 23:53:22 | [diff] [blame] | 116 | * you can't assume a numeric <code>PP_Var</code> will be the type you expect. |
| 117 | * Your code should be capable of handling either int32_t or double for numeric |
| 118 | * PP_Vars sent from JavaScript. |
[email protected] | 2272ed3 | 2011-03-30 17:37:54 | [diff] [blame] | 119 | */ |
[email protected] | 745b0d4 | 2011-07-16 23:53:22 | [diff] [blame] | 120 | [passByValue, returnByValue, assert_size(16)] |
| 121 | struct PP_Var { |
[email protected] | 2272ed3 | 2011-03-30 17:37:54 | [diff] [blame] | 122 | PP_VarType type; |
[email protected] | 745b0d4 | 2011-07-16 23:53:22 | [diff] [blame] | 123 | |
| 124 | /** |
| 125 | * The <code>padding</code> ensures <code>value</code> is aligned on an |
| 126 | * 8-byte boundary relative to the start of the struct. Some compilers |
| 127 | * align doubles on 8-byte boundaries for 32-bit x86, and some align on |
| 128 | * 4-byte boundaries. |
| 129 | */ |
| 130 | int32_t padding; |
| 131 | |
| 132 | /** |
| 133 | * This <code>value</code> represents the contents of the PP_Var. Only one of |
| 134 | * the fields of <code>value</code> is valid at a time based upon |
| 135 | * <code>type</code>. |
| 136 | */ |
[email protected] | 2272ed3 | 2011-03-30 17:37:54 | [diff] [blame] | 137 | PP_VarValue value; |
| 138 | }; |
[email protected] | cfe868c | 2011-06-20 18:03:06 | [diff] [blame] | 139 | |
[email protected] | 745b0d4 | 2011-07-16 23:53:22 | [diff] [blame] | 140 | |
| 141 | #inline c |
| 142 | /** |
| 143 | * @addtogroup Functions |
| 144 | * @{ |
| 145 | */ |
| 146 | |
| 147 | /** |
| 148 | * PP_MakeUndefined() is used to wrap an undefined value into a |
| 149 | * <code>PP_Var</code> struct for passing to the browser. |
| 150 | * |
| 151 | * @return A <code>PP_Var</code> structure. |
| 152 | */ |
| 153 | PP_INLINE struct PP_Var PP_MakeUndefined() { |
| 154 | struct PP_Var result = { PP_VARTYPE_UNDEFINED, 0, {PP_FALSE} }; |
| 155 | return result; |
| 156 | } |
| 157 | |
| 158 | /** |
| 159 | * PP_MakeNull() is used to wrap a null value into a |
| 160 | * <code>PP_Var</code> struct for passing to the browser. |
| 161 | * |
| 162 | * @return A <code>PP_Var</code> structure, |
| 163 | */ |
| 164 | PP_INLINE struct PP_Var PP_MakeNull() { |
| 165 | struct PP_Var result = { PP_VARTYPE_NULL, 0, {PP_FALSE} }; |
| 166 | return result; |
| 167 | } |
| 168 | |
| 169 | /** |
| 170 | * PP_MakeBool() is used to wrap a boolean value into a |
| 171 | * <code>PP_Var</code> struct for passing to the browser. |
| 172 | * |
| 173 | * @param[in] value A <code>PP_Bool</code> enumeration to |
| 174 | * wrap. |
| 175 | * |
| 176 | * @return A <code>PP_Var</code> structure. |
| 177 | */ |
| 178 | PP_INLINE struct PP_Var PP_MakeBool(PP_Bool value) { |
| 179 | struct PP_Var result = { PP_VARTYPE_BOOL, 0, {PP_FALSE} }; |
| 180 | result.value.as_bool = value; |
| 181 | return result; |
| 182 | } |
| 183 | |
| 184 | /** |
| 185 | * PP_MakeInt32() is used to wrap a 32 bit integer value |
| 186 | * into a <code>PP_Var</code> struct for passing to the browser. |
| 187 | * |
| 188 | * @param[in] value An int32 to wrap. |
| 189 | * |
| 190 | * @return A <code>PP_Var</code> structure. |
| 191 | */ |
| 192 | PP_INLINE struct PP_Var PP_MakeInt32(int32_t value) { |
| 193 | struct PP_Var result = { PP_VARTYPE_INT32, 0, {PP_FALSE} }; |
| 194 | result.value.as_int = value; |
| 195 | return result; |
| 196 | } |
| 197 | |
| 198 | /** |
| 199 | * PP_MakeDouble() is used to wrap a double value into a |
| 200 | * <code>PP_Var</code> struct for passing to the browser. |
| 201 | * |
| 202 | * @param[in] value A double to wrap. |
| 203 | * |
| 204 | * @return A <code>PP_Var</code> structure. |
| 205 | */ |
| 206 | PP_INLINE struct PP_Var PP_MakeDouble(double value) { |
| 207 | struct PP_Var result = { PP_VARTYPE_DOUBLE, 0, {PP_FALSE} }; |
| 208 | result.value.as_double = value; |
| 209 | return result; |
| 210 | } |
| 211 | /** |
| 212 | * @} |
| 213 | */ |
| 214 | |
| 215 | #endinl |
| 216 | |