176 lines
9.0 KiB
C++
176 lines
9.0 KiB
C++
// Copyright (c) 2021 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_FRAME_HANDLER_H_
|
|
#define CEF_INCLUDE_CEF_FRAME_HANDLER_H_
|
|
#pragma once
|
|
|
|
#include "include/cef_base.h"
|
|
#include "include/cef_browser.h"
|
|
#include "include/cef_frame.h"
|
|
|
|
///
|
|
// Implement this interface to handle events related to CefFrame life span. The
|
|
// order of callbacks is:
|
|
//
|
|
// (1) During initial CefBrowserHost creation and navigation of the main frame:
|
|
// - CefFrameHandler::OnFrameCreated => The initial main frame object has been
|
|
// created. Any commands will be queued until the frame is attached.
|
|
// - CefFrameHandler::OnMainFrameChanged => The initial main frame object has
|
|
// been assigned to the browser.
|
|
// - CefLifeSpanHandler::OnAfterCreated => The browser is now valid and can be
|
|
// used.
|
|
// - CefFrameHandler::OnFrameAttached => The initial main frame object is now
|
|
// connected to its peer in the renderer process. Commands can be routed.
|
|
//
|
|
// (2) During further CefBrowserHost navigation/loading of the main frame and/or
|
|
// sub-frames:
|
|
// - CefFrameHandler::OnFrameCreated => A new main frame or sub-frame object has
|
|
// been created. Any commands will be queued until the frame is attached.
|
|
// - CefFrameHandler::OnFrameAttached => A new main frame or sub-frame object is
|
|
// now connected to its peer in the renderer process. Commands can be routed.
|
|
// - CefFrameHandler::OnFrameDetached => An existing main frame or sub-frame
|
|
// object has lost its connection to the renderer process. If multiple objects
|
|
// are detached at the same time then notifications will be sent for any
|
|
// sub-frame objects before the main frame object. Commands can no longer be
|
|
// routed and will be discarded.
|
|
// - CefFrameHandler::OnMainFrameChanged => A new main frame object has been
|
|
// assigned to the browser. This will only occur with cross-origin navigation
|
|
// or re-navigation after renderer process termination (due to crashes, etc).
|
|
//
|
|
// (3) During final CefBrowserHost destruction of the main frame:
|
|
// - CefFrameHandler::OnFrameDetached => Any sub-frame objects have lost their
|
|
// connection to the renderer process. Commands can no longer be routed and
|
|
// will be discarded.
|
|
// - CefLifeSpanHandler::OnBeforeClose => The browser has been destroyed.
|
|
// - CefFrameHandler::OnFrameDetached => The main frame object have lost its
|
|
// connection to the renderer process. Notifications will be sent for any
|
|
// sub-frame objects before the main frame object. Commands can no longer be
|
|
// routed and will be discarded.
|
|
// - CefFrameHandler::OnMainFrameChanged => The final main frame object has been
|
|
// removed from the browser.
|
|
//
|
|
// Cross-origin navigation and/or loading receives special handling.
|
|
//
|
|
// When the main frame navigates to a different origin the OnMainFrameChanged
|
|
// callback (2) will be executed with the old and new main frame objects.
|
|
//
|
|
// When a new sub-frame is loaded in, or an existing sub-frame is navigated to,
|
|
// a different origin from the parent frame, a temporary sub-frame object will
|
|
// first be created in the parent's renderer process. That temporary sub-frame
|
|
// will then be discarded after the real cross-origin sub-frame is created in
|
|
// the new/target renderer process. The client will receive cross-origin
|
|
// navigation callbacks (2) for the transition from the temporary sub-frame to
|
|
// the real sub-frame. The temporary sub-frame will not recieve or execute
|
|
// commands during this transitional period (any sent commands will be
|
|
// discarded).
|
|
//
|
|
// When a new popup browser is created in a different origin from the parent
|
|
// browser, a temporary main frame object for the popup will first be created in
|
|
// the parent's renderer process. That temporary main frame will then be
|
|
// discarded after the real cross-origin main frame is created in the new/target
|
|
// renderer process. The client will recieve creation and initial navigation
|
|
// callbacks (1) for the temporary main frame, followed by cross-origin
|
|
// navigation callbacks (2) for the transition from the temporary main frame to
|
|
// the real main frame. The temporary main frame may receive and execute
|
|
// commands during this transitional period (any sent commands may be executed,
|
|
// but the behavior is potentially undesirable since they execute in the parent
|
|
// browser's renderer process and not the new/target renderer process).
|
|
//
|
|
// Callbacks will not be executed for placeholders that may be created during
|
|
// pre-commit navigation for sub-frames that do not yet exist in the renderer
|
|
// process. Placeholders will have CefFrame::GetIdentifier() == -4.
|
|
//
|
|
// The methods of this class will be called on the UI thread unless otherwise
|
|
// indicated.
|
|
///
|
|
/*--cef(source=client)--*/
|
|
class CefFrameHandler : public virtual CefBaseRefCounted {
|
|
public:
|
|
///
|
|
// Called when a new frame is created. This will be the first notification
|
|
// that references |frame|. Any commands that require transport to the
|
|
// associated renderer process (LoadRequest, SendProcessMessage, GetSource,
|
|
// etc.) will be queued until OnFrameAttached is called for |frame|.
|
|
///
|
|
/*--cef()--*/
|
|
virtual void OnFrameCreated(CefRefPtr<CefBrowser> browser,
|
|
CefRefPtr<CefFrame> frame) {}
|
|
|
|
///
|
|
// Called when a frame can begin routing commands to/from the associated
|
|
// renderer process. |reattached| will be true if the frame was re-attached
|
|
// after exiting the BackForwardCache. Any commands that were queued have now
|
|
// been dispatched.
|
|
///
|
|
/*--cef()--*/
|
|
virtual void OnFrameAttached(CefRefPtr<CefBrowser> browser,
|
|
CefRefPtr<CefFrame> frame,
|
|
bool reattached) {}
|
|
|
|
///
|
|
// Called when a frame loses its connection to the renderer process and will
|
|
// be destroyed. Any pending or future commands will be discarded and
|
|
// CefFrame::IsValid() will now return false for |frame|. If called after
|
|
// CefLifeSpanHandler::OnBeforeClose() during browser destruction then
|
|
// CefBrowser::IsValid() will return false for |browser|.
|
|
///
|
|
/*--cef()--*/
|
|
virtual void OnFrameDetached(CefRefPtr<CefBrowser> browser,
|
|
CefRefPtr<CefFrame> frame) {}
|
|
|
|
///
|
|
// Called when the main frame changes due to (a) initial browser creation, (b)
|
|
// final browser destruction, (c) cross-origin navigation or (d) re-navigation
|
|
// after renderer process termination (due to crashes, etc). |old_frame| will
|
|
// be NULL and |new_frame| will be non-NULL when a main frame is assigned to
|
|
// |browser| for the first time. |old_frame| will be non-NULL and |new_frame|
|
|
// will be NULL and when a main frame is removed from |browser| for the last
|
|
// time. Both |old_frame| and |new_frame| will be non-NULL for cross-origin
|
|
// navigations or re-navigation after renderer process termination. This
|
|
// method will be called after OnFrameCreated() for |new_frame| and/or after
|
|
// OnFrameDetached() for |old_frame|. If called after
|
|
// CefLifeSpanHandler::OnBeforeClose() during browser destruction then
|
|
// CefBrowser::IsValid() will return false for |browser|.
|
|
///
|
|
/*--cef(optional_param=old_frame,optional_param=new_frame)--*/
|
|
virtual void OnMainFrameChanged(CefRefPtr<CefBrowser> browser,
|
|
CefRefPtr<CefFrame> old_frame,
|
|
CefRefPtr<CefFrame> new_frame) {}
|
|
};
|
|
|
|
#endif // CEF_INCLUDE_CEF_FRAME_HANDLER_H_
|