cef/include/cef_devtools_message_observ...

131 lines
6.2 KiB
C
Raw Normal View History

Add support for direct DevTools protocol messaging (fixes issue #2961). 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.
2020-06-13 02:54:08 +02:00
// 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.
//
// ---------------------------------------------------------------------------
//
// The contents of this file must follow a specific format in order to
// support the CEF translator tool. See the translator.README.txt file in the
// tools directory for more information.
//
#ifndef CEF_INCLUDE_CEF_DEVTOOLS_MESSAGE_OBSERVER_H_
#define CEF_INCLUDE_CEF_DEVTOOLS_MESSAGE_OBSERVER_H_
#pragma once
#include "include/cef_base.h"
class CefBrowser;
///
// Callback interface for CefBrowserHost::AddDevToolsMessageObserver. The
// methods of this class will be called on the browser process UI thread.
///
/*--cef(source=client)--*/
class CefDevToolsMessageObserver : public virtual CefBaseRefCounted {
public:
///
// 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 method result or an event. |message|
// is only valid for the scope of this callback and should be copied if
// necessary. Return true if the message was handled or false if the message
// should be further processed and passed to the OnDevToolsMethodResult or
// OnDevToolsEvent methods as appropriate.
//
// Method result dictionaries include an "id" (int) value that identifies the
// orginating method call sent from CefBrowserHost::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 "method" (string) value and optionally
// a "params" (dictionary) value. See the DevTools protocol documentation at
// https://chromedevtools.github.io/devtools-protocol/ for details of
// supported method 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).
///
/*--cef()--*/
virtual bool OnDevToolsMessage(CefRefPtr<CefBrowser> browser,
const void* message,
size_t message_size) {
return false;
}
///
// Method that will be called after attempted execution of a DevTools protocol
// method. |browser| is the originating browser instance. |message_id| is the
// "id" value that identifies the originating method call message. If the
// method succeeded |success| will be true and |result| will be the
// UTF8-encoded JSON "result" dictionary value (which may be empty). If the
// method failed |success| will be false 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.
///
/*--cef(optional_param=result)--*/
virtual void OnDevToolsMethodResult(CefRefPtr<CefBrowser> browser,
int message_id,
bool 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. |method| is the "method"
// value. |params| is the UTF8-encoded JSON "params" dictionary value (which
// may be empty). |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.
///
/*--cef(optional_param=params)--*/
virtual void OnDevToolsEvent(CefRefPtr<CefBrowser> browser,
const CefString& 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.
///
/*--cef()--*/
virtual void OnDevToolsAgentAttached(CefRefPtr<CefBrowser> browser) {}
///
// Method that will be called when the DevTools agent has detached. |browser|
// is the originating browser instance. Any method results that were pending
// before the agent became detached will not be delivered, and any active
// event subscriptions will be canceled.
///
/*--cef()--*/
virtual void OnDevToolsAgentDetached(CefRefPtr<CefBrowser> browser) {}
};
#endif // CEF_INCLUDE_CEF_DEVTOOLS_MESSAGE_OBSERVER_H_