cyf
148 lines
6.9 KiB
Plaintext
148 lines
6.9 KiB
Plaintext
// 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.
|