--- /dev/null
+// Copyright (c) 2014 Marshall A. Greenblatt. All rights reserved.
+//
+// Redistribution and use in source and binary forms, with or without
+// modification, are permitted provided that the following conditions are
+// met:
+//
+// * Redistributions of source code must retain the above copyright
+// notice, this list of conditions and the following disclaimer.
+// * Redistributions in binary form must reproduce the above
+// copyright notice, this list of conditions and the following disclaimer
+// in the documentation and/or other materials provided with the
+// distribution.
+// * Neither the name of Google Inc. nor the name Chromium Embedded
+// Framework nor the names of its contributors may be used to endorse
+// or promote products derived from this software without specific prior
+// written permission.
+//
+// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+//
+// ---------------------------------------------------------------------------
+//
+// The contents of this file are only available to applications that link
+// against the libcef_dll_wrapper target.
+//
+
+#ifndef CEF_INCLUDE_WRAPPER_CEF_MESSAGE_ROUTER_H_
+#define CEF_INCLUDE_WRAPPER_CEF_MESSAGE_ROUTER_H_
+#pragma once
+
+#include "include/base/cef_ref_counted.h"
+#include "include/cef_base.h"
+#include "include/cef_browser.h"
+#include "include/cef_process_message.h"
+#include "include/cef_v8.h"
+
+// The below classes implement support for routing aynchronous messages between
+// JavaScript running in the renderer process and C++ running in the browser
+// process. An application interacts with the router by passing it data from
+// standard CEF C++ callbacks (OnBeforeBrowse, OnProcessMessageRecieved,
+// OnContextCreated, etc). The renderer-side router supports generic JavaScript
+// callback registration and execution while the browser-side router supports
+// application-specific logic via one or more application-provided Handler
+// instances.
+//
+// The renderer-side router implementation exposes a query function and a cancel
+// function via the JavaScript 'window' object:
+//
+// // Create and send a new query.
+// var request_id = window.cefQuery({
+// request: 'my_request',
+// persistent: false,
+// onSuccess: function(response) {},
+// onFailure: function(error_code, error_message) {}
+// });
+//
+// // Optionally cancel the query.
+// window.cefQueryCancel(request_id);
+//
+// When |window.cefQuery| is executed the request is sent asynchronously to one
+// or more C++ Handler objects registered in the browser process. Each C++
+// Handler can choose to either handle or ignore the query in the
+// Handler::OnQuery callback. If a Handler chooses to handle the query then it
+// should execute Callback::Success when a response is available or
+// Callback::Failure if an error occurs. This will result in asynchronous
+// execution of the associated JavaScript callback in the renderer process. Any
+// queries unhandled by C++ code in the browser process will be automatically
+// canceled and the associated JavaScript onFailure callback will be executed
+// with an error code of -1.
+//
+// Queries can be either persistent or non-persistent. If the query is
+// persistent than the callbacks will remain registered until one of the
+// following conditions are met:
+//
+// A. The query is canceled in JavaScript using the |window.cefQueryCancel|
+// function.
+// B. The query is canceled in C++ code using the Callback::Failure function.
+// C. The context associated with the query is released due to browser
+// destruction, navigation or renderer process termination.
+//
+// If the query is non-persistent then the registration will be removed after
+// the JavaScript callback is executed a single time. If a query is canceled for
+// a reason other than Callback::Failure being executed then the associated
+// Handler's OnQueryCanceled method will be called.
+//
+// Some possible usage patterns include:
+//
+// One-time Request. Use a non-persistent query to send a JavaScript request.
+// The Handler evaluates the request and returns the response. The query is
+// then discarded.
+//
+// Broadcast. Use a persistent query to register as a JavaScript broadcast
+// receiver. The Handler keeps track of all registered Callbacks and executes
+// them sequentially to deliver the broadcast message.
+//
+// Subscription. Use a persistent query to register as a JavaScript subscription
+// receiver. The Handler initiates the subscription feed on the first request
+// and delivers responses to all registered subscribers as they become
+// available. The Handler cancels the subscription feed when there are no
+// longer any registered JavaScript receivers.
+//
+// Message routing occurs on a per-browser and per-context basis. Consequently,
+// additional application logic can be applied by restricting which browser or
+// context instances are passed into the router. If you choose to use this
+// approach do so cautiously. In order for the router to function correctly any
+// browser or context instance passed into a single router callback must then
+// be passed into all router callbacks.
+//
+// There is generally no need to have multiple renderer-side routers unless you
+// wish to have multiple bindings with different JavaScript function names. It
+// can be useful to have multiple browser-side routers with different client-
+// provided Handler instances when implementing different behaviors on a per-
+// browser basis.
+//
+// This implementation places no formatting restrictions on payload content.
+// An application may choose to exchange anything from simple formatted
+// strings to serialized XML or JSON data.
+//
+//
+// EXAMPLE USAGE
+//
+// 1. Define the router configuration. You can optionally specify settings
+// like the JavaScript function names. The configuration must be the same in
+// both the browser and renderer processes. If using multiple routers in the
+// same application make sure to specify unique function names for each
+// router configuration.
+//
+// // Example config object showing the default values.
+// CefMessageRouterConfig config;
+// config.js_query_function = "cefQuery";
+// config.js_cancel_function = "cefQueryCancel";
+//
+// 2. Create an instance of CefMessageRouterBrowserSide in the browser process.
+// You might choose to make it a member of your CefClient implementation,
+// for example.
+//
+// browser_side_router_ = CefMessageRouterBrowserSide::Create(config);
+//
+// 3. Register one or more Handlers. The Handler instances must either outlive
+// the router or be removed from the router before they're deleted.
+//
+// browser_side_router_->AddHandler(my_handler);
+//
+// 4. Call all required CefMessageRouterBrowserSide methods from other callbacks
+// in your CefClient implementation (OnBeforeClose, etc). See the
+// CefMessageRouterBrowserSide class documentation for the complete list of
+// methods.
+//
+// 5. Create an instance of CefMessageRouterRendererSide in the renderer process.
+// You might choose to make it a member of your CefApp implementation, for
+// example.
+//
+// renderer_side_router_ = CefMessageRouterRendererSide::Create(config);
+//
+// 6. Call all required CefMessageRouterRendererSide methods from other
+// callbacks in your CefRenderProcessHandler implementation
+// (OnContextCreated, etc). See the CefMessageRouterRendererSide class
+// documentation for the complete list of methods.
+//
+// 7. Execute the query function from JavaScript code.
+//
+// window.cefQuery({request: 'my_request',
+// persistent: false,
+// onSuccess: function(response) { print(response); },
+// onFailure: function(error_code, error_message) {} });
+//
+// 8. Handle the query in your Handler::OnQuery implementation and execute the
+// appropriate callback either immediately or asynchronously.
+//
+// void MyHandler::OnQuery(int64 query_id,
+// CefRefPtr<CefBrowser> browser,
+// CefRefPtr<CefFrame> frame,
+// const CefString& request,
+// bool persistent,
+// CefRefPtr<Callback> callback) {
+// if (request == "my_request") {
+// callback->Continue("my_response");
+// return true;
+// }
+// return false; // Not handled.
+// }
+//
+// 9. Notice that the onSuccess callback is executed in JavaScript.
+
+///
+// Used to configure the query router. The same values must be passed to both
+// CefMessageRouterBrowserSide and CefMessageRouterRendererSide. If using multiple
+// router pairs make sure to choose values that do not conflict.
+///
+struct CefMessageRouterConfig {
+ CefMessageRouterConfig();
+
+ // Name of the JavaScript function that will be added to the 'window' object
+ // for sending a query. The default value is "cefQuery".
+ CefString js_query_function;
+
+ // Name of the JavaScript function that will be added to the 'window' object
+ // for canceling a pending query. The default value is "cefQueryCancel".
+ CefString js_cancel_function;
+};
+
+///
+// Implements the browser side of query routing. The methods of this class may
+// be called on any browser process thread unless otherwise indicated.
+///
+class CefMessageRouterBrowserSide :
+ public base::RefCountedThreadSafe<CefMessageRouterBrowserSide> {
+ public:
+ ///
+ // Callback associated with a single pending asynchronous query. Execute the
+ // Success or Failure method to send an asynchronous response to the
+ // associated JavaScript handler. It is a runtime error to destroy a Callback
+ // object associated with an uncanceled query without first executing one of
+ // the callback methods. The methods of this class may be called on any
+ // browser process thread.
+ ///
+ class Callback : public CefBaseRefCounted {
+ public:
+ ///
+ // Notify the associated JavaScript onSuccess callback that the query has
+ // completed successfully with the specified |response|.
+ ///
+ virtual void Success(const CefString& response) =0;
+
+ ///
+ // Notify the associated JavaScript onFailure callback that the query has
+ // failed with the specified |error_code| and |error_message|.
+ ///
+ virtual void Failure(int error_code, const CefString& error_message) =0;
+ };
+
+ ///
+ // Implement this interface to handle queries. All methods will be executed on
+ // the browser process UI thread.
+ ///
+ class Handler {
+ public:
+ typedef CefMessageRouterBrowserSide::Callback Callback;
+
+ ///
+ // Executed when a new query is received. |query_id| uniquely identifies the
+ // query for the life span of the router. Return true to handle the query
+ // or false to propagate the query to other registered handlers, if any. If
+ // no handlers return true from this method then the query will be
+ // automatically canceled with an error code of -1 delivered to the
+ // JavaScript onFailure callback. If this method returns true then a
+ // Callback method must be executed either in this method or asynchronously
+ // to complete the query.
+ ///
+ virtual bool OnQuery(CefRefPtr<CefBrowser> browser,
+ CefRefPtr<CefFrame> frame,
+ int64 query_id,
+ const CefString& request,
+ bool persistent,
+ CefRefPtr<Callback> callback) {
+ return false;
+ }
+
+ ///
+ // Executed when a query has been canceled either explicitly using the
+ // JavaScript cancel function or implicitly due to browser destruction,
+ // navigation or renderer process termination. It will only be called for
+ // the single handler that returned true from OnQuery for the same
+ // |query_id|. No references to the associated Callback object should be
+ // kept after this method is called, nor should any Callback methods be
+ // executed.
+ ///
+ virtual void OnQueryCanceled(CefRefPtr<CefBrowser> browser,
+ CefRefPtr<CefFrame> frame,
+ int64 query_id) {}
+
+ virtual ~Handler() {}
+ };
+
+ ///
+ // Create a new router with the specified configuration.
+ ///
+ static CefRefPtr<CefMessageRouterBrowserSide> Create(
+ const CefMessageRouterConfig& config);
+
+ ///
+ // Add a new query handler. If |first| is true it will be added as the first
+ // handler, otherwise it will be added as the last handler. Returns true if
+ // the handler is added successfully or false if the handler has already been
+ // added. Must be called on the browser process UI thread. The Handler object
+ // must either outlive the router or be removed before deletion.
+ ///
+ virtual bool AddHandler(Handler* handler, bool first) =0;
+
+ ///
+ // Remove an existing query handler. Any pending queries associated with the
+ // handler will be canceled. Handler::OnQueryCanceled will be called and the
+ // associated JavaScript onFailure callback will be executed with an error
+ // code of -1. Returns true if the handler is removed successfully or false
+ // if the handler is not found. Must be called on the browser process UI
+ // thread.
+ ///
+ virtual bool RemoveHandler(Handler* handler) =0;
+
+ ///
+ // Cancel all pending queries associated with either |browser| or |handler|.
+ // If both |browser| and |handler| are NULL all pending queries will be
+ // canceled. Handler::OnQueryCanceled will be called and the associated
+ // JavaScript onFailure callback will be executed in all cases with an error
+ // code of -1.
+ ///
+ virtual void CancelPending(CefRefPtr<CefBrowser> browser,
+ Handler* handler) =0;
+
+ ///
+ // Returns the number of queries currently pending for the specified |browser|
+ // and/or |handler|. Either or both values may be empty. Must be called on the
+ // browser process UI thread.
+ ///
+ virtual int GetPendingCount(CefRefPtr<CefBrowser> browser,
+ Handler* handler) =0;
+
+
+ // The below methods should be called from other CEF handlers. They must be
+ // called exactly as documented for the router to function correctly.
+
+ ///
+ // Call from CefLifeSpanHandler::OnBeforeClose. Any pending queries associated
+ // with |browser| will be canceled and Handler::OnQueryCanceled will be called.
+ // No JavaScript callbacks will be executed since this indicates destruction
+ // of the browser.
+ ///
+ virtual void OnBeforeClose(CefRefPtr<CefBrowser> browser) =0;
+
+ ///
+ // Call from CefRequestHandler::OnRenderProcessTerminated. Any pending queries
+ // associated with |browser| will be canceled and Handler::OnQueryCanceled
+ // will be called. No JavaScript callbacks will be executed since this
+ // indicates destruction of the context.
+ ///
+ virtual void OnRenderProcessTerminated(CefRefPtr<CefBrowser> browser) =0;
+
+ ///
+ // Call from CefRequestHandler::OnBeforeBrowse only if the navigation is
+ // allowed to proceed. If |frame| is the main frame then any pending queries
+ // associated with |browser| will be canceled and Handler::OnQueryCanceled
+ // will be called. No JavaScript callbacks will be executed since this
+ // indicates destruction of the context.
+ ///
+ virtual void OnBeforeBrowse(CefRefPtr<CefBrowser> browser,
+ CefRefPtr<CefFrame> frame) =0;
+
+ ///
+ // Call from CefClient::OnProcessMessageReceived. Returns true if the message
+ // is handled by this router or false otherwise.
+ ///
+ virtual bool OnProcessMessageReceived(
+ CefRefPtr<CefBrowser> browser,
+ CefProcessId source_process,
+ CefRefPtr<CefProcessMessage> message) =0;
+
+ protected:
+ // Protect against accidental deletion of this object.
+ friend class base::RefCountedThreadSafe<CefMessageRouterBrowserSide>;
+ virtual ~CefMessageRouterBrowserSide() {}
+};
+
+///
+// Implements the renderer side of query routing. The methods of this class must
+// be called on the render process main thread.
+///
+class CefMessageRouterRendererSide :
+ public base::RefCountedThreadSafe<CefMessageRouterRendererSide> {
+ public:
+ ///
+ // Create a new router with the specified configuration.
+ ///
+ static CefRefPtr<CefMessageRouterRendererSide> Create(
+ const CefMessageRouterConfig& config);
+
+ ///
+ // Returns the number of queries currently pending for the specified |browser|
+ // and/or |context|. Either or both values may be empty.
+ ///
+ virtual int GetPendingCount(CefRefPtr<CefBrowser> browser,
+ CefRefPtr<CefV8Context> context) =0;
+
+
+ // The below methods should be called from other CEF handlers. They must be
+ // called exactly as documented for the router to function correctly.
+
+ ///
+ // Call from CefRenderProcessHandler::OnContextCreated. Registers the
+ // JavaScripts functions with the new context.
+ ///
+ virtual void OnContextCreated(CefRefPtr<CefBrowser> browser,
+ CefRefPtr<CefFrame> frame,
+ CefRefPtr<CefV8Context> context) =0;
+
+ ///
+ // Call from CefRenderProcessHandler::OnContextReleased. Any pending queries
+ // associated with the released context will be canceled and
+ // Handler::OnQueryCanceled will be called in the browser process.
+ ///
+ virtual void OnContextReleased(CefRefPtr<CefBrowser> browser,
+ CefRefPtr<CefFrame> frame,
+ CefRefPtr<CefV8Context> context) =0;
+
+ ///
+ // Call from CefRenderProcessHandler::OnProcessMessageReceived. Returns true
+ // if the message is handled by this router or false otherwise.
+ ///
+ virtual bool OnProcessMessageReceived(
+ CefRefPtr<CefBrowser> browser,
+ CefProcessId source_process,
+ CefRefPtr<CefProcessMessage> message) =0;
+
+ protected:
+ // Protect against accidental deletion of this object.
+ friend class base::RefCountedThreadSafe<CefMessageRouterRendererSide>;
+ virtual ~CefMessageRouterRendererSide() {}
+};
+
+#endif // CEF_INCLUDE_WRAPPER_CEF_MESSAGE_ROUTER_H_
projects / casparcg / blobdiff