cef/include/cef_devtools_message_observer.h

// 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_