1 // Copyright (c) 2012 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_H_ 38 #define CEF_INCLUDE_CEF_FRAME_H_ 39 #pragma once 40 41 #include "include/cef_base.h" 42 #include "include/cef_dom.h" 43 #include "include/cef_process_message.h" 44 #include "include/cef_request.h" 45 #include "include/cef_stream.h" 46 #include "include/cef_string_visitor.h" 47 48 class CefBrowser; 49 class CefURLRequest; 50 class CefURLRequestClient; 51 class CefV8Context; 52 53 /// 54 // Class used to represent a frame in the browser window. When used in the 55 // browser process the methods of this class may be called on any thread unless 56 // otherwise indicated in the comments. When used in the render process the 57 // methods of this class may only be called on the main thread. 58 /// 59 /*--cef(source=library)--*/ 60 class CefFrame : public virtual CefBaseRefCounted { 61 public: 62 /// 63 // True if this object is currently attached to a valid frame. 64 /// 65 /*--cef()--*/ 66 virtual bool IsValid() = 0; 67 68 /// 69 // Execute undo in this frame. 70 /// 71 /*--cef()--*/ 72 virtual void Undo() = 0; 73 74 /// 75 // Execute redo in this frame. 76 /// 77 /*--cef()--*/ 78 virtual void Redo() = 0; 79 80 /// 81 // Execute cut in this frame. 82 /// 83 /*--cef()--*/ 84 virtual void Cut() = 0; 85 86 /// 87 // Execute copy in this frame. 88 /// 89 /*--cef()--*/ 90 virtual void Copy() = 0; 91 92 /// 93 // Execute paste in this frame. 94 /// 95 /*--cef()--*/ 96 virtual void Paste() = 0; 97 98 /// 99 // Execute delete in this frame. 100 /// 101 /*--cef(capi_name=del)--*/ 102 virtual void Delete() = 0; 103 104 /// 105 // Execute select all in this frame. 106 /// 107 /*--cef()--*/ 108 virtual void SelectAll() = 0; 109 110 /// 111 // Save this frame's HTML source to a temporary file and open it in the 112 // default text viewing application. This method can only be called from the 113 // browser process. 114 /// 115 /*--cef()--*/ 116 virtual void ViewSource() = 0; 117 118 /// 119 // Retrieve this frame's HTML source as a string sent to the specified 120 // visitor. 121 /// 122 /*--cef()--*/ 123 virtual void GetSource(CefRefPtr<CefStringVisitor> visitor) = 0; 124 125 /// 126 // Retrieve this frame's display text as a string sent to the specified 127 // visitor. 128 /// 129 /*--cef()--*/ 130 virtual void GetText(CefRefPtr<CefStringVisitor> visitor) = 0; 131 132 /// 133 // Load the request represented by the |request| object. 134 // 135 // WARNING: This method will fail with "bad IPC message" reason 136 // INVALID_INITIATOR_ORIGIN (213) unless you first navigate to the 137 // request origin using some other mechanism (LoadURL, link click, etc). 138 /// 139 /*--cef()--*/ 140 virtual void LoadRequest(CefRefPtr<CefRequest> request) = 0; 141 142 /// 143 // Load the specified |url|. 144 /// 145 /*--cef()--*/ 146 virtual void LoadURL(const CefString& url) = 0; 147 148 /// 149 // Execute a string of JavaScript code in this frame. The |script_url| 150 // parameter is the URL where the script in question can be found, if any. 151 // The renderer may request this URL to show the developer the source of the 152 // error. The |start_line| parameter is the base line number to use for error 153 // reporting. 154 /// 155 /*--cef(optional_param=script_url)--*/ 156 virtual void ExecuteJavaScript(const CefString& code, 157 const CefString& script_url, 158 int start_line) = 0; 159 160 /// 161 // Returns true if this is the main (top-level) frame. 162 /// 163 /*--cef()--*/ 164 virtual bool IsMain() = 0; 165 166 /// 167 // Returns true if this is the focused frame. 168 /// 169 /*--cef()--*/ 170 virtual bool IsFocused() = 0; 171 172 /// 173 // Returns the name for this frame. If the frame has an assigned name (for 174 // example, set via the iframe "name" attribute) then that value will be 175 // returned. Otherwise a unique name will be constructed based on the frame 176 // parent hierarchy. The main (top-level) frame will always have an empty name 177 // value. 178 /// 179 /*--cef()--*/ 180 virtual CefString GetName() = 0; 181 182 /// 183 // Returns the globally unique identifier for this frame or < 0 if the 184 // underlying frame does not yet exist. 185 /// 186 /*--cef()--*/ 187 virtual int64 GetIdentifier() = 0; 188 189 /// 190 // Returns the parent of this frame or NULL if this is the main (top-level) 191 // frame. 192 /// 193 /*--cef()--*/ 194 virtual CefRefPtr<CefFrame> GetParent() = 0; 195 196 /// 197 // Returns the URL currently loaded in this frame. 198 /// 199 /*--cef()--*/ 200 virtual CefString GetURL() = 0; 201 202 /// 203 // Returns the browser that this frame belongs to. 204 /// 205 /*--cef()--*/ 206 virtual CefRefPtr<CefBrowser> GetBrowser() = 0; 207 208 /// 209 // Get the V8 context associated with the frame. This method can only be 210 // called from the render process. 211 /// 212 /*--cef()--*/ 213 virtual CefRefPtr<CefV8Context> GetV8Context() = 0; 214 215 /// 216 // Visit the DOM document. This method can only be called from the render 217 // process. 218 /// 219 /*--cef()--*/ 220 virtual void VisitDOM(CefRefPtr<CefDOMVisitor> visitor) = 0; 221 222 /// 223 // Create a new URL request that will be treated as originating from this 224 // frame and the associated browser. This request may be intercepted by the 225 // client via CefResourceRequestHandler or CefSchemeHandlerFactory. Use 226 // CefURLRequest::Create instead if you do not want the request to have this 227 // association, in which case it may be handled differently (see documentation 228 // on that method). Requests may originate from both the browser process and 229 // the render process. 230 // 231 // For requests originating from the browser process: 232 // - POST data may only contain a single element of type PDE_TYPE_FILE or 233 // PDE_TYPE_BYTES. 234 // For requests originating from the render process: 235 // - POST data may only contain a single element of type PDE_TYPE_BYTES. 236 // - If the response contains Content-Disposition or Mime-Type header values 237 // that would not normally be rendered then the response may receive 238 // special handling inside the browser (for example, via the file download 239 // code path instead of the URL request code path). 240 // 241 // The |request| object will be marked as read-only after calling this method. 242 /// 243 /*--cef()--*/ 244 virtual CefRefPtr<CefURLRequest> CreateURLRequest( 245 CefRefPtr<CefRequest> request, 246 CefRefPtr<CefURLRequestClient> client) = 0; 247 248 /// 249 // Send a message to the specified |target_process|. Ownership of the message 250 // contents will be transferred and the |message| reference will be 251 // invalidated. Message delivery is not guaranteed in all cases (for example, 252 // if the browser is closing, navigating, or if the target process crashes). 253 // Send an ACK message back from the target process if confirmation is 254 // required. 255 /// 256 /*--cef()--*/ 257 virtual void SendProcessMessage(CefProcessId target_process, 258 CefRefPtr<CefProcessMessage> message) = 0; 259 }; 260 261 #endif // CEF_INCLUDE_CEF_FRAME_H_ 262