bcarrella/cef
1
0
Fork 0
mirror of https://bitbucket.org/chromiumembedded/cef synced 2025-06-05 21:39:12 +02:00
Code Issues Packages Projects Releases Wiki Activity

Add support for direct DevTools protocol messaging (fixes issue #2961).

Browse Source 
This change allows the client to directly send and receive DevTools
protocol messages (send method calls, and receive method results and
events) without requiring a DevTools front-end or remote-debugging
session.

This change includes additional supporting changes:
- Add a new CefRequestHandler::OnDocumentAvailableInMainFrame
  callback (see issue #1454).
- Add a CefParseJSON variant that accepts a UTF8-encoded buffer.
- Add a `--devtools-protocol-log-file=<path>` command-line flag for
  logging protocol messages sent to/from the DevTools front-end
  while it is displayed. This is useful for understanding existing
  DevTools protocol usage.
- Add a new "libcef_static_unittests" executable target to support
  light-weight unit tests of libcef_static internals (e.g. without
  requiring exposure via the CEF API). Files to be unittested are
  placed in the new "libcef_static_unittested" source_set which is
  then included by both the existing libcef_static library and the
  new unittests executable target.
- Linux: Remove use_bundled_fontconfig=false, which is no longer
  required and causes unittest build errors (see issue #2424).

This change also adds a cefclient demo for configuring offline mode
using the DevTools protocol (fixes issue #245). This is controlled
by the "Offline mode" context menu option and the `--offline`
command-line switch which will launch cefclient in offline mode. When
cefclient is offline all network requests will fail with
ERR_INTERNET_DISCONNECTED and navigator.onLine will return false when
called from JavaScript in any frame. This mode is per-browser so
newly created browser windows will have the default mode. Note that
configuring offline mode in this way will not update the Network tab
UI ("Throtting" option) in a displayed DevTools front-end instance.
This commit is contained in:
Marshall Greenblatt
2020-06-12 20:54:08 -04:00
parent a9aef28966
commit 39aed35644
46 changed files with 2824 additions and 146 deletions
Download Patch File Download Diff File Expand all files Collapse all files

69
include/capi/cef_browser_capi.h
View File

@@ -33,7 +33,7 @@
// by hand. See the translator.README.txt file in the tools directory for
// more information.
//
// $hash=ba4033eaf40a8ee24408b89b78496bf1381e7e6b$
// $hash=6cb00a0fa3631a46903abb3a783f315895511db2$
//
#ifndef CEF_INCLUDE_CAPI_CEF_BROWSER_CAPI_H_
@@ -41,10 +41,12 @@
#pragma once
#include "include/capi/cef_base_capi.h"
#include "include/capi/cef_devtools_message_observer_capi.h"
#include "include/capi/cef_drag_data_capi.h"
#include "include/capi/cef_frame_capi.h"
#include "include/capi/cef_image_capi.h"
#include "include/capi/cef_navigation_entry_capi.h"
#include "include/capi/cef_registration_capi.h"
#include "include/capi/cef_request_context_capi.h"
#ifdef __cplusplus
@@ -484,6 +486,71 @@ typedef struct _cef_browser_host_t {
///
int(CEF_CALLBACK* has_dev_tools)(struct _cef_browser_host_t* self);
///
// Send a function call message over the DevTools protocol. |message| must be
// a UTF8-encoded JSON dictionary that contains "id" (int), "function"
// (string) and "params" (dictionary, optional) values. See the DevTools
// protocol documentation at https://chromedevtools.github.io/devtools-
// protocol/ for details of supported functions and the expected "params"
// dictionary contents. |message| will be copied if necessary. This function
// will return true (1) if called on the UI thread and the message was
// successfully submitted for validation, otherwise false (0). Validation will
// be applied asynchronously and any messages that fail due to formatting
// errors or missing parameters may be discarded without notification. Prefer
// ExecuteDevToolsMethod if a more structured approach to message formatting
// is desired.
//
// Every valid function call will result in an asynchronous function result or
// error message that references the sent message "id". Event messages are
// received while notifications are enabled (for example, between function
// calls for "Page.enable" and "Page.disable"). All received messages will be
// delivered to the observer(s) registered with AddDevToolsMessageObserver.
// See cef_dev_tools_message_observer_t::OnDevToolsMessage documentation for
// details of received message contents.
//
// Usage of the SendDevToolsMessage, ExecuteDevToolsMethod and
// AddDevToolsMessageObserver functions does not require an active DevTools
// front-end or remote-debugging session. Other active DevTools sessions will
// continue to function independently. However, any modification of global
// browser state by one session may not be reflected in the UI of other
// sessions.
//
// Communication with the DevTools front-end (when displayed) can be logged
// for development purposes by passing the `--devtools-protocol-log-
// file=<path>` command-line flag.
///
int(CEF_CALLBACK* send_dev_tools_message)(struct _cef_browser_host_t* self,
const void* message,
size_t message_size);
///
// Execute a function call over the DevTools protocol. This is a more
// structured version of SendDevToolsMessage. |message_id| is an incremental
// number that uniquely identifies the message (pass 0 to have the next number
// assigned automatically based on previous values). |function| is the
// function name. |params| are the function parameters, which may be NULL. See
// the DevTools protocol documentation (linked above) for details of supported
// functions and the expected |params| dictionary contents. This function will
// return the assigned message ID if called on the UI thread and the message
// was successfully submitted for validation, otherwise 0. See the
// SendDevToolsMessage documentation for additional usage information.
///
int(CEF_CALLBACK* execute_dev_tools_method)(
struct _cef_browser_host_t* self,
int message_id,
const cef_string_t* method,
struct _cef_dictionary_value_t* params);
///
// Add an observer for DevTools protocol messages (function results and
// events). The observer will remain registered until the returned
// Registration object is destroyed. See the SendDevToolsMessage documentation
// for additional usage information.
///
struct _cef_registration_t*(CEF_CALLBACK* add_dev_tools_message_observer)(
struct _cef_browser_host_t* self,
struct _cef_dev_tools_message_observer_t* observer);
///
// Retrieve a snapshot of current navigation entries as values sent to the
// specified visitor. If |current_only| is true (1) only the current

147
include/capi/cef_devtools_message_observer_capi.h Normal file
View File

@@ -0,0 +1,147 @@
// Copyright (c) 2020 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.
//
// ---------------------------------------------------------------------------
//
// This file was generated by the CEF translator tool and should not edited
// by hand. See the translator.README.txt file in the tools directory for
// more information.
//
// $hash=86906c2e971fea7e479738f59bbf85d71ce31953$
//
#ifndef CEF_INCLUDE_CAPI_CEF_DEVTOOLS_MESSAGE_OBSERVER_CAPI_H_
#define CEF_INCLUDE_CAPI_CEF_DEVTOOLS_MESSAGE_OBSERVER_CAPI_H_
#pragma once
#include "include/capi/cef_base_capi.h"
#ifdef __cplusplus
extern "C" {
#endif
struct _cef_browser_t;
///
// Callback structure for cef_browser_host_t::AddDevToolsMessageObserver. The
// functions of this structure will be called on the browser process UI thread.
///
typedef struct _cef_dev_tools_message_observer_t {
///
// Base structure.
///
cef_base_ref_counted_t base;
///
// Method that will be called on receipt of a DevTools protocol message.
// |browser| is the originating browser instance. |message| is a UTF8-encoded
// JSON dictionary representing either a function result or an event.
// |message| is only valid for the scope of this callback and should be copied
// if necessary. Return true (1) if the message was handled or false (0) if
// the message should be further processed and passed to the
// OnDevToolsMethodResult or OnDevToolsEvent functions as appropriate.
//
// Method result dictionaries include an "id" (int) value that identifies the
// orginating function call sent from cef_browser_host_t::SendDevToolsMessage,
// and optionally either a "result" (dictionary) or "error" (dictionary)
// value. The "error" dictionary will contain "code" (int) and "message"
// (string) values. Event dictionaries include a "function" (string) value and
// optionally a "params" (dictionary) value. See the DevTools protocol
// documentation at https://chromedevtools.github.io/devtools-protocol/ for
// details of supported function calls and the expected "result" or "params"
// dictionary contents. JSON dictionaries can be parsed using the CefParseJSON
// function if desired, however be aware of performance considerations when
// parsing large messages (some of which may exceed 1MB in size).
///
int(CEF_CALLBACK* on_dev_tools_message)(
struct _cef_dev_tools_message_observer_t* self,
struct _cef_browser_t* browser,
const void* message,
size_t message_size);
///
// Method that will be called after attempted execution of a DevTools protocol
// function. |browser| is the originating browser instance. |message_id| is
// the "id" value that identifies the originating function call message. If
// the function succeeded |success| will be true (1) and |result| will be the
// UTF8-encoded JSON "result" dictionary value (which may be NULL). If the
// function failed |success| will be false (0) and |result| will be the
// UTF8-encoded JSON "error" dictionary value. |result| is only valid for the
// scope of this callback and should be copied if necessary. See the
// OnDevToolsMessage documentation for additional details on |result|
// contents.
///
void(CEF_CALLBACK* on_dev_tools_method_result)(
struct _cef_dev_tools_message_observer_t* self,
struct _cef_browser_t* browser,
int message_id,
int success,
const void* result,
size_t result_size);
///
// Method that will be called on receipt of a DevTools protocol event.
// |browser| is the originating browser instance. |function| is the "function"
// value. |params| is the UTF8-encoded JSON "params" dictionary value (which
// may be NULL). |params| is only valid for the scope of this callback and
// should be copied if necessary. See the OnDevToolsMessage documentation for
// additional details on |params| contents.
///
void(CEF_CALLBACK* on_dev_tools_event)(
struct _cef_dev_tools_message_observer_t* self,
struct _cef_browser_t* browser,
const cef_string_t* method,
const void* params,
size_t params_size);
///
// Method that will be called when the DevTools agent has attached. |browser|
// is the originating browser instance. This will generally occur in response
// to the first message sent while the agent is detached.
///
void(CEF_CALLBACK* on_dev_tools_agent_attached)(
struct _cef_dev_tools_message_observer_t* self,
struct _cef_browser_t* browser);
///
// Method that will be called when the DevTools agent has detached. |browser|
// is the originating browser instance. Any function results that were pending
// before the agent became detached will not be delivered, and any active
// event subscriptions will be canceled.
///
void(CEF_CALLBACK* on_dev_tools_agent_detached)(
struct _cef_dev_tools_message_observer_t* self,
struct _cef_browser_t* browser);
} cef_dev_tools_message_observer_t;
#ifdef __cplusplus
}
#endif
#endif // CEF_INCLUDE_CAPI_CEF_DEVTOOLS_MESSAGE_OBSERVER_CAPI_H_

12
include/capi/cef_parser_capi.h
View File

@@ -33,7 +33,7 @@
// by hand. See the translator.README.txt file in the tools directory for
// more information.
//
// $hash=3bc4225f43428d8a3a24dcac1830dafac18b0caf$
// $hash=14cf03e02d8ca3416e65f756470afd8185c7bc78$
//
#ifndef CEF_INCLUDE_CAPI_CEF_PARSER_CAPI_H_
@@ -140,6 +140,16 @@ CEF_EXPORT struct _cef_value_t* cef_parse_json(
const cef_string_t* json_string,
cef_json_parser_options_t options);
///
// Parses the specified UTF8-encoded |json| buffer of size |json_size| and
// returns a dictionary or list representation. If JSON parsing fails this
// function returns NULL.
///
CEF_EXPORT struct _cef_value_t* cef_parse_json_buffer(
const void* json,
size_t json_size,
cef_json_parser_options_t options);
///
// Parses the specified |json_string| and returns a dictionary or list
// representation. If JSON parsing fails this function returns NULL and

10
include/capi/cef_request_handler_capi.h
View File

@@ -33,7 +33,7 @@
// by hand. See the translator.README.txt file in the tools directory for
// more information.
//
// $hash=a28219cc8c1cb53faacaf236374c3cf2c0c45bef$
// $hash=0167eb1abe614bd6391d273a8085fa3e53e7c217$
//
#ifndef CEF_INCLUDE_CAPI_CEF_REQUEST_HANDLER_CAPI_H_
@@ -253,6 +253,14 @@ typedef struct _cef_request_handler_t {
struct _cef_request_handler_t* self,
struct _cef_browser_t* browser,
cef_termination_status_t status);
///
// Called on the browser process UI thread when the window.document object of
// the main frame has been created.
///
void(CEF_CALLBACK* on_document_available_in_main_frame)(
struct _cef_request_handler_t* self,
struct _cef_browser_t* browser);
} cef_request_handler_t;
#ifdef __cplusplus