1 // Copyright 2017 the Chromium Embedded Framework Authors. Portions copyright 2 // 2014 The Chromium Authors. All rights reserved. Use of this source code is 3 // governed by a BSD-style license that can be found in the LICENSE file. 4 5 #ifndef CEF_LIBCEF_BROWSER_EXTENSIONS_EXTENSION_FUNCTION_DETAILS_H_ 6 #define CEF_LIBCEF_BROWSER_EXTENSIONS_EXTENSION_FUNCTION_DETAILS_H_ 7 8 #include "libcef/browser/alloy/alloy_browser_host_impl.h" 9 10 #include "include/cef_extension.h" 11 12 #include "base/callback_forward.h" 13 #include "chrome/common/extensions/api/tabs.h" 14 #include "ui/gfx/native_widget_types.h" 15 16 class Profile; 17 class ExtensionFunction; 18 19 namespace content { 20 class WebContents; 21 } 22 23 namespace extensions { 24 25 // Provides CEF-specific details to ExtensionFunction implementations. 26 // Based on chrome/browser/extensions/chrome_extension_function_details.h. 27 class CefExtensionFunctionDetails { 28 public: 29 // Constructs a new ChromeExtensionFunctionDetails instance for |function|. 30 // This instance does not own |function| and must outlive it. 31 explicit CefExtensionFunctionDetails(ExtensionFunction* function); 32 33 CefExtensionFunctionDetails(const CefExtensionFunctionDetails&) = delete; 34 CefExtensionFunctionDetails& operator=(const CefExtensionFunctionDetails&) = 35 delete; 36 37 ~CefExtensionFunctionDetails(); 38 39 Profile* GetProfile() const; 40 41 // Get the "sender" browser that is hosting the extension. May return NULL 42 // during startup/shutdown. 43 CefRefPtr<AlloyBrowserHostImpl> GetSenderBrowser() const; 44 45 // Get the "current" browser that will be acted on by this extension function, 46 // if any. When mapping from a tabId use the GetBrowserForTabId* methods 47 // instead of calling this method directly. 48 // 49 // Many extension APIs operate relative to the browser that the calling code 50 // is running inside of. For example, popups and tabs all have a containing 51 // browser, but background pages and notification bubbles do not. Other APIs, 52 // like chrome.tabs.*, can act on either a specific browser (specified via the 53 // tabId parameter) or should allow the client to determine the most 54 // appropriate browser (for example, the browser that representing the 55 // foreground window). 56 // 57 // Incognito browsers should not be considered unless the calling extension 58 // has incognito access enabled. CEF does not internally enforce incognito 59 // status so we pass this flag to client callbacks for consideration. 60 // 61 // This method can return NULL if there is no matching browser, which can 62 // happen if only incognito windows are open, or early in startup or shutdown 63 // shutdown when there are no active windows. 64 CefRefPtr<AlloyBrowserHostImpl> GetCurrentBrowser() const; 65 66 // Returns true if the sender browser can access |target|. When mapping from a 67 // tabId use the GetBrowserForTabId* methods instead of calling this method 68 // directly. 69 bool CanAccessBrowser(CefRefPtr<AlloyBrowserHostImpl> target) const; 70 71 // Returns the browser matching |tab_id| or NULL if the browser cannot be 72 // found or does not have a WebContents. If |tab_id| is < 0 the "current" 73 // browser will be returned. |error_message| can optionally be passed in and 74 // will be set with an appropriate message on error. This method should only 75 // be called one time per extension function and will check all necessary 76 // client permissions. 77 CefRefPtr<AlloyBrowserHostImpl> GetBrowserForTabIdFirstTime( 78 int tab_id, 79 std::string* error_message) const; 80 81 // Returns the browser matching |tab_id| or NULL if the browser cannot be 82 // found or does not have a WebContents. |tab_id| must be >= 0. 83 // |error_message| can optionally be passed in and will be set with an 84 // appropriate message on error. This method should be called only after 85 // GetBrowserForTabIdFirstTime() has succeeded for the same |tab_id|. 86 CefRefPtr<AlloyBrowserHostImpl> GetBrowserForTabIdAgain( 87 int tab_id, 88 std::string* error_message) const; 89 90 // Give the client a chance to handle |file|. |callback| will be executed 91 // once the file contents have been loaded. Returns false if the file is 92 // unhandled. 93 using LoadFileCallback = 94 base::OnceCallback<void(std::unique_ptr<std::string>)>; 95 bool LoadFile(const std::string& file, LoadFileCallback callback) const; 96 97 struct OpenTabParams { 98 OpenTabParams(); 99 ~OpenTabParams(); 100 101 std::unique_ptr<int> window_id; 102 std::unique_ptr<int> opener_tab_id; 103 std::unique_ptr<std::string> url; 104 std::unique_ptr<bool> active; 105 std::unique_ptr<bool> pinned; 106 std::unique_ptr<int> index; 107 }; 108 109 // Opens a new tab given creation parameters |params|. Returns a Tab object 110 // if successful, or NULL and optionally sets |error_message| if an error 111 // occurs. 112 base::DictionaryValue* OpenTab(const OpenTabParams& params, 113 bool user_gesture, 114 std::string* error_message) const; 115 116 // Creates a Tab object (see chrome/common/extensions/api/tabs.json) with 117 // information about the state of a browser tab. Depending on the 118 // permissions of the extension, the object may or may not include sensitive 119 // data such as the tab's URL. 120 std::unique_ptr<api::tabs::Tab> CreateTabObject( 121 CefRefPtr<AlloyBrowserHostImpl> new_browser, 122 int opener_browser_id, 123 bool active, 124 int index) const; 125 126 // Creates a tab MutedInfo object (see chrome/common/extensions/api/tabs.json) 127 // with information about the mute state of a browser tab. 128 static std::unique_ptr<api::tabs::MutedInfo> CreateMutedInfo( 129 content::WebContents* contents); 130 131 // Returns a pointer to the associated ExtensionFunction function()132 ExtensionFunction* function() { return function_; } function()133 const ExtensionFunction* function() const { return function_; } 134 135 protected: 136 CefRefPtr<CefExtension> GetCefExtension() const; 137 138 private: 139 // The function for which these details have been created. Must outlive the 140 // CefExtensionFunctionDetails instance. 141 ExtensionFunction* function_; 142 143 mutable CefRefPtr<CefExtension> cef_extension_; 144 145 // Verifies correct usage of GetBrowserForTabId* methods. 146 mutable bool get_browser_called_first_time_ = false; 147 }; 148 149 } // namespace extensions 150 151 #endif // CEF_LIBCEF_BROWSER_EXTENSIONS_EXTENSION_FUNCTION_DETAILS_H_ 152