1 // Copyright (c) 2022 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 // This file was generated by the CEF translator tool and should not edited 33 // by hand. See the translator.README.txt file in the tools directory for 34 // more information. 35 // 36 // $hash=8f791b2d1d5bea27f9e6ca5e0db731a0a76d181c$ 37 // 38 39 #ifndef CEF_INCLUDE_CAPI_CEF_FRAME_HANDLER_CAPI_H_ 40 #define CEF_INCLUDE_CAPI_CEF_FRAME_HANDLER_CAPI_H_ 41 #pragma once 42 43 #include "include/capi/cef_base_capi.h" 44 #include "include/capi/cef_browser_capi.h" 45 #include "include/capi/cef_frame_capi.h" 46 47 #ifdef __cplusplus 48 extern "C" { 49 #endif 50 51 /// 52 // Implement this structure to handle events related to cef_frame_t life span. 53 // The order of callbacks is: 54 // 55 // (1) During initial cef_browser_host_t creation and navigation of the main 56 // frame: - cef_frame_handler_t::OnFrameCreated => The initial main frame object 57 // has been 58 // created. Any commands will be queued until the frame is attached. 59 // - cef_frame_handler_t::OnMainFrameChanged => The initial main frame object 60 // has 61 // been assigned to the browser. 62 // - cef_life_span_handler_t::OnAfterCreated => The browser is now valid and can 63 // be 64 // used. 65 // - cef_frame_handler_t::OnFrameAttached => The initial main frame object is 66 // now 67 // connected to its peer in the renderer process. Commands can be routed. 68 // 69 // (2) During further cef_browser_host_t navigation/loading of the main frame 70 // and/or sub-frames: - cef_frame_handler_t::OnFrameCreated => A new main frame 71 // or sub-frame object has 72 // been created. Any commands will be queued until the frame is attached. 73 // - cef_frame_handler_t::OnFrameAttached => A new main frame or sub-frame 74 // object is 75 // now connected to its peer in the renderer process. Commands can be routed. 76 // - cef_frame_handler_t::OnFrameDetached => An existing main frame or sub-frame 77 // object has lost its connection to the renderer process. If multiple objects 78 // are detached at the same time then notifications will be sent for any 79 // sub-frame objects before the main frame object. Commands can no longer be 80 // routed and will be discarded. 81 // - cef_frame_handler_t::OnMainFrameChanged => A new main frame object has been 82 // assigned to the browser. This will only occur with cross-origin navigation 83 // or re-navigation after renderer process termination (due to crashes, etc). 84 // 85 // (3) During final cef_browser_host_t destruction of the main frame: - 86 // cef_frame_handler_t::OnFrameDetached => Any sub-frame objects have lost their 87 // connection to the renderer process. Commands can no longer be routed and 88 // will be discarded. 89 // - cef_life_span_handler_t::OnBeforeClose => The browser has been destroyed. - 90 // cef_frame_handler_t::OnFrameDetached => The main frame object have lost its 91 // connection to the renderer process. Notifications will be sent for any 92 // sub-frame objects before the main frame object. Commands can no longer be 93 // routed and will be discarded. 94 // - cef_frame_handler_t::OnMainFrameChanged => The final main frame object has 95 // been 96 // removed from the browser. 97 // 98 // Cross-origin navigation and/or loading receives special handling. 99 // 100 // When the main frame navigates to a different origin the OnMainFrameChanged 101 // callback (2) will be executed with the old and new main frame objects. 102 // 103 // When a new sub-frame is loaded in, or an existing sub-frame is navigated to, 104 // a different origin from the parent frame, a temporary sub-frame object will 105 // first be created in the parent's renderer process. That temporary sub-frame 106 // will then be discarded after the real cross-origin sub-frame is created in 107 // the new/target renderer process. The client will receive cross-origin 108 // navigation callbacks (2) for the transition from the temporary sub-frame to 109 // the real sub-frame. The temporary sub-frame will not recieve or execute 110 // commands during this transitional period (any sent commands will be 111 // discarded). 112 // 113 // When a new popup browser is created in a different origin from the parent 114 // browser, a temporary main frame object for the popup will first be created in 115 // the parent's renderer process. That temporary main frame will then be 116 // discarded after the real cross-origin main frame is created in the new/target 117 // renderer process. The client will recieve creation and initial navigation 118 // callbacks (1) for the temporary main frame, followed by cross-origin 119 // navigation callbacks (2) for the transition from the temporary main frame to 120 // the real main frame. The temporary main frame may receive and execute 121 // commands during this transitional period (any sent commands may be executed, 122 // but the behavior is potentially undesirable since they execute in the parent 123 // browser's renderer process and not the new/target renderer process). 124 // 125 // Callbacks will not be executed for placeholders that may be created during 126 // pre-commit navigation for sub-frames that do not yet exist in the renderer 127 // process. Placeholders will have cef_frame_t::get_identifier() == -4. 128 // 129 // The functions of this structure will be called on the UI thread unless 130 // otherwise indicated. 131 /// 132 typedef struct _cef_frame_handler_t { 133 /// 134 // Base structure. 135 /// 136 cef_base_ref_counted_t base; 137 138 /// 139 // Called when a new frame is created. This will be the first notification 140 // that references |frame|. Any commands that require transport to the 141 // associated renderer process (LoadRequest, SendProcessMessage, GetSource, 142 // etc.) will be queued until OnFrameAttached is called for |frame|. 143 /// 144 void(CEF_CALLBACK* on_frame_created)(struct _cef_frame_handler_t* self, 145 struct _cef_browser_t* browser, 146 struct _cef_frame_t* frame); 147 148 /// 149 // Called when a frame can begin routing commands to/from the associated 150 // renderer process. |reattached| will be true (1) if the frame was re- 151 // attached after exiting the BackForwardCache. Any commands that were queued 152 // have now been dispatched. 153 /// 154 void(CEF_CALLBACK* on_frame_attached)(struct _cef_frame_handler_t* self, 155 struct _cef_browser_t* browser, 156 struct _cef_frame_t* frame, 157 int reattached); 158 159 /// 160 // Called when a frame loses its connection to the renderer process and will 161 // be destroyed. Any pending or future commands will be discarded and 162 // cef_frame_t::is_valid() will now return false (0) for |frame|. If called 163 // after cef_life_span_handler_t::on_before_close() during browser destruction 164 // then cef_browser_t::is_valid() will return false (0) for |browser|. 165 /// 166 void(CEF_CALLBACK* on_frame_detached)(struct _cef_frame_handler_t* self, 167 struct _cef_browser_t* browser, 168 struct _cef_frame_t* frame); 169 170 /// 171 // Called when the main frame changes due to (a) initial browser creation, (b) 172 // final browser destruction, (c) cross-origin navigation or (d) re-navigation 173 // after renderer process termination (due to crashes, etc). |old_frame| will 174 // be NULL and |new_frame| will be non-NULL when a main frame is assigned to 175 // |browser| for the first time. |old_frame| will be non-NULL and |new_frame| 176 // will be NULL and when a main frame is removed from |browser| for the last 177 // time. Both |old_frame| and |new_frame| will be non-NULL for cross-origin 178 // navigations or re-navigation after renderer process termination. This 179 // function will be called after on_frame_created() for |new_frame| and/or 180 // after on_frame_detached() for |old_frame|. If called after 181 // cef_life_span_handler_t::on_before_close() during browser destruction then 182 // cef_browser_t::is_valid() will return false (0) for |browser|. 183 /// 184 void(CEF_CALLBACK* on_main_frame_changed)(struct _cef_frame_handler_t* self, 185 struct _cef_browser_t* browser, 186 struct _cef_frame_t* old_frame, 187 struct _cef_frame_t* new_frame); 188 } cef_frame_handler_t; 189 190 #ifdef __cplusplus 191 } 192 #endif 193 194 #endif // CEF_INCLUDE_CAPI_CEF_FRAME_HANDLER_CAPI_H_ 195