1 // Copyright (c) 2014 Marshall A. Greenblatt. All rights reserved.
3 // Redistribution and use in source and binary forms, with or without
4 // modification, are permitted provided that the following conditions are
7 // * Redistributions of source code must retain the above copyright
8 // notice, this list of conditions and the following disclaimer.
9 // * Redistributions in binary form must reproduce the above
10 // copyright notice, this list of conditions and the following disclaimer
11 // in the documentation and/or other materials provided with the
13 // * Neither the name of Google Inc. nor the name Chromium Embedded
14 // Framework nor the names of its contributors may be used to endorse
15 // or promote products derived from this software without specific prior
16 // written permission.
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.
30 // ---------------------------------------------------------------------------
32 // The contents of this file are only available to applications that link
33 // against the libcef_dll_wrapper target.
36 #ifndef CEF_INCLUDE_WRAPPER_CEF_MESSAGE_ROUTER_H_
37 #define CEF_INCLUDE_WRAPPER_CEF_MESSAGE_ROUTER_H_
40 #include "include/base/cef_ref_counted.h"
41 #include "include/cef_base.h"
42 #include "include/cef_browser.h"
43 #include "include/cef_process_message.h"
44 #include "include/cef_v8.h"
46 // The below classes implement support for routing aynchronous messages between
47 // JavaScript running in the renderer process and C++ running in the browser
48 // process. An application interacts with the router by passing it data from
49 // standard CEF C++ callbacks (OnBeforeBrowse, OnProcessMessageRecieved,
50 // OnContextCreated, etc). The renderer-side router supports generic JavaScript
51 // callback registration and execution while the browser-side router supports
52 // application-specific logic via one or more application-provided Handler
55 // The renderer-side router implementation exposes a query function and a cancel
56 // function via the JavaScript 'window' object:
58 // // Create and send a new query.
59 // var request_id = window.cefQuery({
60 // request: 'my_request',
62 // onSuccess: function(response) {},
63 // onFailure: function(error_code, error_message) {}
66 // // Optionally cancel the query.
67 // window.cefQueryCancel(request_id);
69 // When |window.cefQuery| is executed the request is sent asynchronously to one
70 // or more C++ Handler objects registered in the browser process. Each C++
71 // Handler can choose to either handle or ignore the query in the
72 // Handler::OnQuery callback. If a Handler chooses to handle the query then it
73 // should execute Callback::Success when a response is available or
74 // Callback::Failure if an error occurs. This will result in asynchronous
75 // execution of the associated JavaScript callback in the renderer process. Any
76 // queries unhandled by C++ code in the browser process will be automatically
77 // canceled and the associated JavaScript onFailure callback will be executed
78 // with an error code of -1.
80 // Queries can be either persistent or non-persistent. If the query is
81 // persistent than the callbacks will remain registered until one of the
82 // following conditions are met:
84 // A. The query is canceled in JavaScript using the |window.cefQueryCancel|
86 // B. The query is canceled in C++ code using the Callback::Failure function.
87 // C. The context associated with the query is released due to browser
88 // destruction, navigation or renderer process termination.
90 // If the query is non-persistent then the registration will be removed after
91 // the JavaScript callback is executed a single time. If a query is canceled for
92 // a reason other than Callback::Failure being executed then the associated
93 // Handler's OnQueryCanceled method will be called.
95 // Some possible usage patterns include:
97 // One-time Request. Use a non-persistent query to send a JavaScript request.
98 // The Handler evaluates the request and returns the response. The query is
101 // Broadcast. Use a persistent query to register as a JavaScript broadcast
102 // receiver. The Handler keeps track of all registered Callbacks and executes
103 // them sequentially to deliver the broadcast message.
105 // Subscription. Use a persistent query to register as a JavaScript subscription
106 // receiver. The Handler initiates the subscription feed on the first request
107 // and delivers responses to all registered subscribers as they become
108 // available. The Handler cancels the subscription feed when there are no
109 // longer any registered JavaScript receivers.
111 // Message routing occurs on a per-browser and per-context basis. Consequently,
112 // additional application logic can be applied by restricting which browser or
113 // context instances are passed into the router. If you choose to use this
114 // approach do so cautiously. In order for the router to function correctly any
115 // browser or context instance passed into a single router callback must then
116 // be passed into all router callbacks.
118 // There is generally no need to have multiple renderer-side routers unless you
119 // wish to have multiple bindings with different JavaScript function names. It
120 // can be useful to have multiple browser-side routers with different client-
121 // provided Handler instances when implementing different behaviors on a per-
124 // This implementation places no formatting restrictions on payload content.
125 // An application may choose to exchange anything from simple formatted
126 // strings to serialized XML or JSON data.
131 // 1. Define the router configuration. You can optionally specify settings
132 // like the JavaScript function names. The configuration must be the same in
133 // both the browser and renderer processes. If using multiple routers in the
134 // same application make sure to specify unique function names for each
135 // router configuration.
137 // // Example config object showing the default values.
138 // CefMessageRouterConfig config;
139 // config.js_query_function = "cefQuery";
140 // config.js_cancel_function = "cefQueryCancel";
142 // 2. Create an instance of CefMessageRouterBrowserSide in the browser process.
143 // You might choose to make it a member of your CefClient implementation,
146 // browser_side_router_ = CefMessageRouterBrowserSide::Create(config);
148 // 3. Register one or more Handlers. The Handler instances must either outlive
149 // the router or be removed from the router before they're deleted.
151 // browser_side_router_->AddHandler(my_handler);
153 // 4. Call all required CefMessageRouterBrowserSide methods from other callbacks
154 // in your CefClient implementation (OnBeforeClose, etc). See the
155 // CefMessageRouterBrowserSide class documentation for the complete list of
158 // 5. Create an instance of CefMessageRouterRendererSide in the renderer process.
159 // You might choose to make it a member of your CefApp implementation, for
162 // renderer_side_router_ = CefMessageRouterRendererSide::Create(config);
164 // 6. Call all required CefMessageRouterRendererSide methods from other
165 // callbacks in your CefRenderProcessHandler implementation
166 // (OnContextCreated, etc). See the CefMessageRouterRendererSide class
167 // documentation for the complete list of methods.
169 // 7. Execute the query function from JavaScript code.
171 // window.cefQuery({request: 'my_request',
172 // persistent: false,
173 // onSuccess: function(response) { print(response); },
174 // onFailure: function(error_code, error_message) {} });
176 // 8. Handle the query in your Handler::OnQuery implementation and execute the
177 // appropriate callback either immediately or asynchronously.
179 // void MyHandler::OnQuery(int64 query_id,
180 // CefRefPtr<CefBrowser> browser,
181 // CefRefPtr<CefFrame> frame,
182 // const CefString& request,
184 // CefRefPtr<Callback> callback) {
185 // if (request == "my_request") {
186 // callback->Continue("my_response");
189 // return false; // Not handled.
192 // 9. Notice that the onSuccess callback is executed in JavaScript.
195 // Used to configure the query router. The same values must be passed to both
196 // CefMessageRouterBrowserSide and CefMessageRouterRendererSide. If using multiple
197 // router pairs make sure to choose values that do not conflict.
199 struct CefMessageRouterConfig {
200 CefMessageRouterConfig();
202 // Name of the JavaScript function that will be added to the 'window' object
203 // for sending a query. The default value is "cefQuery".
204 CefString js_query_function;
206 // Name of the JavaScript function that will be added to the 'window' object
207 // for canceling a pending query. The default value is "cefQueryCancel".
208 CefString js_cancel_function;
212 // Implements the browser side of query routing. The methods of this class may
213 // be called on any browser process thread unless otherwise indicated.
215 class CefMessageRouterBrowserSide :
216 public base::RefCountedThreadSafe<CefMessageRouterBrowserSide> {
219 // Callback associated with a single pending asynchronous query. Execute the
220 // Success or Failure method to send an asynchronous response to the
221 // associated JavaScript handler. It is a runtime error to destroy a Callback
222 // object associated with an uncanceled query without first executing one of
223 // the callback methods. The methods of this class may be called on any
224 // browser process thread.
226 class Callback : public CefBase {
229 // Notify the associated JavaScript onSuccess callback that the query has
230 // completed successfully with the specified |response|.
232 virtual void Success(const CefString& response) =0;
235 // Notify the associated JavaScript onFailure callback that the query has
236 // failed with the specified |error_code| and |error_message|.
238 virtual void Failure(int error_code, const CefString& error_message) =0;
242 // Implement this interface to handle queries. All methods will be executed on
243 // the browser process UI thread.
247 typedef CefMessageRouterBrowserSide::Callback Callback;
250 // Executed when a new query is received. |query_id| uniquely identifies the
251 // query for the life span of the router. Return true to handle the query
252 // or false to propagate the query to other registered handlers, if any. If
253 // no handlers return true from this method then the query will be
254 // automatically canceled with an error code of -1 delivered to the
255 // JavaScript onFailure callback. If this method returns true then a
256 // Callback method must be executed either in this method or asynchronously
257 // to complete the query.
259 virtual bool OnQuery(CefRefPtr<CefBrowser> browser,
260 CefRefPtr<CefFrame> frame,
262 const CefString& request,
264 CefRefPtr<Callback> callback) {
269 // Executed when a query has been canceled either explicitly using the
270 // JavaScript cancel function or implicitly due to browser destruction,
271 // navigation or renderer process termination. It will only be called for
272 // the single handler that returned true from OnQuery for the same
273 // |query_id|. No references to the associated Callback object should be
274 // kept after this method is called, nor should any Callback methods be
277 virtual void OnQueryCanceled(CefRefPtr<CefBrowser> browser,
278 CefRefPtr<CefFrame> frame,
281 virtual ~Handler() {}
285 // Create a new router with the specified configuration.
287 static CefRefPtr<CefMessageRouterBrowserSide> Create(
288 const CefMessageRouterConfig& config);
291 // Add a new query handler. If |first| is true it will be added as the first
292 // handler, otherwise it will be added as the last handler. Returns true if
293 // the handler is added successfully or false if the handler has already been
294 // added. Must be called on the browser process UI thread. The Handler object
295 // must either outlive the router or be removed before deletion.
297 virtual bool AddHandler(Handler* handler, bool first) =0;
300 // Remove an existing query handler. Any pending queries associated with the
301 // handler will be canceled. Handler::OnQueryCanceled will be called and the
302 // associated JavaScript onFailure callback will be executed with an error
303 // code of -1. Returns true if the handler is removed successfully or false
304 // if the handler is not found. Must be called on the browser process UI
307 virtual bool RemoveHandler(Handler* handler) =0;
310 // Cancel all pending queries associated with either |browser| or |handler|.
311 // If both |browser| and |handler| are NULL all pending queries will be
312 // canceled. Handler::OnQueryCanceled will be called and the associated
313 // JavaScript onFailure callback will be executed in all cases with an error
316 virtual void CancelPending(CefRefPtr<CefBrowser> browser,
317 Handler* handler) =0;
320 // Returns the number of queries currently pending for the specified |browser|
321 // and/or |handler|. Either or both values may be empty. Must be called on the
322 // browser process UI thread.
324 virtual int GetPendingCount(CefRefPtr<CefBrowser> browser,
325 Handler* handler) =0;
328 // The below methods should be called from other CEF handlers. They must be
329 // called exactly as documented for the router to function correctly.
332 // Call from CefLifeSpanHandler::OnBeforeClose. Any pending queries associated
333 // with |browser| will be canceled and Handler::OnQueryCanceled will be called.
334 // No JavaScript callbacks will be executed since this indicates destruction
337 virtual void OnBeforeClose(CefRefPtr<CefBrowser> browser) =0;
340 // Call from CefRequestHandler::OnRenderProcessTerminated. Any pending queries
341 // associated with |browser| will be canceled and Handler::OnQueryCanceled
342 // will be called. No JavaScript callbacks will be executed since this
343 // indicates destruction of the context.
345 virtual void OnRenderProcessTerminated(CefRefPtr<CefBrowser> browser) =0;
348 // Call from CefRequestHandler::OnBeforeBrowse only if the navigation is
349 // allowed to proceed. If |frame| is the main frame then any pending queries
350 // associated with |browser| will be canceled and Handler::OnQueryCanceled
351 // will be called. No JavaScript callbacks will be executed since this
352 // indicates destruction of the context.
354 virtual void OnBeforeBrowse(CefRefPtr<CefBrowser> browser,
355 CefRefPtr<CefFrame> frame) =0;
358 // Call from CefClient::OnProcessMessageReceived. Returns true if the message
359 // is handled by this router or false otherwise.
361 virtual bool OnProcessMessageReceived(
362 CefRefPtr<CefBrowser> browser,
363 CefProcessId source_process,
364 CefRefPtr<CefProcessMessage> message) =0;
367 // Protect against accidental deletion of this object.
368 friend class base::RefCountedThreadSafe<CefMessageRouterBrowserSide>;
369 virtual ~CefMessageRouterBrowserSide() {}
373 // Implements the renderer side of query routing. The methods of this class must
374 // be called on the render process main thread.
376 class CefMessageRouterRendererSide :
377 public base::RefCountedThreadSafe<CefMessageRouterRendererSide> {
380 // Create a new router with the specified configuration.
382 static CefRefPtr<CefMessageRouterRendererSide> Create(
383 const CefMessageRouterConfig& config);
386 // Returns the number of queries currently pending for the specified |browser|
387 // and/or |context|. Either or both values may be empty.
389 virtual int GetPendingCount(CefRefPtr<CefBrowser> browser,
390 CefRefPtr<CefV8Context> context) =0;
393 // The below methods should be called from other CEF handlers. They must be
394 // called exactly as documented for the router to function correctly.
397 // Call from CefRenderProcessHandler::OnContextCreated. Registers the
398 // JavaScripts functions with the new context.
400 virtual void OnContextCreated(CefRefPtr<CefBrowser> browser,
401 CefRefPtr<CefFrame> frame,
402 CefRefPtr<CefV8Context> context) =0;
405 // Call from CefRenderProcessHandler::OnContextReleased. Any pending queries
406 // associated with the released context will be canceled and
407 // Handler::OnQueryCanceled will be called in the browser process.
409 virtual void OnContextReleased(CefRefPtr<CefBrowser> browser,
410 CefRefPtr<CefFrame> frame,
411 CefRefPtr<CefV8Context> context) =0;
414 // Call from CefRenderProcessHandler::OnProcessMessageReceived. Returns true
415 // if the message is handled by this router or false otherwise.
417 virtual bool OnProcessMessageReceived(
418 CefRefPtr<CefBrowser> browser,
419 CefProcessId source_process,
420 CefRefPtr<CefProcessMessage> message) =0;
423 // Protect against accidental deletion of this object.
424 friend class base::RefCountedThreadSafe<CefMessageRouterRendererSide>;
425 virtual ~CefMessageRouterRendererSide() {}
428 #endif // CEF_INCLUDE_WRAPPER_CEF_MESSAGE_ROUTER_H_