src/webkit/renderer/cpp_variant.h

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