public abstract class CefMessageRouter
extends java.lang.Object
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 = new CefMessageRouterConfig(); config.jsQueryFunction = "cefQuery"; config.jsCancelFunction = "cefQueryCancel"; 2. Create an instance of CefMessageRouter in the browser process. messageRouter_ = CefMessageRouter.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. messageRouter_.addHandler(myHandler); 4. Add your message router to all CefClient instances you want to get your JavaScript code be handled. myClient.addMessageRouter(messageRouter_); 4. 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) {} }); 5. Handle the query in your CefMessageRouterHandler.onQuery implementation and execute the appropriate callback either immediately or asynchronously. public boolean onQuery(CefBrowser browser, long query_id, String request, boolean persistent, CefQueryCallback callback) { if (request.indexOf("my_request") == 0) { callback.success("my_response"); return true; } return false; // Not handled. } 6. Notice that the success callback is executed in JavaScript.
以下类实现了对在渲染器进程中运行的JavaScript和浏览器进程中运行的C ++之间路由异步消息的支持。应用程序通过从标准CEF C ++回调（OnBeforeBrowse，OnProcessMessageRecieved，OnContextCreated等）传递数据来与路由器进行交互。呈现器端路由器支持通用的JavaScript回调注册和执行，而浏览器端路由器则通过一个或多个应用程序提供的Handler实例支持特定于应用程序的逻辑。渲染器端路由器实现通过JavaScript“窗口”对象公开查询功能和取消功能：//创建并发送新查询。 var request_id = window.cefQuery（{request：'my_request'，persistent：false，onSuccess：function（response）{}，onFailure：function（error_code，error_message）{}}）; //（可选）取消查询。 window.cefQueryCancel（request_id）; | window.cefQuery |执行该请求后，该请求将异步发送到在浏览器进程中注册的一个或多个C ++ Handler对象。每个C ++处理程序都可以选择处理或忽略Handler :: OnQuery回调中的查询。如果处理程序选择处理查询，则它应在响应可用时执行Callback :: Success或在发生错误时执行Callback :: Failure。这将导致渲染器进程中异步执行关联的JavaScript回调。浏览器进程中由C ++代码未处理的所有查询将被自动取消，并且关联的JavaScript onFailure回调将以错误代码-1执行。查询可以是持久性的，也可以是非持久性的。如果查询是持久查询，则在满足以下条件之一之前，回调将保持注册状态：A.使用| window.cefQueryCancel |在JavaScript中取消查询。功能。 B.使用Callback :: Failure函数以C ++代码取消查询。 C.与查询关联的上下文由于浏览器破坏，导航或渲染器进程终止而被释放。如果查询是非持久性的，则将在一次执行JavaScript回调后删除注册。如果由于执行Callback :: Failure之外的其他原因取消了查询，则将调用关联的Handler的OnQueryCanceled方法。一些可能的使用模式包括：一次性请求。使用非持久查询发送JavaScript请求。处理程序评估请求并返回响应。然后查询被丢弃。广播。使用永久查询注册为JavaScript广播接收器。处理程序会跟踪所有已注册的回调，并顺序执行它们以传递广播消息。订阅。使用永久查询注册为JavaScript订阅接收者。处理程序在第一个请求上启动订阅供稿，并在所有注册订户可用时将响应传递给所有注册订户。当不再有注册的JavaScript接收者时，处理程序将取消订阅供稿。消息路由是基于浏览器和上下文的。因此，可以通过限制将哪些浏览器或上下文实例传递到路由器来应用其他应用程序逻辑。如果选择使用此方法，请谨慎选择。为了使路由器正常工作，必须将传递到单个路由器回调中的任何浏览器或上下文实例传递到所有路由器回调中。除非您希望使用不同的JavaScript函数名称进行多个绑定，否则通常不需要多个渲染器侧路由器。在每个浏览器基础上实现不同行为时，让多个浏览器侧路由器具有不同的客户端提供的Handler实例会很有用。此实现对有效负载内容没有格式限制。应用程序可以选择交换任何内容，从简单格式的字符串到序列化的XML或JSON数据。用法示例1.定义路由器配置。您可以选择指定设置，例如JavaScript函数名称。浏览器和渲染器进程中的配置必须相同。如果在同一应用程序中使用多个路由器，请确保为每个路由器配置指定唯一的功能名称。 //示例配置对象显示默认值。 CefMessageRouterConfig config = new CefMessageRouterConfig（）; config.jsQueryFunction =“ cefQuery”; config.jsCancelFunction =“ cefQueryCancel”; 2.在浏览器进程中创建一个CefMessageRouter实例。 messageRouter_ = CefMessageRouter.create（config）; 3.注册一个或多个处理程序。 Handler实例必须在路由器之前失效，或者在删除之前从路由器中删除。 messageRouter_.addHandler（myHandler）; 4.将消息路由器添加到要处理JavaScript代码的所有CefClient实例。 myClient.addMessageRouter（messageRouter_）; 4.从JavaScript代码执行查询功能。 window.cefQuery（{request：'my_request'，persistent：false，onSuccess：function（response）{print（response）;}，onFailure：function（error_code，error_message）{}}）; 5.在CefMessageRouterHandler.onQuery实现中处理查询，并立即或异步执行适当的回调。 公开的boolean onQuery（CefBrowser浏览器，长查询ID，字符串请求，布尔持久性，CefQueryCallback回调）{if（request.indexOf（“ my_request”）== 0）{callback.success（“ my_response”）; 返回true； 返回false； //未处理。 } 6.注意，成功回调是在JavaScript中执行的。)