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 /* 6 This file contains the declaration for CppVariant, a type used by C++ classes 7 that are to be bound to JavaScript objects. 8 9 CppVariant exists primarily as an interface between C++ callers and the 10 corresponding NPVariant type. CppVariant also provides a number of 11 convenience constructors and accessors, so that the NPVariantType values 12 don't need to be exposed, and a destructor to free any memory allocated for 13 string values. 14 15 For a usage example, see cpp_binding_example.{h|cc}. 16 */ 17 18 #ifndef WEBKIT_GLUE_CPP_VARIANT_H__ 19 #define WEBKIT_GLUE_CPP_VARIANT_H__ 20 21 #include <string> 22 #include <vector> 23 24 #include "base/basictypes.h" 25 #include "third_party/npapi/bindings/npruntime.h" 26 27 class CppVariant : public NPVariant { 28 public: 29 CppVariant(); 30 ~CppVariant(); 31 void SetNull(); 32 void Set(bool value); 33 void Set(int32_t value); 34 void Set(double value); 35 36 // Note that setting a CppVariant to a string value involves copying the 37 // string data, which must be freed with a call to FreeData() when the 38 // CppVariant is set to a different value or is no longer needed. Normally 39 // this is handled by the other Set() methods and by the destructor. 40 void Set(const char* value); // Must be a null-terminated string. 41 void Set(const std::string& value); 42 void Set(const NPString& new_value); 43 void Set(const NPVariant& new_value); 44 45 // Note that setting a CppVariant to an NPObject involves ref-counting 46 // the actual object. FreeData() should only be called if the CppVariant 47 // is no longer needed. The other Set() methods handle this internally. 48 // Also, the object's NPClass is expected to be a static object: neither 49 // the NP runtime nor CPPVariant will ever free it. 50 void Set(NPObject* new_value); 51 52 // These three methods all perform deep copies of any string data. This 53 // allows local CppVariants to be released by the destructor without 54 // corrupting their sources. In performance-critical code, or when strings 55 // are very long, avoid creating new CppVariants. 56 // In case of NPObject as the data, the copying involves ref-counting 57 // as opposed to deep-copying. The ref-counting ensures that sources don't 58 // get corrupted when the copies get destroyed. 59 void CopyToNPVariant(NPVariant* result) const; 60 CppVariant& operator=(const CppVariant& original); 61 CppVariant(const CppVariant& original); 62 63 // Calls NPN_ReleaseVariantValue, which frees any string data 64 // held by the object and sets its type to null. 65 // In case of NPObject, the NPN_ReleaseVariantValue decrements 66 // the ref-count (releases when ref-count becomes 0) 67 void FreeData(); 68 69 // Compares this CppVariant's type and value to another's. They must be 70 // identical in both type and value to be considered equal. For string and 71 // object types, a deep comparison is performed; that is, the contents of the 72 // strings, or the classes and refcounts of the objects, must be the same, 73 // but they need not be the same pointers. 74 bool isEqual(const CppVariant& other) const; 75 76 // The value of a CppVariant may be read directly from its NPVariant (but 77 // should only be set using one of the Set() methods above). Although the 78 // type of a CppVariant is likewise public, it can be accessed through these 79 // functions rather than directly if a caller wishes to avoid dependence on 80 // the NPVariantType values. isBool()81 bool isBool() const { return (type == NPVariantType_Bool); } isInt32()82 bool isInt32() const { return (type == NPVariantType_Int32); } isDouble()83 bool isDouble() const { return (type == NPVariantType_Double); } isNumber()84 bool isNumber() const { return (isInt32() || isDouble()); } isString()85 bool isString() const { return (type == NPVariantType_String); } isVoid()86 bool isVoid() const { return (type == NPVariantType_Void); } isNull()87 bool isNull() const { return (type == NPVariantType_Null); } isEmpty()88 bool isEmpty() const { return (isVoid() || isNull()); } isObject()89 bool isObject() const { return (type == NPVariantType_Object); } 90 91 // Converters. The CppVariant must be of a type convertible to these values. 92 // For example, ToInt32() works only if isNumber() is true. 93 std::string ToString() const; 94 int32_t ToInt32() const; 95 double ToDouble() const; 96 bool ToBoolean() const; 97 // Returns a vector of CppVariant for the specified variant. This should only 98 // be called on an Object. If the object has no "length" property an empty 99 // vector is returned. 100 std::vector<CppVariant> ToVector() const; 101 102 // Invoke method of the given name on an object with the supplied arguments. 103 // The first argument should be the object on which the method is to be 104 // invoked. Returns whether the method was successfully invoked. If the 105 // method was invoked successfully, any return value is stored in the 106 // CppVariant specified by result. 107 bool Invoke(const std::string& method, const CppVariant* args, 108 uint32 arg_count, CppVariant& result) const; 109 }; 110 111 #endif // WEBKIT_GLUE_CPP_VARIANT_H__ 112