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 // Tells all renderer processes associated with this context to throw away 184 // their plugin list cache. If |reload_pages| is true they will also reload 185 // all pages with plugins. CefRequestContextHandler::OnBeforePluginLoad may 186 // be called to rebuild the plugin list cache. 187 /// 188 /*--cef()--*/ 189 virtual void PurgePluginListCache(bool reload_pages) = 0; 190 191 /// 192 // Returns true if a preference with the specified |name| exists. This method 193 // must be called on the browser process UI thread. 194 /// 195 /*--cef()--*/ 196 virtual bool HasPreference(const CefString& name) = 0; 197 198 /// 199 // Returns the value for the preference with the specified |name|. Returns 200 // NULL if the preference does not exist. The returned object contains a copy 201 // of the underlying preference value and modifications to the returned object 202 // will not modify the underlying preference value. This method must be called 203 // on the browser process UI thread. 204 /// 205 /*--cef()--*/ 206 virtual CefRefPtr<CefValue> GetPreference(const CefString& name) = 0; 207 208 /// 209 // Returns all preferences as a dictionary. If |include_defaults| is true then 210 // preferences currently at their default value will be included. The returned 211 // object contains a copy of the underlying preference values and 212 // modifications to the returned object will not modify the underlying 213 // preference values. This method must be called on the browser process UI 214 // thread. 215 /// 216 /*--cef()--*/ 217 virtual CefRefPtr<CefDictionaryValue> GetAllPreferences( 218 bool include_defaults) = 0; 219 220 /// 221 // Returns true if the preference with the specified |name| can be modified 222 // using SetPreference. As one example preferences set via the command-line 223 // usually cannot be modified. This method must be called on the browser 224 // process UI thread. 225 /// 226 /*--cef()--*/ 227 virtual bool CanSetPreference(const CefString& name) = 0; 228 229 /// 230 // Set the |value| associated with preference |name|. Returns true if the 231 // value is set successfully and false otherwise. If |value| is NULL the 232 // preference will be restored to its default value. If setting the preference 233 // fails then |error| will be populated with a detailed description of the 234 // problem. This method must be called on the browser process UI thread. 235 /// 236 /*--cef(optional_param=value)--*/ 237 virtual bool SetPreference(const CefString& name, 238 CefRefPtr<CefValue> value, 239 CefString& error) = 0; 240 241 /// 242 // Clears all certificate exceptions that were added as part of handling 243 // CefRequestHandler::OnCertificateError(). If you call this it is 244 // recommended that you also call CloseAllConnections() or you risk not 245 // being prompted again for server certificates if you reconnect quickly. 246 // If |callback| is non-NULL it will be executed on the UI thread after 247 // completion. 248 /// 249 /*--cef(optional_param=callback)--*/ 250 virtual void ClearCertificateExceptions( 251 CefRefPtr<CefCompletionCallback> callback) = 0; 252 253 /// 254 // Clears all HTTP authentication credentials that were added as part of 255 // handling GetAuthCredentials. If |callback| is non-NULL it will be executed 256 // on the UI thread after completion. 257 /// 258 /*--cef(optional_param=callback)--*/ 259 virtual void ClearHttpAuthCredentials( 260 CefRefPtr<CefCompletionCallback> callback) = 0; 261 262 /// 263 // Clears all active and idle connections that Chromium currently has. 264 // This is only recommended if you have released all other CEF objects but 265 // don't yet want to call CefShutdown(). If |callback| is non-NULL it will be 266 // executed on the UI thread after completion. 267 /// 268 /*--cef(optional_param=callback)--*/ 269 virtual void CloseAllConnections( 270 CefRefPtr<CefCompletionCallback> callback) = 0; 271 272 /// 273 // Attempts to resolve |origin| to a list of associated IP addresses. 274 // |callback| will be executed on the UI thread after completion. 275 /// 276 /*--cef()--*/ 277 virtual void ResolveHost(const CefString& origin, 278 CefRefPtr<CefResolveCallback> callback) = 0; 279 280 /// 281 // Load an extension. 282 // 283 // If extension resources will be read from disk using the default load 284 // implementation then |root_directory| should be the absolute path to the 285 // extension resources directory and |manifest| should be NULL. If extension 286 // resources will be provided by the client (e.g. via CefRequestHandler and/or 287 // CefExtensionHandler) then |root_directory| should be a path component 288 // unique to the extension (if not absolute this will be internally prefixed 289 // with the PK_DIR_RESOURCES path) and |manifest| should contain the contents 290 // that would otherwise be read from the "manifest.json" file on disk. 291 // 292 // The loaded extension will be accessible in all contexts sharing the same 293 // storage (HasExtension returns true). However, only the context on which 294 // this method was called is considered the loader (DidLoadExtension returns 295 // true) and only the loader will receive CefRequestContextHandler callbacks 296 // for the extension. 297 // 298 // CefExtensionHandler::OnExtensionLoaded will be called on load success or 299 // CefExtensionHandler::OnExtensionLoadFailed will be called on load failure. 300 // 301 // If the extension specifies a background script via the "background" 302 // manifest key then CefExtensionHandler::OnBeforeBackgroundBrowser will be 303 // called to create the background browser. See that method for additional 304 // information about background scripts. 305 // 306 // For visible extension views the client application should evaluate the 307 // manifest to determine the correct extension URL to load and then pass that 308 // URL to the CefBrowserHost::CreateBrowser* function after the extension has 309 // loaded. For example, the client can look for the "browser_action" manifest 310 // key as documented at https://developer.chrome.com/extensions/browserAction. 311 // Extension URLs take the form "chrome-extension://<extension_id>/<path>". 312 // 313 // Browsers that host extensions differ from normal browsers as follows: 314 // - Can access chrome.* JavaScript APIs if allowed by the manifest. Visit 315 // chrome://extensions-support for the list of extension APIs currently 316 // supported by CEF. 317 // - Main frame navigation to non-extension content is blocked. 318 // - Pinch-zooming is disabled. 319 // - CefBrowserHost::GetExtension returns the hosted extension. 320 // - CefBrowserHost::IsBackgroundHost returns true for background hosts. 321 // 322 // See https://developer.chrome.com/extensions for extension implementation 323 // and usage documentation. 324 /// 325 /*--cef(optional_param=manifest,optional_param=handler)--*/ 326 virtual void LoadExtension(const CefString& root_directory, 327 CefRefPtr<CefDictionaryValue> manifest, 328 CefRefPtr<CefExtensionHandler> handler) = 0; 329 330 /// 331 // Returns true if this context was used to load the extension identified by 332 // |extension_id|. Other contexts sharing the same storage will also have 333 // access to the extension (see HasExtension). This method must be called on 334 // the browser process UI thread. 335 /// 336 /*--cef()--*/ 337 virtual bool DidLoadExtension(const CefString& extension_id) = 0; 338 339 /// 340 // Returns true if this context has access to the extension identified by 341 // |extension_id|. This may not be the context that was used to load the 342 // extension (see DidLoadExtension). This method must be called on the browser 343 // process UI thread. 344 /// 345 /*--cef()--*/ 346 virtual bool HasExtension(const CefString& extension_id) = 0; 347 348 /// 349 // Retrieve the list of all extensions that this context has access to (see 350 // HasExtension). |extension_ids| will be populated with the list of extension 351 // ID values. Returns true on success. This method must be called on the 352 // browser process UI thread. 353 /// 354 /*--cef()--*/ 355 virtual bool GetExtensions(std::vector<CefString>& extension_ids) = 0; 356 357 /// 358 // Returns the extension matching |extension_id| or NULL if no matching 359 // extension is accessible in this context (see HasExtension). This method 360 // must be called on the browser process UI thread. 361 /// 362 /*--cef()--*/ 363 virtual CefRefPtr<CefExtension> GetExtension( 364 const CefString& extension_id) = 0; 365 366 /// 367 // Returns the MediaRouter object associated with this context. If |callback| 368 // is non-NULL it will be executed asnychronously on the UI thread after the 369 // manager's context has been initialized. 370 /// 371 /*--cef(optional_param=callback)--*/ 372 virtual CefRefPtr<CefMediaRouter> GetMediaRouter( 373 CefRefPtr<CefCompletionCallback> callback) = 0; 374 }; 375 376 #endif // CEF_INCLUDE_CEF_REQUEST_CONTEXT_H_ 377