1 // Copyright (c) 2021 Marshall A. Greenblatt. All rights reserved. 2 // 3 // Redistribution and use in source and binary forms, with or without 4 // modification, are permitted provided that the following conditions are 5 // met: 6 // 7 // * Redistributions of source code must retain the above copyright 8 // notice, this list of conditions and the following disclaimer. 9 // * Redistributions in binary form must reproduce the above 10 // copyright notice, this list of conditions and the following disclaimer 11 // in the documentation and/or other materials provided with the 12 // distribution. 13 // * Neither the name of Google Inc. nor the name Chromium Embedded 14 // Framework nor the names of its contributors may be used to endorse 15 // or promote products derived from this software without specific prior 16 // written permission. 17 // 18 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 19 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 20 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 21 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 22 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 23 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 24 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 25 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 26 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 27 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 28 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 29 // 30 // --------------------------------------------------------------------------- 31 // 32 // The contents of this file must follow a specific format in order to 33 // support the CEF translator tool. See the translator.README.txt file in the 34 // tools directory for more information. 35 // 36 37 #ifndef CEF_INCLUDE_CEF_FRAME_HANDLER_H_ 38 #define CEF_INCLUDE_CEF_FRAME_HANDLER_H_ 39 #pragma once 40 41 #include "include/cef_base.h" 42 #include "include/cef_browser.h" 43 #include "include/cef_frame.h" 44 45 /// 46 // Implement this interface to handle events related to CefFrame life span. The 47 // order of callbacks is: 48 // 49 // (1) During initial CefBrowserHost creation and navigation of the main frame: 50 // - CefFrameHandler::OnFrameCreated => The initial main frame object has been 51 // created. Any commands will be queued until the frame is attached. 52 // - CefFrameHandler::OnMainFrameChanged => The initial main frame object has 53 // been assigned to the browser. 54 // - CefLifeSpanHandler::OnAfterCreated => The browser is now valid and can be 55 // used. 56 // - CefFrameHandler::OnFrameAttached => The initial main frame object is now 57 // connected to its peer in the renderer process. Commands can be routed. 58 // 59 // (2) During further CefBrowserHost navigation/loading of the main frame and/or 60 // sub-frames: 61 // - CefFrameHandler::OnFrameCreated => A new main frame or sub-frame object has 62 // been created. Any commands will be queued until the frame is attached. 63 // - CefFrameHandler::OnFrameAttached => A new main frame or sub-frame object is 64 // now connected to its peer in the renderer process. Commands can be routed. 65 // - CefFrameHandler::OnFrameDetached => An existing main frame or sub-frame 66 // object has lost its connection to the renderer process. If multiple objects 67 // are detached at the same time then notifications will be sent for any 68 // sub-frame objects before the main frame object. Commands can no longer be 69 // routed and will be discarded. 70 // - CefFrameHandler::OnMainFrameChanged => A new main frame object has been 71 // assigned to the browser. This will only occur with cross-origin navigation 72 // or re-navigation after renderer process termination (due to crashes, etc). 73 // 74 // (3) During final CefBrowserHost destruction of the main frame: 75 // - CefFrameHandler::OnFrameDetached => Any sub-frame objects have lost their 76 // connection to the renderer process. Commands can no longer be routed and 77 // will be discarded. 78 // - CefLifeSpanHandler::OnBeforeClose => The browser has been destroyed. 79 // - CefFrameHandler::OnFrameDetached => The main frame object have lost its 80 // connection to the renderer process. Notifications will be sent for any 81 // sub-frame objects before the main frame object. Commands can no longer be 82 // routed and will be discarded. 83 // - CefFrameHandler::OnMainFrameChanged => The final main frame object has been 84 // removed from the browser. 85 // 86 // Cross-origin navigation and/or loading receives special handling. 87 // 88 // When the main frame navigates to a different origin the OnMainFrameChanged 89 // callback (2) will be executed with the old and new main frame objects. 90 // 91 // When a new sub-frame is loaded in, or an existing sub-frame is navigated to, 92 // a different origin from the parent frame, a temporary sub-frame object will 93 // first be created in the parent's renderer process. That temporary sub-frame 94 // will then be discarded after the real cross-origin sub-frame is created in 95 // the new/target renderer process. The client will receive cross-origin 96 // navigation callbacks (2) for the transition from the temporary sub-frame to 97 // the real sub-frame. The temporary sub-frame will not recieve or execute 98 // commands during this transitional period (any sent commands will be 99 // discarded). 100 // 101 // When a new popup browser is created in a different origin from the parent 102 // browser, a temporary main frame object for the popup will first be created in 103 // the parent's renderer process. That temporary main frame will then be 104 // discarded after the real cross-origin main frame is created in the new/target 105 // renderer process. The client will recieve creation and initial navigation 106 // callbacks (1) for the temporary main frame, followed by cross-origin 107 // navigation callbacks (2) for the transition from the temporary main frame to 108 // the real main frame. The temporary main frame may receive and execute 109 // commands during this transitional period (any sent commands may be executed, 110 // but the behavior is potentially undesirable since they execute in the parent 111 // browser's renderer process and not the new/target renderer process). 112 // 113 // Callbacks will not be executed for placeholders that may be created during 114 // pre-commit navigation for sub-frames that do not yet exist in the renderer 115 // process. Placeholders will have CefFrame::GetIdentifier() == -4. 116 // 117 // The methods of this class will be called on the UI thread unless otherwise 118 // indicated. 119 /// 120 /*--cef(source=client)--*/ 121 class CefFrameHandler : public virtual CefBaseRefCounted { 122 public: 123 /// 124 // Called when a new frame is created. This will be the first notification 125 // that references |frame|. Any commands that require transport to the 126 // associated renderer process (LoadRequest, SendProcessMessage, GetSource, 127 // etc.) will be queued until OnFrameAttached is called for |frame|. 128 /// 129 /*--cef()--*/ OnFrameCreated(CefRefPtr<CefBrowser> browser,CefRefPtr<CefFrame> frame)130 virtual void OnFrameCreated(CefRefPtr<CefBrowser> browser, 131 CefRefPtr<CefFrame> frame) {} 132 133 /// 134 // Called when a frame can begin routing commands to/from the associated 135 // renderer process. |reattached| will be true if the frame was re-attached 136 // after exiting the BackForwardCache. Any commands that were queued have now 137 // been dispatched. 138 /// 139 /*--cef()--*/ OnFrameAttached(CefRefPtr<CefBrowser> browser,CefRefPtr<CefFrame> frame,bool reattached)140 virtual void OnFrameAttached(CefRefPtr<CefBrowser> browser, 141 CefRefPtr<CefFrame> frame, 142 bool reattached) {} 143 144 /// 145 // Called when a frame loses its connection to the renderer process and will 146 // be destroyed. Any pending or future commands will be discarded and 147 // CefFrame::IsValid() will now return false for |frame|. If called after 148 // CefLifeSpanHandler::OnBeforeClose() during browser destruction then 149 // CefBrowser::IsValid() will return false for |browser|. 150 /// 151 /*--cef()--*/ OnFrameDetached(CefRefPtr<CefBrowser> browser,CefRefPtr<CefFrame> frame)152 virtual void OnFrameDetached(CefRefPtr<CefBrowser> browser, 153 CefRefPtr<CefFrame> frame) {} 154 155 /// 156 // Called when the main frame changes due to (a) initial browser creation, (b) 157 // final browser destruction, (c) cross-origin navigation or (d) re-navigation 158 // after renderer process termination (due to crashes, etc). |old_frame| will 159 // be NULL and |new_frame| will be non-NULL when a main frame is assigned to 160 // |browser| for the first time. |old_frame| will be non-NULL and |new_frame| 161 // will be NULL and when a main frame is removed from |browser| for the last 162 // time. Both |old_frame| and |new_frame| will be non-NULL for cross-origin 163 // navigations or re-navigation after renderer process termination. This 164 // method will be called after OnFrameCreated() for |new_frame| and/or after 165 // OnFrameDetached() for |old_frame|. If called after 166 // CefLifeSpanHandler::OnBeforeClose() during browser destruction then 167 // CefBrowser::IsValid() will return false for |browser|. 168 /// 169 /*--cef(optional_param=old_frame,optional_param=new_frame)--*/ OnMainFrameChanged(CefRefPtr<CefBrowser> browser,CefRefPtr<CefFrame> old_frame,CefRefPtr<CefFrame> new_frame)170 virtual void OnMainFrameChanged(CefRefPtr<CefBrowser> browser, 171 CefRefPtr<CefFrame> old_frame, 172 CefRefPtr<CefFrame> new_frame) {} 173 }; 174 175 #endif // CEF_INCLUDE_CEF_FRAME_HANDLER_H_ 176