forked from chromiumembedded/cef
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathcef_frame_handler.h
177 lines (170 loc) · 9.15 KB
/
cef_frame_handler.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
// 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_