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.
7 This base class serves as a parent for C++ classes designed to be bound to
10 Subclasses should define the constructor to build the property and method
11 lists needed to bind this class to a JS object. They should also declare
12 and define member variables and methods to be exposed to JS through
15 See cpp_binding_example.{h|cc} for an example.
18 #ifndef WEBKIT_GLUE_CPP_BOUND_CLASS_H_
19 #define WEBKIT_GLUE_CPP_BOUND_CLASS_H_
24 #include "base/callback.h"
25 #include "webkit/glue/cpp_variant.h"
26 #include "webkit/glue/webkit_glue_export.h"
32 namespace webkit_glue
{
34 typedef std::vector
<CppVariant
> CppArgumentList
;
36 // CppBoundClass lets you map Javascript method calls and property accesses
37 // directly to C++ method calls and CppVariant* variable access.
38 class WEBKIT_GLUE_EXPORT CppBoundClass
{
40 class PropertyCallback
{
42 virtual ~PropertyCallback() { }
44 // Sets |value| to the value of the property. Returns false in case of
45 // failure. |value| is always non-NULL.
46 virtual bool GetValue(CppVariant
* value
) = 0;
48 // sets the property value to |value|. Returns false in case of failure.
49 virtual bool SetValue(const CppVariant
& value
) = 0;
52 // The constructor should call BindCallback, BindProperty, and
53 // BindFallbackCallback as needed to set up the methods, properties, and
56 virtual ~CppBoundClass();
58 // Return a CppVariant representing this class, for use with BindProperty().
59 // The variant type is guaranteed to be NPVariantType_Object.
60 CppVariant
* GetAsCppVariant();
62 // Given a WebFrame, BindToJavascript builds the NPObject that will represent
63 // this CppBoundClass object and binds it to the frame's window under the
64 // given name. This should generally be called from the WebView delegate's
65 // WindowObjectCleared(). This CppBoundClass object will be accessible to
66 // JavaScript as window.<classname>. The owner of this CppBoundClass object is
67 // responsible for keeping it around while the frame is alive, and for
68 // destroying it afterwards.
69 void BindToJavascript(WebKit::WebFrame
* frame
, const std::string
& classname
);
71 // The type of callbacks.
72 typedef base::Callback
<void(const CppArgumentList
&, CppVariant
*)> Callback
;
73 typedef base::Callback
<void(CppVariant
*)> GetterCallback
;
75 // Used by a test. Returns true if a method with name |name| exists,
76 // regardless of whether a fallback is registered.
77 bool IsMethodRegistered(const std::string
& name
) const;
80 // Bind the Javascript method called |name| to the C++ callback |callback|.
81 void BindCallback(const std::string
& name
, const Callback
& callback
);
83 // Bind Javascript property |name| to the C++ getter callback |callback|.
84 // This can be used to create read-only properties.
85 void BindGetterCallback(const std::string
& name
,
86 const GetterCallback
& callback
);
88 // Bind the Javascript property called |name| to a CppVariant |prop|.
89 void BindProperty(const std::string
& name
, CppVariant
* prop
);
91 // Bind Javascript property called |name| to a PropertyCallback |callback|.
92 // CppBoundClass assumes control over the life time of the |callback|.
93 void BindProperty(const std::string
& name
, PropertyCallback
* callback
);
95 // Set the fallback callback, which is called when when a callback is
96 // invoked that isn't bound.
97 // If it is NULL (its default value), a JavaScript exception is thrown in
98 // that case (as normally expected). If non NULL, the fallback method is
99 // invoked and the script continues its execution.
100 // Passing NULL for |callback| clears out any existing binding.
101 // It is used for tests and should probably only be used in such cases
102 // as it may cause unexpected behaviors (a JavaScript object with a
103 // fallback always returns true when checked for a method's
105 void BindFallbackCallback(const Callback
& fallback_callback
) {
106 fallback_callback_
= fallback_callback
;
109 // Some fields are protected because some tests depend on accessing them,
110 // but otherwise they should be considered private.
112 typedef std::map
<NPIdentifier
, PropertyCallback
*> PropertyList
;
113 typedef std::map
<NPIdentifier
, Callback
> MethodList
;
114 // These maps associate names with property and method pointers to be
115 // exposed to JavaScript.
116 PropertyList properties_
;
119 // The callback gets invoked when a call is made to an nonexistent method.
120 Callback fallback_callback_
;
123 // NPObject callbacks.
124 friend struct CppNPObject
;
125 bool HasMethod(NPIdentifier ident
) const;
126 bool Invoke(NPIdentifier ident
, const NPVariant
* args
, size_t arg_count
,
128 bool HasProperty(NPIdentifier ident
) const;
129 bool GetProperty(NPIdentifier ident
, NPVariant
* result
) const;
130 bool SetProperty(NPIdentifier ident
, const NPVariant
* value
);
132 // A lazily-initialized CppVariant representing this class. We retain 1
133 // reference to this object, and it is released on deletion.
134 CppVariant self_variant_
;
136 // True if our np_object has been bound to a WebFrame, in which case it must
137 // be unregistered with V8 when we delete it.
138 bool bound_to_frame_
;
140 DISALLOW_COPY_AND_ASSIGN(CppBoundClass
);
143 } // namespace webkit_glue
145 #endif // WEBKIT_GLUE_CPP_BOUND_CLASS_H_