1/*
2 * Copyright (C) 2010 Google Inc. All rights reserved.
3 *
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions are
6 * met:
7 *
8 *     * Redistributions of source code must retain the above copyright
9 * notice, this list of conditions and the following disclaimer.
10 *     * Redistributions in binary form must reproduce the above
11 * copyright notice, this list of conditions and the following disclaimer
12 * in the documentation and/or other materials provided with the
13 * distribution.
14 *     * Neither the name of Google Inc. nor the names of its
15 * contributors may be used to endorse or promote products derived from
16 * this software without specific prior written permission.
17 *
18 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
19 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
20 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
21 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
22 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
23 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
24 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
25 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
26 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
28 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29 */
30
31/*
32  This file contains the declaration for CppVariant, a type used by C++ classes
33  that are to be bound to JavaScript objects.
34
35  CppVariant exists primarily as an interface between C++ callers and the
36  corresponding NPVariant type.  CppVariant also provides a number of
37  convenience constructors and accessors, so that the NPVariantType values
38  don't need to be exposed, and a destructor to free any memory allocated for
39  string values.
40*/
41
42#ifndef CppVariant_h
43#define CppVariant_h
44
45#include "public/web/WebBindings.h"
46#include <string>
47#include <vector>
48
49namespace WebTestRunner {
50
51class CppVariant : public NPVariant {
52public:
53    CppVariant();
54    ~CppVariant();
55    void setNull();
56    void set(bool);
57    void set(int32_t);
58    void set(double);
59
60    // Note that setting a CppVariant to a string value involves copying the
61    // string data, which must be freed with a call to freeData() when the
62    // CppVariant is set to a different value or is no longer needed. Normally
63    // this is handled by the other set() methods and by the destructor.
64    void set(const char*); // Must be a null-terminated string.
65    void set(const std::string&);
66    void set(const NPString&);
67    void set(const NPVariant&);
68
69    // Note that setting a CppVariant to an NPObject involves ref-counting
70    // the actual object. freeData() should only be called if the CppVariant
71    // is no longer needed. The other set() methods handle this internally.
72    // Also, the object's NPClass is expected to be a static object: neither
73    // the NP runtime nor CppVariant will ever free it.
74    void set(NPObject*_value);
75
76    // These three methods all perform deep copies of any string data. This
77    // allows local CppVariants to be released by the destructor without
78    // corrupting their sources. In performance-critical code, or when strings
79    // are very long, avoid creating new CppVariants.
80    // In case of NPObject as the data, the copying involves ref-counting
81    // as opposed to deep-copying. The ref-counting ensures that sources don't
82    // get corrupted when the copies get destroyed.
83    void copyToNPVariant(NPVariant* result) const;
84    CppVariant& operator=(const CppVariant& original);
85    CppVariant(const CppVariant& original);
86
87    // Calls NPN_ReleaseVariantValue, which frees any string data
88    // held by the object and sets its type to null.
89    // In case of NPObject, the NPN_ReleaseVariantValue decrements
90    // the ref-count (releases when ref-count becomes 0)
91    void freeData();
92
93    // Compares this CppVariant's type and value to another's. They must be
94    // identical in both type and value to be considered equal. For string and
95    // object types, a deep comparison is performed; that is, the contents of the
96    // strings, or the classes and refcounts of the objects, must be the same,
97    // but they need not be the same pointers.
98    bool isEqual(const CppVariant&) const;
99
100    // The value of a CppVariant may be read directly from its NPVariant (but
101    // should only be set using one of the set() methods above). Although the
102    // type of a CppVariant is likewise public, it can be accessed through these
103    // functions rather than directly if a caller wishes to avoid dependence on
104    // the NPVariantType values.
105    bool isBool() const { return (type == NPVariantType_Bool); }
106    bool isInt32() const { return (type == NPVariantType_Int32); }
107    bool isDouble() const { return (type == NPVariantType_Double); }
108    bool isNumber() const { return (isInt32() || isDouble()); }
109    bool isString() const { return (type == NPVariantType_String); }
110    bool isVoid() const { return (type == NPVariantType_Void); }
111    bool isNull() const { return (type == NPVariantType_Null); }
112    bool isEmpty() const { return (isVoid() || isNull()); }
113    bool isObject() const { return (type == NPVariantType_Object); }
114
115    // Converters. The CppVariant must be of a type convertible to these values.
116    // For example, toInt32() works only if isNumber() is true.
117    std::string toString() const;
118    int32_t toInt32() const;
119    double toDouble() const;
120    bool toBoolean() const;
121    // Returns a vector of strings for the specified argument. This is useful
122    // for converting a JavaScript array of strings into a vector of strings.
123    std::vector<std::string> toStringVector() const;
124
125    // Invoke method of the given name on an object with the supplied arguments.
126    // The first argument should be the object on which the method is to be
127    // invoked. Returns whether the method was successfully invoked. If the
128    // method was invoked successfully, any return value is stored in the
129    // CppVariant specified by result.
130    bool invoke(const std::string&, const CppVariant* arguments,
131                uint32_t argumentCount, CppVariant& result) const;
132
133    // Invoke an object's default method with the supplied arguments.
134    // The first argument should be the object on which the method is to be
135    // invoked. Returns whether the method was successfully invoked. If the
136    // method was invoked successfully, any return value is stored in the
137    // CppVariant specified by result.
138    bool invokeDefault(const CppVariant* arguments,
139                       uint32_t argumentCount, CppVariant& result) const;
140};
141
142}
143
144#endif // CppVariant_h
145