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 #ifndef PPAPI_CPP_VAR_H_ 6 #define PPAPI_CPP_VAR_H_ 7 8 #include <string> 9 #include <vector> 10 11 #include "ppapi/c/pp_var.h" 12 #include "ppapi/cpp/pass_ref.h" 13 14 /// @file 15 /// This file defines the API for handling the passing of data types between 16 /// your module and the page. 17 namespace pp { 18 19 /// A generic type used for passing data types between the module and the page. 20 class Var { 21 public: 22 /// Special value passed to constructor to make <code>NULL</code>. 23 struct Null {}; 24 25 /// Default constructor. Creates a <code>Var</code> of type 26 /// <code>Undefined</code>. 27 Var(); 28 29 /// A constructor used to create a <code>Var</code> of type <code>Null</code>. 30 Var(Null); 31 32 /// A constructor used to create a <code>Var</code> of type <code>Bool</code>. 33 /// 34 /// @param[in] b A boolean value. 35 Var(bool b); 36 37 /// A constructor used to create a 32 bit integer <code>Var</code>. 38 /// 39 /// @param[in] i A 32 bit integer value. 40 Var(int32_t i); 41 42 /// A constructor used to create a double value <code>Var</code>. 43 /// 44 /// @param[in] d A double value. 45 Var(double d); 46 47 /// A constructor used to create a UTF-8 character <code>Var</code>. 48 Var(const char* utf8_str); // Must be encoded in UTF-8. 49 50 /// A constructor used to create a UTF-8 character <code>Var</code>. 51 Var(const std::string& utf8_str); // Must be encoded in UTF-8. 52 53 /// A constructor used when you have received a <code>Var</code> as a return 54 /// value that has had its reference count incremented for you. 55 /// 56 /// You will not normally need to use this constructor because 57 /// the reference count will not normally be incremented for you. 58 Var(PassRef, const PP_Var& var) { 59 var_ = var; 60 is_managed_ = true; 61 } 62 63 /// A constructor that increments the reference count. 64 explicit Var(const PP_Var& var); 65 66 struct DontManage {}; 67 68 // TODO(brettw): remove DontManage when this bug is fixed 69 // http://code.google.com/p/chromium/issues/detail?id=52105 70 /// This constructor is used when we've given a <code>PP_Var</code> as an 71 /// input argument from somewhere and that reference is managing the 72 /// reference count for us. The object will not have its reference count 73 /// increased or decreased by this class instance. 74 /// 75 /// @param[in] var A <code>Var</code>. 76 Var(DontManage, const PP_Var& var) { 77 var_ = var; 78 is_managed_ = false; 79 } 80 81 /// A constructor for copying a <code>Var</code>. 82 Var(const Var& other); 83 84 /// Destructor. 85 virtual ~Var(); 86 87 /// This function assigns one <code>Var</code> to another <code>Var</code>. 88 /// 89 /// @param[in] other The <code>Var</code> to be assigned. 90 /// 91 /// @return A resulting <code>Var</code>. 92 virtual Var& operator=(const Var& other); 93 94 /// This function compares object identity (rather than value identity) for 95 /// objects, dictionaries, and arrays 96 /// 97 /// @param[in] other The <code>Var</code> to be compared to this Var. 98 /// 99 /// @return true if the <code>other</code> <code>Var</code> is the same as 100 /// this <code>Var</code>, otherwise false. 101 bool operator==(const Var& other) const; 102 103 /// This function determines if this <code>Var</code> is an undefined value. 104 /// 105 /// @return true if this <code>Var</code> is undefined, otherwise false. 106 bool is_undefined() const { return var_.type == PP_VARTYPE_UNDEFINED; } 107 108 /// This function determines if this <code>Var</code> is a null value. 109 /// 110 /// @return true if this <code>Var</code> is null, otherwise false. 111 bool is_null() const { return var_.type == PP_VARTYPE_NULL; } 112 113 /// This function determines if this <code>Var</code> is a bool value. 114 /// 115 /// @return true if this <code>Var</code> is a bool, otherwise false. 116 bool is_bool() const { return var_.type == PP_VARTYPE_BOOL; } 117 118 /// This function determines if this <code>Var</code> is a string value. 119 /// 120 /// @return true if this <code>Var</code> is a string, otherwise false. 121 bool is_string() const { return var_.type == PP_VARTYPE_STRING; } 122 123 /// This function determines if this <code>Var</code> is an object. 124 /// 125 /// @return true if this <code>Var</code> is an object, otherwise false. 126 bool is_object() const { return var_.type == PP_VARTYPE_OBJECT; } 127 128 /// This function determines if this <code>Var</code> is an array. 129 /// 130 /// @return true if this <code>Var</code> is an array, otherwise false. 131 bool is_array() const { return var_.type == PP_VARTYPE_ARRAY; } 132 133 /// This function determines if this <code>Var</code> is a dictionary. 134 /// 135 /// @return true if this <code>Var</code> is a dictionary, otherwise false. 136 bool is_dictionary() const { return var_.type == PP_VARTYPE_DICTIONARY; } 137 138 /// This function determines if this <code>Var</code> is an integer value. 139 /// The <code>is_int</code> function returns the internal representation. 140 /// The JavaScript runtime may convert between the two as needed, so the 141 /// distinction may not be relevant in all cases (int is really an 142 /// optimization inside the runtime). So most of the time, you will want 143 /// to check is_number(). 144 /// 145 /// @return true if this <code>Var</code> is an integer, otherwise false. 146 bool is_int() const { return var_.type == PP_VARTYPE_INT32; } 147 148 /// This function determines if this <code>Var</code> is a double value. 149 /// The <code>is_double</code> function returns the internal representation. 150 /// The JavaScript runtime may convert between the two as needed, so the 151 /// distinction may not be relevant in all cases (int is really an 152 /// optimization inside the runtime). So most of the time, you will want to 153 /// check is_number(). 154 /// 155 /// @return true if this <code>Var</code> is a double, otherwise false. 156 bool is_double() const { return var_.type == PP_VARTYPE_DOUBLE; } 157 158 /// This function determines if this <code>Var</code> is a number. 159 /// 160 /// @return true if this <code>Var</code> is an int32 or double number, 161 /// otherwise false. 162 bool is_number() const { 163 return var_.type == PP_VARTYPE_INT32 || 164 var_.type == PP_VARTYPE_DOUBLE; 165 } 166 167 /// This function determines if this <code>Var</code> is an ArrayBuffer. 168 bool is_array_buffer() const { return var_.type == PP_VARTYPE_ARRAY_BUFFER; } 169 170 /// AsBool() converts this <code>Var</code> to a bool. Assumes the 171 /// internal representation is_bool(). If it's not, it will assert in debug 172 /// mode, and return false. 173 /// 174 /// @return A bool version of this <code>Var</code>. 175 bool AsBool() const; 176 177 /// AsInt() converts this <code>Var</code> to an int32_t. This function 178 /// is required because JavaScript doesn't have a concept of ints and doubles, 179 /// only numbers. The distinction between the two is an optimization inside 180 /// the compiler. Since converting from a double to an int may be lossy, if 181 /// you care about the distinction, either always work in doubles, or check 182 /// !is_double() before calling AsInt(). 183 /// 184 /// These functions will assert in debug mode and return 0 if the internal 185 /// representation is not is_number(). 186 /// 187 /// @return An int32_t version of this <code>Var</code>. 188 int32_t AsInt() const; 189 190 /// AsDouble() converts this <code>Var</code> to a double. This function is 191 /// necessary because JavaScript doesn't have a concept of ints and doubles, 192 /// only numbers. The distinction between the two is an optimization inside 193 /// the compiler. Since converting from a double to an int may be lossy, if 194 /// you care about the distinction, either always work in doubles, or check 195 /// !is_double() before calling AsInt(). 196 /// 197 /// These functions will assert in debug mode and return 0 if the internal 198 /// representation is not is_number(). 199 /// 200 /// @return An double version of this <code>Var</code>. 201 double AsDouble() const; 202 203 /// AsString() converts this <code>Var</code> to a string. If this object is 204 /// not a string, it will assert in debug mode, and return an empty string. 205 /// 206 /// @return A string version of this <code>Var</code>. 207 std::string AsString() const; 208 209 /// This function returns the internal <code>PP_Var</code> 210 /// managed by this <code>Var</code> object. 211 /// 212 /// @return A const reference to a <code>PP_Var</code>. 213 const PP_Var& pp_var() const { 214 return var_; 215 } 216 217 /// Detach() detaches from the internal <code>PP_Var</code> of this 218 /// object, keeping the reference count the same. This is used when returning 219 /// a <code>PP_Var</code> from an API function where the caller expects the 220 /// return value to have the reference count incremented for it. 221 /// 222 /// @return A detached version of this object without affecting the reference 223 /// count. 224 PP_Var Detach() { 225 PP_Var ret = var_; 226 var_ = PP_MakeUndefined(); 227 is_managed_ = true; 228 return ret; 229 } 230 231 /// DebugString() returns a short description "Var<X>" that can be used for 232 /// logging, where "X" is the underlying scalar or "UNDEFINED" or "OBJ" as 233 /// it does not call into the browser to get the object description. 234 /// 235 /// @return A string displaying the value of this <code>Var</code>. This 236 /// function is used for debugging. 237 std::string DebugString() const; 238 239 /// This class is used when calling the raw C PPAPI when using the C++ 240 /// <code>Var</code> as a possible NULL exception. This class will handle 241 /// getting the address of the internal value out if it's non-NULL and 242 /// fixing up the reference count. 243 /// 244 /// <strong>Warning:</strong> this will only work for things with exception 245 /// semantics, i.e. that the value will not be changed if it's a 246 /// non-undefined exception. Otherwise, this class will mess up the 247 /// refcounting. 248 /// 249 /// This is a bit subtle: 250 /// - If NULL is passed, we return NULL from get() and do nothing. 251 /// 252 /// - If a undefined value is passed, we return the address of a undefined 253 /// var from get and have the output value take ownership of that var. 254 /// 255 /// - If a non-undefined value is passed, we return the address of that var 256 /// from get, and nothing else should change. 257 /// 258 /// Example: 259 /// void FooBar(a, b, Var* exception = NULL) { 260 /// foo_interface->Bar(a, b, Var::OutException(exception).get()); 261 /// } 262 class OutException { 263 public: 264 /// A constructor. 265 OutException(Var* v) 266 : output_(v), 267 originally_had_exception_(v && !v->is_undefined()) { 268 if (output_) { 269 temp_ = output_->var_; 270 } else { 271 temp_.padding = 0; 272 temp_.type = PP_VARTYPE_UNDEFINED; 273 } 274 } 275 276 /// Destructor. 277 ~OutException() { 278 if (output_ && !originally_had_exception_) 279 *output_ = Var(PASS_REF, temp_); 280 } 281 282 PP_Var* get() { 283 if (output_) 284 return &temp_; 285 return NULL; 286 } 287 288 private: 289 Var* output_; 290 bool originally_had_exception_; 291 PP_Var temp_; 292 }; 293 294 protected: 295 PP_Var var_; 296 297 // |is_managed_| indicates if the instance manages |var_|. 298 // You need to check if |var_| is refcounted to call Release(). 299 bool is_managed_; 300 301 private: 302 // Prevent an arbitrary pointer argument from being implicitly converted to 303 // a bool at Var construction. If somebody makes such a mistake, (s)he will 304 // get a compilation error. 305 Var(void* non_scriptable_object_pointer); 306 }; 307 308 } // namespace pp 309 310 #endif // PPAPI_CPP_VAR_H_ 311
