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
27class 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.
81  bool isBool() const { return (type == NPVariantType_Bool); }
82  bool isInt32() const { return (type == NPVariantType_Int32); }
83  bool isDouble() const { return (type == NPVariantType_Double); }
84  bool isNumber() const { return (isInt32() || isDouble()); }
85  bool isString() const { return (type == NPVariantType_String); }
86  bool isVoid() const { return (type == NPVariantType_Void); }
87  bool isNull() const { return (type == NPVariantType_Null); }
88  bool isEmpty() const { return (isVoid() || isNull()); }
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