1 // Copyright (c) 2013 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_REQUEST_CONTEXT_H_ 38 #define CEF_INCLUDE_CEF_REQUEST_CONTEXT_H_ 39 #pragma once 40 41 #include <vector> 42 43 #include "include/cef_callback.h" 44 #include "include/cef_cookie.h" 45 #include "include/cef_extension.h" 46 #include "include/cef_extension_handler.h" 47 #include "include/cef_media_router.h" 48 #include "include/cef_values.h" 49 50 class CefRequestContextHandler; 51 class CefSchemeHandlerFactory; 52 53 /// 54 // Callback interface for CefRequestContext::ResolveHost. 55 /// 56 /*--cef(source=client)--*/ 57 class CefResolveCallback : public virtual CefBaseRefCounted { 58 public: 59 /// 60 // Called on the UI thread after the ResolveHost request has completed. 61 // |result| will be the result code. |resolved_ips| will be the list of 62 // resolved IP addresses or empty if the resolution failed. 63 /// 64 /*--cef(optional_param=resolved_ips)--*/ 65 virtual void OnResolveCompleted( 66 cef_errorcode_t result, 67 const std::vector<CefString>& resolved_ips) = 0; 68 }; 69 70 /// 71 // A request context provides request handling for a set of related browser 72 // or URL request objects. A request context can be specified when creating a 73 // new browser via the CefBrowserHost static factory methods or when creating a 74 // new URL request via the CefURLRequest static factory methods. Browser objects 75 // with different request contexts will never be hosted in the same render 76 // process. Browser objects with the same request context may or may not be 77 // hosted in the same render process depending on the process model. Browser 78 // objects created indirectly via the JavaScript window.open function or 79 // targeted links will share the same render process and the same request 80 // context as the source browser. When running in single-process mode there is 81 // only a single render process (the main process) and so all browsers created 82 // in single-process mode will share the same request context. This will be the 83 // first request context passed into a CefBrowserHost static factory method and 84 // all other request context objects will be ignored. 85 /// 86 /*--cef(source=library,no_debugct_check)--*/ 87 class CefRequestContext : public virtual CefBaseRefCounted { 88 public: 89 /// 90 // Returns the global context object. 91 /// 92 /*--cef()--*/ 93 static CefRefPtr<CefRequestContext> GetGlobalContext(); 94 95 /// 96 // Creates a new context object with the specified |settings| and optional 97 // |handler|. 98 /// 99 /*--cef(optional_param=handler)--*/ 100 static CefRefPtr<CefRequestContext> CreateContext( 101 const CefRequestContextSettings& settings, 102 CefRefPtr<CefRequestContextHandler> handler); 103 104 /// 105 // Creates a new context object that shares storage with |other| and uses an 106 // optional |handler|. 107 /// 108 /*--cef(capi_name=cef_create_context_shared,optional_param=handler)--*/ 109 static CefRefPtr<CefRequestContext> CreateContext( 110 CefRefPtr<CefRequestContext> other, 111 CefRefPtr<CefRequestContextHandler> handler); 112 113 /// 114 // Returns true if this object is pointing to the same context as |that| 115 // object. 116 /// 117 /*--cef()--*/ 118 virtual bool IsSame(CefRefPtr<CefRequestContext> other) = 0; 119 120 /// 121 // Returns true if this object is sharing the same storage as |that| object. 122 /// 123 /*--cef()--*/ 124 virtual bool IsSharingWith(CefRefPtr<CefRequestContext> other) = 0; 125 126 /// 127 // Returns true if this object is the global context. The global context is 128 // used by default when creating a browser or URL request with a NULL context 129 // argument. 130 /// 131 /*--cef()--*/ 132 virtual bool IsGlobal() = 0; 133 134 /// 135 // Returns the handler for this context if any. 136 /// 137 /*--cef()--*/ 138 virtual CefRefPtr<CefRequestContextHandler> GetHandler() = 0; 139 140 /// 141 // Returns the cache path for this object. If empty an "incognito mode" 142 // in-memory cache is being used. 143 /// 144 /*--cef()--*/ 145 virtual CefString GetCachePath() = 0; 146 147 /// 148 // Returns the cookie manager for this object. If |callback| is non-NULL it 149 // will be executed asnychronously on the UI thread after the manager's 150 // storage has been initialized. 151 /// 152 /*--cef(optional_param=callback)--*/ 153 virtual CefRefPtr<CefCookieManager> GetCookieManager( 154 CefRefPtr<CefCompletionCallback> callback) = 0; 155 156 /// 157 // Register a scheme handler factory for the specified |scheme_name| and 158 // optional |domain_name|. An empty |domain_name| value for a standard scheme 159 // will cause the factory to match all domain names. The |domain_name| value 160 // will be ignored for non-standard schemes. If |scheme_name| is a built-in 161 // scheme and no handler is returned by |factory| then the built-in scheme 162 // handler factory will be called. If |scheme_name| is a custom scheme then 163 // you must also implement the CefApp::OnRegisterCustomSchemes() method in all 164 // processes. This function may be called multiple times to change or remove 165 // the factory that matches the specified |scheme_name| and optional 166 // |domain_name|. Returns false if an error occurs. This function may be 167 // called on any thread in the browser process. 168 /// 169 /*--cef(optional_param=domain_name,optional_param=factory)--*/ 170 virtual bool RegisterSchemeHandlerFactory( 171 const CefString& scheme_name, 172 const CefString& domain_name, 173 CefRefPtr<CefSchemeHandlerFactory> factory) = 0; 174 175 /// 176 // Clear all registered scheme handler factories. Returns false on error. This 177 // function may be called on any thread in the browser process. 178 /// 179 /*--cef()--*/ 180 virtual bool ClearSchemeHandlerFactories() = 0; 181 182 /// 183 // Returns true if a preference with the specified |name| exists. This method 184 // must be called on the browser process UI thread. 185 /// 186 /*--cef()--*/ 187 virtual bool HasPreference(const CefString& name) = 0; 188 189 /// 190 // Returns the value for the preference with the specified |name|. Returns 191 // NULL if the preference does not exist. The returned object contains a copy 192 // of the underlying preference value and modifications to the returned object 193 // will not modify the underlying preference value. This method must be called 194 // on the browser process UI thread. 195 /// 196 /*--cef()--*/ 197 virtual CefRefPtr<CefValue> GetPreference(const CefString& name) = 0; 198 199 /// 200 // Returns all preferences as a dictionary. If |include_defaults| is true then 201 // preferences currently at their default value will be included. The returned 202 // object contains a copy of the underlying preference values and 203 // modifications to the returned object will not modify the underlying 204 // preference values. This method must be called on the browser process UI 205 // thread. 206 /// 207 /*--cef()--*/ 208 virtual CefRefPtr<CefDictionaryValue> GetAllPreferences( 209 bool include_defaults) = 0; 210 211 /// 212 // Returns true if the preference with the specified |name| can be modified 213 // using SetPreference. As one example preferences set via the command-line 214 // usually cannot be modified. This method must be called on the browser 215 // process UI thread. 216 /// 217 /*--cef()--*/ 218 virtual bool CanSetPreference(const CefString& name) = 0; 219 220 /// 221 // Set the |value| associated with preference |name|. Returns true if the 222 // value is set successfully and false otherwise. If |value| is NULL the 223 // preference will be restored to its default value. If setting the preference 224 // fails then |error| will be populated with a detailed description of the 225 // problem. This method must be called on the browser process UI thread. 226 /// 227 /*--cef(optional_param=value)--*/ 228 virtual bool SetPreference(const CefString& name, 229 CefRefPtr<CefValue> value, 230 CefString& error) = 0; 231 232 /// 233 // Clears all certificate exceptions that were added as part of handling 234 // CefRequestHandler::OnCertificateError(). If you call this it is 235 // recommended that you also call CloseAllConnections() or you risk not 236 // being prompted again for server certificates if you reconnect quickly. 237 // If |callback| is non-NULL it will be executed on the UI thread after 238 // completion. 239 /// 240 /*--cef(optional_param=callback)--*/ 241 virtual void ClearCertificateExceptions( 242 CefRefPtr<CefCompletionCallback> callback) = 0; 243 244 /// 245 // Clears all HTTP authentication credentials that were added as part of 246 // handling GetAuthCredentials. If |callback| is non-NULL it will be executed 247 // on the UI thread after completion. 248 /// 249 /*--cef(optional_param=callback)--*/ 250 virtual void ClearHttpAuthCredentials( 251 CefRefPtr<CefCompletionCallback> callback) = 0; 252 253 /// 254 // Clears all active and idle connections that Chromium currently has. 255 // This is only recommended if you have released all other CEF objects but 256 // don't yet want to call CefShutdown(). If |callback| is non-NULL it will be 257 // executed on the UI thread after completion. 258 /// 259 /*--cef(optional_param=callback)--*/ 260 virtual void CloseAllConnections( 261 CefRefPtr<CefCompletionCallback> callback) = 0; 262 263 /// 264 // Attempts to resolve |origin| to a list of associated IP addresses. 265 // |callback| will be executed on the UI thread after completion. 266 /// 267 /*--cef()--*/ 268 virtual void ResolveHost(const CefString& origin, 269 CefRefPtr<CefResolveCallback> callback) = 0; 270 271 /// 272 // Load an extension. 273 // 274 // If extension resources will be read from disk using the default load 275 // implementation then |root_directory| should be the absolute path to the 276 // extension resources directory and |manifest| should be NULL. If extension 277 // resources will be provided by the client (e.g. via CefRequestHandler and/or 278 // CefExtensionHandler) then |root_directory| should be a path component 279 // unique to the extension (if not absolute this will be internally prefixed 280 // with the PK_DIR_RESOURCES path) and |manifest| should contain the contents 281 // that would otherwise be read from the "manifest.json" file on disk. 282 // 283 // The loaded extension will be accessible in all contexts sharing the same 284 // storage (HasExtension returns true). However, only the context on which 285 // this method was called is considered the loader (DidLoadExtension returns 286 // true) and only the loader will receive CefRequestContextHandler callbacks 287 // for the extension. 288 // 289 // CefExtensionHandler::OnExtensionLoaded will be called on load success or 290 // CefExtensionHandler::OnExtensionLoadFailed will be called on load failure. 291 // 292 // If the extension specifies a background script via the "background" 293 // manifest key then CefExtensionHandler::OnBeforeBackgroundBrowser will be 294 // called to create the background browser. See that method for additional 295 // information about background scripts. 296 // 297 // For visible extension views the client application should evaluate the 298 // manifest to determine the correct extension URL to load and then pass that 299 // URL to the CefBrowserHost::CreateBrowser* function after the extension has 300 // loaded. For example, the client can look for the "browser_action" manifest 301 // key as documented at https://developer.chrome.com/extensions/browserAction. 302 // Extension URLs take the form "chrome-extension://<extension_id>/<path>". 303 // 304 // Browsers that host extensions differ from normal browsers as follows: 305 // - Can access chrome.* JavaScript APIs if allowed by the manifest. Visit 306 // chrome://extensions-support for the list of extension APIs currently 307 // supported by CEF. 308 // - Main frame navigation to non-extension content is blocked. 309 // - Pinch-zooming is disabled. 310 // - CefBrowserHost::GetExtension returns the hosted extension. 311 // - CefBrowserHost::IsBackgroundHost returns true for background hosts. 312 // 313 // See https://developer.chrome.com/extensions for extension implementation 314 // and usage documentation. 315 /// 316 /*--cef(optional_param=manifest,optional_param=handler)--*/ 317 virtual void LoadExtension(const CefString& root_directory, 318 CefRefPtr<CefDictionaryValue> manifest, 319 CefRefPtr<CefExtensionHandler> handler) = 0; 320 321 /// 322 // Returns true if this context was used to load the extension identified by 323 // |extension_id|. Other contexts sharing the same storage will also have 324 // access to the extension (see HasExtension). This method must be called on 325 // the browser process UI thread. 326 /// 327 /*--cef()--*/ 328 virtual bool DidLoadExtension(const CefString& extension_id) = 0; 329 330 /// 331 // Returns true if this context has access to the extension identified by 332 // |extension_id|. This may not be the context that was used to load the 333 // extension (see DidLoadExtension). This method must be called on the browser 334 // process UI thread. 335 /// 336 /*--cef()--*/ 337 virtual bool HasExtension(const CefString& extension_id) = 0; 338 339 /// 340 // Retrieve the list of all extensions that this context has access to (see 341 // HasExtension). |extension_ids| will be populated with the list of extension 342 // ID values. Returns true on success. This method must be called on the 343 // browser process UI thread. 344 /// 345 /*--cef()--*/ 346 virtual bool GetExtensions(std::vector<CefString>& extension_ids) = 0; 347 348 /// 349 // Returns the extension matching |extension_id| or NULL if no matching 350 // extension is accessible in this context (see HasExtension). This method 351 // must be called on the browser process UI thread. 352 /// 353 /*--cef()--*/ 354 virtual CefRefPtr<CefExtension> GetExtension( 355 const CefString& extension_id) = 0; 356 357 /// 358 // Returns the MediaRouter object associated with this context. If |callback| 359 // is non-NULL it will be executed asnychronously on the UI thread after the 360 // manager's context has been initialized. 361 /// 362 /*--cef(optional_param=callback)--*/ 363 virtual CefRefPtr<CefMediaRouter> GetMediaRouter( 364 CefRefPtr<CefCompletionCallback> callback) = 0; 365 }; 366 367 #endif // CEF_INCLUDE_CEF_REQUEST_CONTEXT_H_ 368