1 // Copyright 2013 The Chromium Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
5 #ifndef EXTENSIONS_BROWSER_EXTENSION_FUNCTION_H_
6 #define EXTENSIONS_BROWSER_EXTENSION_FUNCTION_H_
11 #include "base/callback.h"
12 #include "base/compiler_specific.h"
13 #include "base/memory/ref_counted.h"
14 #include "base/memory/scoped_ptr.h"
15 #include "base/memory/weak_ptr.h"
16 #include "base/process/process.h"
17 #include "base/sequenced_task_runner_helpers.h"
18 #include "content/public/browser/browser_thread.h"
19 #include "content/public/common/console_message_level.h"
20 #include "extensions/browser/extension_function_histogram_value.h"
21 #include "extensions/browser/info_map.h"
22 #include "extensions/common/extension.h"
23 #include "extensions/common/features/feature.h"
24 #include "ipc/ipc_message.h"
26 class ExtensionFunction
;
27 class UIThreadExtensionFunction
;
28 class IOThreadExtensionFunction
;
37 class RenderFrameHost
;
42 namespace extensions
{
43 class ExtensionFunctionDispatcher
;
44 class ExtensionMessageFilter
;
45 class QuotaLimitHeuristic
;
53 #define EXTENSION_FUNCTION_VALIDATE(test) \
56 this->bad_message_ = true; \
57 return ValidationFailure(this); \
61 #define EXTENSION_FUNCTION_VALIDATE(test) CHECK(test)
64 #define EXTENSION_FUNCTION_ERROR(error) \
67 this->bad_message_ = true; \
68 return ValidationFailure(this); \
71 // Declares a callable extension function with the given |name|. You must also
72 // supply a unique |histogramvalue| used for histograms of extension function
73 // invocation (add new ones at the end of the enum in
74 // extension_function_histogram_value.h).
75 #define DECLARE_EXTENSION_FUNCTION(name, histogramvalue) \
76 public: static const char* function_name() { return name; } \
77 public: static extensions::functions::HistogramValue histogram_value() \
78 { return extensions::functions::histogramvalue; }
80 // Traits that describe how ExtensionFunction should be deleted. This just calls
81 // the virtual "Destruct" method on ExtensionFunction, allowing derived classes
82 // to override the behavior.
83 struct ExtensionFunctionDeleteTraits
{
85 static void Destruct(const ExtensionFunction
* x
);
88 // Abstract base class for extension functions the ExtensionFunctionDispatcher
89 // knows how to dispatch to.
90 class ExtensionFunction
91 : public base::RefCountedThreadSafe
<ExtensionFunction
,
92 ExtensionFunctionDeleteTraits
> {
95 // The function has succeeded.
97 // The function has failed.
99 // The input message is malformed.
103 typedef base::Callback
<void(ResponseType type
,
104 const base::ListValue
& results
,
105 const std::string
& error
)> ResponseCallback
;
109 virtual UIThreadExtensionFunction
* AsUIThreadExtensionFunction();
110 virtual IOThreadExtensionFunction
* AsIOThreadExtensionFunction();
112 // Returns true if the function has permission to run.
114 // The default implementation is to check the Extension's permissions against
115 // what this function requires to run, but some APIs may require finer
116 // grained control, such as tabs.executeScript being allowed for active tabs.
118 // This will be run after the function has been set up but before Run().
119 virtual bool HasPermission();
121 // The result of a function call.
123 // Use NoArguments(), OneArgument(), ArgumentList(), or Error()
124 // rather than this class directly.
125 class ResponseValueObject
{
127 virtual ~ResponseValueObject() {}
129 // Returns true for success, false for failure.
130 virtual bool Apply() = 0;
132 typedef scoped_ptr
<ResponseValueObject
> ResponseValue
;
134 // The action to use when returning from RunAsync.
136 // Use RespondNow() or RespondLater() rather than this class directly.
137 class ResponseActionObject
{
139 virtual ~ResponseActionObject() {}
141 virtual void Execute() = 0;
143 typedef scoped_ptr
<ResponseActionObject
> ResponseAction
;
145 // Helper class for tests to force all ExtensionFunction::user_gesture()
146 // calls to return true as long as at least one instance of this class
148 class ScopedUserGestureForTests
{
150 ScopedUserGestureForTests();
151 ~ScopedUserGestureForTests();
154 // Runs the function and returns the action to take when the caller is ready
157 // Typical return values might be:
158 // * RespondNow(NoArguments())
159 // * RespondNow(OneArgument(42))
160 // * RespondNow(ArgumentList(my_result.ToValue()))
161 // * RespondNow(Error("Warp core breach"))
162 // * RespondNow(Error("Warp core breach on *", GetURL()))
163 // * RespondLater(), then later,
164 // * Respond(NoArguments())
168 // Callers must call Execute() on the return ResponseAction at some point,
171 // SyncExtensionFunction and AsyncExtensionFunction implement this in terms
172 // of SyncExtensionFunction::RunSync and AsyncExtensionFunction::RunAsync,
173 // but this is deprecated. ExtensionFunction implementations are encouraged
174 // to just implement Run.
175 virtual ResponseAction
Run() WARN_UNUSED_RESULT
= 0;
177 // Gets whether quota should be applied to this individual function
178 // invocation. This is different to GetQuotaLimitHeuristics which is only
179 // invoked once and then cached.
181 // Returns false by default.
182 virtual bool ShouldSkipQuotaLimiting() const;
184 // Optionally adds one or multiple QuotaLimitHeuristic instances suitable for
185 // this function to |heuristics|. The ownership of the new QuotaLimitHeuristic
186 // instances is passed to the owner of |heuristics|.
187 // No quota limiting by default.
189 // Only called once per lifetime of the QuotaService.
190 virtual void GetQuotaLimitHeuristics(
191 extensions::QuotaLimitHeuristics
* heuristics
) const {}
193 // Called when the quota limit has been exceeded. The default implementation
195 virtual void OnQuotaExceeded(const std::string
& violation_error
);
197 // Specifies the raw arguments to the function, as a JSON value.
198 virtual void SetArgs(const base::ListValue
* args
);
200 // Sets a single Value as the results of the function.
201 void SetResult(base::Value
* result
);
203 // Sets multiple Values as the results of the function.
204 void SetResultList(scoped_ptr
<base::ListValue
> results
);
206 // Retrieves the results of the function as a ListValue.
207 const base::ListValue
* GetResultList() const;
209 // Retrieves any error string from the function.
210 virtual std::string
GetError() const;
212 // Sets the function's error string.
213 virtual void SetError(const std::string
& error
);
215 // Sets the function's bad message state.
216 void set_bad_message(bool bad_message
) { bad_message_
= bad_message
; }
218 // Specifies the name of the function.
219 void set_name(const std::string
& name
) { name_
= name
; }
220 const std::string
& name() const { return name_
; }
222 void set_profile_id(void* profile_id
) { profile_id_
= profile_id
; }
223 void* profile_id() const { return profile_id_
; }
226 const scoped_refptr
<const extensions::Extension
>& extension
) {
227 extension_
= extension
;
229 const extensions::Extension
* extension() const { return extension_
.get(); }
230 const std::string
& extension_id() const {
232 << "extension_id() called without an Extension. If " << name()
233 << " is allowed to be called without any Extension then you should "
234 << "check extension() first. If not, there is a bug in the Extension "
235 << "platform, so page somebody in extensions/OWNERS";
236 return extension_
->id();
239 void set_request_id(int request_id
) { request_id_
= request_id
; }
240 int request_id() { return request_id_
; }
242 void set_source_url(const GURL
& source_url
) { source_url_
= source_url
; }
243 const GURL
& source_url() { return source_url_
; }
245 void set_has_callback(bool has_callback
) { has_callback_
= has_callback
; }
246 bool has_callback() { return has_callback_
; }
248 void set_include_incognito(bool include
) { include_incognito_
= include
; }
249 bool include_incognito() const { return include_incognito_
; }
251 // Note: consider using ScopedUserGestureForTests instead of calling
252 // set_user_gesture directly.
253 void set_user_gesture(bool user_gesture
) { user_gesture_
= user_gesture
; }
254 bool user_gesture() const;
256 void set_histogram_value(
257 extensions::functions::HistogramValue histogram_value
) {
258 histogram_value_
= histogram_value
; }
259 extensions::functions::HistogramValue
histogram_value() const {
260 return histogram_value_
; }
262 void set_response_callback(const ResponseCallback
& callback
) {
263 response_callback_
= callback
;
266 void set_source_tab_id(int source_tab_id
) { source_tab_id_
= source_tab_id
; }
267 int source_tab_id() const { return source_tab_id_
; }
269 void set_source_context_type(extensions::Feature::Context type
) {
270 source_context_type_
= type
;
272 extensions::Feature::Context
source_context_type() const {
273 return source_context_type_
;
277 friend struct ExtensionFunctionDeleteTraits
;
281 // Success, no arguments to pass to caller.
282 ResponseValue
NoArguments();
283 // Success, a single argument |arg| to pass to caller. TAKES OWNERSHIP - a
284 // raw pointer for convenience, since callers usually construct the argument
286 ResponseValue
OneArgument(base::Value
* arg
);
287 // Success, two arguments |arg1| and |arg2| to pass to caller. TAKES
288 // OWNERSHIP - raw pointers for convenience, since callers usually construct
289 // the argument to this by hand. Note that use of this function may imply you
290 // should be using the generated Result struct and ArgumentList.
291 ResponseValue
TwoArguments(base::Value
* arg1
, base::Value
* arg2
);
292 // Success, a list of arguments |results| to pass to caller. TAKES OWNERSHIP
293 // - a scoped_ptr<> for convenience, since callers usually get this from the
294 // result of a Create(...) call on the generated Results struct, for example,
295 // alarms::Get::Results::Create(alarm).
296 ResponseValue
ArgumentList(scoped_ptr
<base::ListValue
> results
);
297 // Error. chrome.runtime.lastError.message will be set to |error|.
298 ResponseValue
Error(const std::string
& error
);
299 // Error with formatting. Args are processed using
300 // ErrorUtils::FormatErrorMessage, that is, each occurence of * is replaced
301 // by the corresponding |s*|:
302 // Error("Error in *: *", "foo", "bar") <--> Error("Error in foo: bar").
303 ResponseValue
Error(const std::string
& format
, const std::string
& s1
);
304 ResponseValue
Error(const std::string
& format
,
305 const std::string
& s1
,
306 const std::string
& s2
);
307 ResponseValue
Error(const std::string
& format
,
308 const std::string
& s1
,
309 const std::string
& s2
,
310 const std::string
& s3
);
311 // Bad message. A ResponseValue equivalent to EXTENSION_FUNCTION_VALIDATE(),
312 // so this will actually kill the renderer and not respond at all.
313 ResponseValue
BadMessage();
317 // Respond to the extension immediately with |result|.
318 ResponseAction
RespondNow(ResponseValue result
);
319 // Don't respond now, but promise to call Respond(...) later.
320 ResponseAction
RespondLater();
322 // This is the return value of the EXTENSION_FUNCTION_VALIDATE macro, which
323 // needs to work from Run(), RunAsync(), and RunSync(). The former of those
324 // has a different return type (ResponseAction) than the latter two (bool).
325 static ResponseAction
ValidationFailure(ExtensionFunction
* function
);
327 // If RespondLater() was used, functions must at some point call Respond()
328 // with |result| as their result.
329 void Respond(ResponseValue result
);
331 virtual ~ExtensionFunction();
333 // Helper method for ExtensionFunctionDeleteTraits. Deletes this object.
334 virtual void Destruct() const = 0;
336 // Do not call this function directly, return the appropriate ResponseAction
337 // from Run() instead. If using RespondLater then call Respond().
339 // Call with true to indicate success, false to indicate failure, in which
340 // case please set |error_|.
341 virtual void SendResponse(bool success
) = 0;
343 // Common implementation for SendResponse.
344 void SendResponseImpl(bool success
);
346 // Return true if the argument to this function at |index| was provided and
348 bool HasOptionalArgument(size_t index
);
350 // Id of this request, used to map the response back to the caller.
353 // The id of the profile of this function's extension.
356 // The extension that called this function.
357 scoped_refptr
<const extensions::Extension
> extension_
;
359 // The name of this function.
362 // The URL of the frame which is making this request
365 // True if the js caller provides a callback function to receive the response
369 // True if this callback should include information from incognito contexts
370 // even if our profile_ is non-incognito. Note that in the case of a "split"
371 // mode extension, this will always be false, and we will limit access to
372 // data from within the same profile_ (either incognito or not).
373 bool include_incognito_
;
375 // True if the call was made in response of user gesture.
378 // The arguments to the API. Only non-null if argument were specified.
379 scoped_ptr
<base::ListValue
> args_
;
381 // The results of the API. This should be populated by the derived class
382 // before SendResponse() is called.
383 scoped_ptr
<base::ListValue
> results_
;
385 // Any detailed error from the API. This should be populated by the derived
386 // class before Run() returns.
389 // Any class that gets a malformed message should set this to true before
390 // returning. Usually we want to kill the message sending process.
393 // The sample value to record with the histogram API when the function
395 extensions::functions::HistogramValue histogram_value_
;
397 // The callback to run once the function has done execution.
398 ResponseCallback response_callback_
;
400 // The ID of the tab triggered this function call, or -1 if there is no tab.
403 // The type of the JavaScript context where this call originated.
404 extensions::Feature::Context source_context_type_
;
407 void OnRespondingLater(ResponseValue response
);
409 DISALLOW_COPY_AND_ASSIGN(ExtensionFunction
);
412 // Extension functions that run on the UI thread. Most functions fall into
414 class UIThreadExtensionFunction
: public ExtensionFunction
{
416 // TODO(yzshen): We should be able to remove this interface now that we
417 // support overriding the response callback.
418 // A delegate for use in testing, to intercept the call to SendResponse.
419 class DelegateForTests
{
421 virtual void OnSendResponse(UIThreadExtensionFunction
* function
,
423 bool bad_message
) = 0;
426 UIThreadExtensionFunction();
428 UIThreadExtensionFunction
* AsUIThreadExtensionFunction() override
;
430 void set_test_delegate(DelegateForTests
* delegate
) {
431 delegate_
= delegate
;
434 // Called when a message was received.
435 // Should return true if it processed the message.
436 virtual bool OnMessageReceived(const IPC::Message
& message
);
438 // Set the browser context which contains the extension that has originated
439 // this function call.
440 void set_browser_context(content::BrowserContext
* context
) {
443 content::BrowserContext
* browser_context() const { return context_
; }
445 void SetRenderViewHost(content::RenderViewHost
* render_view_host
);
446 content::RenderViewHost
* render_view_host() const {
447 return render_view_host_
;
449 void SetRenderFrameHost(content::RenderFrameHost
* render_frame_host
);
450 content::RenderFrameHost
* render_frame_host() const {
451 return render_frame_host_
;
454 void set_dispatcher(const base::WeakPtr
<
455 extensions::ExtensionFunctionDispatcher
>& dispatcher
) {
456 dispatcher_
= dispatcher
;
458 extensions::ExtensionFunctionDispatcher
* dispatcher() const {
459 return dispatcher_
.get();
462 // Gets the "current" web contents if any. If there is no associated web
463 // contents then defaults to the foremost one.
464 virtual content::WebContents
* GetAssociatedWebContents();
467 // Emits a message to the extension's devtools console.
468 void WriteToConsole(content::ConsoleMessageLevel level
,
469 const std::string
& message
);
471 friend struct content::BrowserThread::DeleteOnThread
<
472 content::BrowserThread::UI
>;
473 friend class base::DeleteHelper
<UIThreadExtensionFunction
>;
475 ~UIThreadExtensionFunction() override
;
477 void SendResponse(bool success
) override
;
479 // Sets the Blob UUIDs whose ownership is being transferred to the renderer.
480 void SetTransferredBlobUUIDs(const std::vector
<std::string
>& blob_uuids
);
482 // The dispatcher that will service this extension function call.
483 base::WeakPtr
<extensions::ExtensionFunctionDispatcher
> dispatcher_
;
485 // The RenderViewHost we will send responses to.
486 content::RenderViewHost
* render_view_host_
;
488 // The RenderFrameHost we will send responses to.
489 // NOTE: either render_view_host_ or render_frame_host_ will be set, as we
490 // port code to use RenderFrames for OOPIF. See http://crbug.com/304341.
491 content::RenderFrameHost
* render_frame_host_
;
493 // The content::BrowserContext of this function's extension.
494 content::BrowserContext
* context_
;
497 class RenderHostTracker
;
499 void Destruct() const override
;
501 // TODO(tommycli): Remove once RenderViewHost is gone.
502 IPC::Sender
* GetIPCSender();
505 scoped_ptr
<RenderHostTracker
> tracker_
;
507 DelegateForTests
* delegate_
;
509 // The blobs transferred to the renderer process.
510 std::vector
<std::string
> transferred_blob_uuids_
;
513 // Extension functions that run on the IO thread. This type of function avoids
514 // a roundtrip to and from the UI thread (because communication with the
515 // extension process happens on the IO thread). It's intended to be used when
516 // performance is critical (e.g. the webRequest API which can block network
517 // requests). Generally, UIThreadExtensionFunction is more appropriate and will
518 // be easier to use and interface with the rest of the browser.
519 class IOThreadExtensionFunction
: public ExtensionFunction
{
521 IOThreadExtensionFunction();
523 IOThreadExtensionFunction
* AsIOThreadExtensionFunction() override
;
526 base::WeakPtr
<extensions::ExtensionMessageFilter
> ipc_sender
,
528 ipc_sender_
= ipc_sender
;
529 routing_id_
= routing_id
;
532 base::WeakPtr
<extensions::ExtensionMessageFilter
> ipc_sender_weak() const {
536 int routing_id() const { return routing_id_
; }
538 void set_extension_info_map(const extensions::InfoMap
* extension_info_map
) {
539 extension_info_map_
= extension_info_map
;
541 const extensions::InfoMap
* extension_info_map() const {
542 return extension_info_map_
.get();
546 friend struct content::BrowserThread::DeleteOnThread
<
547 content::BrowserThread::IO
>;
548 friend class base::DeleteHelper
<IOThreadExtensionFunction
>;
550 ~IOThreadExtensionFunction() override
;
552 void Destruct() const override
;
554 void SendResponse(bool success
) override
;
557 base::WeakPtr
<extensions::ExtensionMessageFilter
> ipc_sender_
;
560 scoped_refptr
<const extensions::InfoMap
> extension_info_map_
;
563 // Base class for an extension function that runs asynchronously *relative to
564 // the browser's UI thread*.
565 class AsyncExtensionFunction
: public UIThreadExtensionFunction
{
567 AsyncExtensionFunction();
570 ~AsyncExtensionFunction() override
;
572 // Deprecated: Override UIThreadExtensionFunction and implement Run() instead.
574 // AsyncExtensionFunctions implement this method. Return true to indicate that
575 // nothing has gone wrong yet; SendResponse must be called later. Return false
576 // to respond immediately with an error.
577 virtual bool RunAsync() = 0;
579 // ValidationFailure override to match RunAsync().
580 static bool ValidationFailure(AsyncExtensionFunction
* function
);
583 ResponseAction
Run() override
;
586 // A SyncExtensionFunction is an ExtensionFunction that runs synchronously
587 // *relative to the browser's UI thread*. Note that this has nothing to do with
588 // running synchronously relative to the extension process. From the extension
589 // process's point of view, the function is still asynchronous.
591 // This kind of function is convenient for implementing simple APIs that just
592 // need to interact with things on the browser UI thread.
593 class SyncExtensionFunction
: public UIThreadExtensionFunction
{
595 SyncExtensionFunction();
598 ~SyncExtensionFunction() override
;
600 // Deprecated: Override UIThreadExtensionFunction and implement Run() instead.
602 // SyncExtensionFunctions implement this method. Return true to respond
603 // immediately with success, false to respond immediately with an error.
604 virtual bool RunSync() = 0;
606 // ValidationFailure override to match RunSync().
607 static bool ValidationFailure(SyncExtensionFunction
* function
);
610 ResponseAction
Run() override
;
613 class SyncIOThreadExtensionFunction
: public IOThreadExtensionFunction
{
615 SyncIOThreadExtensionFunction();
618 ~SyncIOThreadExtensionFunction() override
;
620 // Deprecated: Override IOThreadExtensionFunction and implement Run() instead.
622 // SyncIOThreadExtensionFunctions implement this method. Return true to
623 // respond immediately with success, false to respond immediately with an
625 virtual bool RunSync() = 0;
627 // ValidationFailure override to match RunSync().
628 static bool ValidationFailure(SyncIOThreadExtensionFunction
* function
);
631 ResponseAction
Run() override
;
634 #endif // EXTENSIONS_BROWSER_EXTENSION_FUNCTION_H_