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 // Runs the function and returns the action to take when the caller is ready
148 // Typical return values might be:
149 // * RespondNow(NoArguments())
150 // * RespondNow(OneArgument(42))
151 // * RespondNow(ArgumentList(my_result.ToValue()))
152 // * RespondNow(Error("Warp core breach"))
153 // * RespondNow(Error("Warp core breach on *", GetURL()))
154 // * RespondLater(), then later,
155 // * Respond(NoArguments())
159 // Callers must call Execute() on the return ResponseAction at some point,
162 // SyncExtensionFunction and AsyncExtensionFunction implement this in terms
163 // of SyncExtensionFunction::RunSync and AsyncExtensionFunction::RunAsync,
164 // but this is deprecated. ExtensionFunction implementations are encouraged
165 // to just implement Run.
166 virtual ResponseAction Run() WARN_UNUSED_RESULT = 0;
168 // Gets whether quota should be applied to this individual function
169 // invocation. This is different to GetQuotaLimitHeuristics which is only
170 // invoked once and then cached.
172 // Returns false by default.
173 virtual bool ShouldSkipQuotaLimiting() const;
175 // Optionally adds one or multiple QuotaLimitHeuristic instances suitable for
176 // this function to |heuristics|. The ownership of the new QuotaLimitHeuristic
177 // instances is passed to the owner of |heuristics|.
178 // No quota limiting by default.
180 // Only called once per lifetime of the QuotaService.
181 virtual void GetQuotaLimitHeuristics(
182 extensions::QuotaLimitHeuristics* heuristics) const {}
184 // Called when the quota limit has been exceeded. The default implementation
186 virtual void OnQuotaExceeded(const std::string& violation_error);
188 // Specifies the raw arguments to the function, as a JSON value.
189 virtual void SetArgs(const base::ListValue* args);
191 // Sets a single Value as the results of the function.
192 void SetResult(base::Value* result);
194 // Sets multiple Values as the results of the function.
195 void SetResultList(scoped_ptr<base::ListValue> results);
197 // Retrieves the results of the function as a ListValue.
198 const base::ListValue* GetResultList() const;
200 // Retrieves any error string from the function.
201 virtual std::string GetError() const;
203 // Sets the function's error string.
204 virtual void SetError(const std::string& error);
206 // Sets the function's bad message state.
207 void set_bad_message(bool bad_message) { bad_message_ = bad_message; }
209 // Specifies the name of the function.
210 void set_name(const std::string& name) { name_ = name; }
211 const std::string& name() const { return name_; }
213 void set_profile_id(void* profile_id) { profile_id_ = profile_id; }
214 void* profile_id() const { return profile_id_; }
217 const scoped_refptr<const extensions::Extension>& extension) {
218 extension_ = extension;
220 const extensions::Extension* extension() const { return extension_.get(); }
221 const std::string& extension_id() const { return extension_->id(); }
223 void set_request_id(int request_id) { request_id_ = request_id; }
224 int request_id() { return request_id_; }
226 void set_source_url(const GURL& source_url) { source_url_ = source_url; }
227 const GURL& source_url() { return source_url_; }
229 void set_has_callback(bool has_callback) { has_callback_ = has_callback; }
230 bool has_callback() { return has_callback_; }
232 void set_include_incognito(bool include) { include_incognito_ = include; }
233 bool include_incognito() const { return include_incognito_; }
235 void set_user_gesture(bool user_gesture) { user_gesture_ = user_gesture; }
236 bool user_gesture() const { return user_gesture_; }
238 void set_histogram_value(
239 extensions::functions::HistogramValue histogram_value) {
240 histogram_value_ = histogram_value; }
241 extensions::functions::HistogramValue histogram_value() const {
242 return histogram_value_; }
244 void set_response_callback(const ResponseCallback& callback) {
245 response_callback_ = callback;
248 void set_source_tab_id(int source_tab_id) { source_tab_id_ = source_tab_id; }
249 int source_tab_id() const { return source_tab_id_; }
251 void set_source_context_type(extensions::Feature::Context type) {
252 source_context_type_ = type;
254 extensions::Feature::Context source_context_type() const {
255 return source_context_type_;
259 friend struct ExtensionFunctionDeleteTraits;
263 // Success, no arguments to pass to caller
264 ResponseValue NoArguments();
265 // Success, a single argument |arg| to pass to caller. TAKES OWNERSHIP -- a
266 // raw pointer for convenience, since callers usually construct the argument
268 ResponseValue OneArgument(base::Value* arg);
269 // Success, two arguments |arg1| and |arg2| to pass to caller. TAKES
270 // OWNERSHIP -- raw pointers for convenience, since callers usually construct
271 // the argument to this by hand. Note that use of this function may imply you
272 // should be using the generated Result struct and ArgumentList.
273 ResponseValue TwoArguments(base::Value* arg1, base::Value* arg2);
274 // Success, a list of arguments |results| to pass to caller. TAKES OWNERSHIP
276 // a scoped_ptr<> for convenience, since callers usually get this from the
277 // result of a ToValue() call on the generated Result struct.
278 ResponseValue ArgumentList(scoped_ptr<base::ListValue> results);
279 // Error. chrome.runtime.lastError.message will be set to |error|.
280 ResponseValue Error(const std::string& error);
281 // Error with formatting. Args are processed using
282 // ErrorUtils::FormatErrorMessage, that is, each occurence of * is replaced
283 // by the corresponding |s*|:
284 // Error("Error in *: *", "foo", "bar") <--> // Error("Error in foo: bar").
285 ResponseValue Error(const std::string& format, const std::string& s1);
286 ResponseValue Error(const std::string& format,
287 const std::string& s1,
288 const std::string& s2);
289 ResponseValue Error(const std::string& format,
290 const std::string& s1,
291 const std::string& s2,
292 const std::string& s3);
293 // Bad message. A ResponseValue equivalent to EXTENSION_FUNCTION_VALIDATE().
294 ResponseValue BadMessage();
298 // Respond to the extension immediately with |result|.
299 ResponseAction RespondNow(ResponseValue result);
300 // Don't respond now, but promise to call Respond() later.
301 ResponseAction RespondLater();
303 // This is the return value of the EXTENSION_FUNCTION_VALIDATE macro, which
304 // needs to work from Run(), RunAsync(), and RunSync(). The former of those
305 // has a different return type (ResponseAction) than the latter two (bool).
306 static ResponseAction ValidationFailure(ExtensionFunction* function);
308 // If RespondLater() was used, functions must at some point call Respond()
309 // with |result| as their result.
310 void Respond(ResponseValue result);
312 virtual ~ExtensionFunction();
314 // Helper method for ExtensionFunctionDeleteTraits. Deletes this object.
315 virtual void Destruct() const = 0;
317 // Do not call this function directly, return the appropriate ResponseAction
318 // from Run() instead. If using RespondLater then call Respond().
320 // Call with true to indicate success, false to indicate failure, in which
321 // case please set |error_|.
322 virtual void SendResponse(bool success) = 0;
324 // Common implementation for SendResponse.
325 void SendResponseImpl(bool success);
327 // Return true if the argument to this function at |index| was provided and
329 bool HasOptionalArgument(size_t index);
331 // Id of this request, used to map the response back to the caller.
334 // The id of the profile of this function's extension.
337 // The extension that called this function.
338 scoped_refptr<const extensions::Extension> extension_;
340 // The name of this function.
343 // The URL of the frame which is making this request
346 // True if the js caller provides a callback function to receive the response
350 // True if this callback should include information from incognito contexts
351 // even if our profile_ is non-incognito. Note that in the case of a "split"
352 // mode extension, this will always be false, and we will limit access to
353 // data from within the same profile_ (either incognito or not).
354 bool include_incognito_;
356 // True if the call was made in response of user gesture.
359 // The arguments to the API. Only non-null if argument were specified.
360 scoped_ptr<base::ListValue> args_;
362 // The results of the API. This should be populated by the derived class
363 // before SendResponse() is called.
364 scoped_ptr<base::ListValue> results_;
366 // Any detailed error from the API. This should be populated by the derived
367 // class before Run() returns.
370 // Any class that gets a malformed message should set this to true before
371 // returning. Usually we want to kill the message sending process.
374 // The sample value to record with the histogram API when the function
376 extensions::functions::HistogramValue histogram_value_;
378 // The callback to run once the function has done execution.
379 ResponseCallback response_callback_;
381 // The ID of the tab triggered this function call, or -1 if there is no tab.
384 // The type of the JavaScript context where this call originated.
385 extensions::Feature::Context source_context_type_;
388 void OnRespondingLater(ResponseValue response);
390 DISALLOW_COPY_AND_ASSIGN(ExtensionFunction);
393 // Extension functions that run on the UI thread. Most functions fall into
395 class UIThreadExtensionFunction : public ExtensionFunction {
397 // TODO(yzshen): We should be able to remove this interface now that we
398 // support overriding the response callback.
399 // A delegate for use in testing, to intercept the call to SendResponse.
400 class DelegateForTests {
402 virtual void OnSendResponse(UIThreadExtensionFunction* function,
404 bool bad_message) = 0;
407 UIThreadExtensionFunction();
409 virtual UIThreadExtensionFunction* AsUIThreadExtensionFunction() OVERRIDE;
411 void set_test_delegate(DelegateForTests* delegate) {
412 delegate_ = delegate;
415 // Called when a message was received.
416 // Should return true if it processed the message.
417 virtual bool OnMessageReceived(const IPC::Message& message);
419 // Set the browser context which contains the extension that has originated
420 // this function call.
421 void set_browser_context(content::BrowserContext* context) {
424 content::BrowserContext* browser_context() const { return context_; }
426 void SetRenderViewHost(content::RenderViewHost* render_view_host);
427 content::RenderViewHost* render_view_host() const {
428 return render_view_host_;
430 void SetRenderFrameHost(content::RenderFrameHost* render_frame_host);
431 content::RenderFrameHost* render_frame_host() const {
432 return render_frame_host_;
435 void set_dispatcher(const base::WeakPtr<
436 extensions::ExtensionFunctionDispatcher>& dispatcher) {
437 dispatcher_ = dispatcher;
439 extensions::ExtensionFunctionDispatcher* dispatcher() const {
440 return dispatcher_.get();
443 // Gets the "current" web contents if any. If there is no associated web
444 // contents then defaults to the foremost one.
445 virtual content::WebContents* GetAssociatedWebContents();
448 // Emits a message to the extension's devtools console.
449 void WriteToConsole(content::ConsoleMessageLevel level,
450 const std::string& message);
452 friend struct content::BrowserThread::DeleteOnThread<
453 content::BrowserThread::UI>;
454 friend class base::DeleteHelper<UIThreadExtensionFunction>;
456 virtual ~UIThreadExtensionFunction();
458 virtual void SendResponse(bool success) OVERRIDE;
460 // Sets the Blob UUIDs whose ownership is being transferred to the renderer.
461 void SetTransferredBlobUUIDs(const std::vector<std::string>& blob_uuids);
463 // The dispatcher that will service this extension function call.
464 base::WeakPtr<extensions::ExtensionFunctionDispatcher> dispatcher_;
466 // The RenderViewHost we will send responses to.
467 content::RenderViewHost* render_view_host_;
469 // The RenderFrameHost we will send responses to.
470 // NOTE: either render_view_host_ or render_frame_host_ will be set, as we
471 // port code to use RenderFrames for OOPIF. See http://crbug.com/304341.
472 content::RenderFrameHost* render_frame_host_;
474 // The content::BrowserContext of this function's extension.
475 content::BrowserContext* context_;
478 class RenderHostTracker;
480 virtual void Destruct() const OVERRIDE;
482 // TODO(tommycli): Remove once RenderViewHost is gone.
483 IPC::Sender* GetIPCSender();
486 scoped_ptr<RenderHostTracker> tracker_;
488 DelegateForTests* delegate_;
490 // The blobs transferred to the renderer process.
491 std::vector<std::string> transferred_blob_uuids_;
494 // Extension functions that run on the IO thread. This type of function avoids
495 // a roundtrip to and from the UI thread (because communication with the
496 // extension process happens on the IO thread). It's intended to be used when
497 // performance is critical (e.g. the webRequest API which can block network
498 // requests). Generally, UIThreadExtensionFunction is more appropriate and will
499 // be easier to use and interface with the rest of the browser.
500 class IOThreadExtensionFunction : public ExtensionFunction {
502 IOThreadExtensionFunction();
504 virtual IOThreadExtensionFunction* AsIOThreadExtensionFunction() OVERRIDE;
507 base::WeakPtr<extensions::ExtensionMessageFilter> ipc_sender,
509 ipc_sender_ = ipc_sender;
510 routing_id_ = routing_id;
513 base::WeakPtr<extensions::ExtensionMessageFilter> ipc_sender_weak() const {
517 int routing_id() const { return routing_id_; }
519 void set_extension_info_map(const extensions::InfoMap* extension_info_map) {
520 extension_info_map_ = extension_info_map;
522 const extensions::InfoMap* extension_info_map() const {
523 return extension_info_map_.get();
527 friend struct content::BrowserThread::DeleteOnThread<
528 content::BrowserThread::IO>;
529 friend class base::DeleteHelper<IOThreadExtensionFunction>;
531 virtual ~IOThreadExtensionFunction();
533 virtual void Destruct() const OVERRIDE;
535 virtual void SendResponse(bool success) OVERRIDE;
538 base::WeakPtr<extensions::ExtensionMessageFilter> ipc_sender_;
541 scoped_refptr<const extensions::InfoMap> extension_info_map_;
544 // Base class for an extension function that runs asynchronously *relative to
545 // the browser's UI thread*.
546 class AsyncExtensionFunction : public UIThreadExtensionFunction {
548 AsyncExtensionFunction();
551 virtual ~AsyncExtensionFunction();
553 // Deprecated: Override UIThreadExtensionFunction and implement Run() instead.
555 // AsyncExtensionFunctions implement this method. Return true to indicate that
556 // nothing has gone wrong yet; SendResponse must be called later. Return false
557 // to respond immediately with an error.
558 virtual bool RunAsync() = 0;
560 // ValidationFailure override to match RunAsync().
561 static bool ValidationFailure(AsyncExtensionFunction* function);
564 virtual ResponseAction Run() OVERRIDE;
567 // A SyncExtensionFunction is an ExtensionFunction that runs synchronously
568 // *relative to the browser's UI thread*. Note that this has nothing to do with
569 // running synchronously relative to the extension process. From the extension
570 // process's point of view, the function is still asynchronous.
572 // This kind of function is convenient for implementing simple APIs that just
573 // need to interact with things on the browser UI thread.
574 class SyncExtensionFunction : public UIThreadExtensionFunction {
576 SyncExtensionFunction();
579 virtual ~SyncExtensionFunction();
581 // Deprecated: Override UIThreadExtensionFunction and implement Run() instead.
583 // SyncExtensionFunctions implement this method. Return true to respond
584 // immediately with success, false to respond immediately with an error.
585 virtual bool RunSync() = 0;
587 // ValidationFailure override to match RunSync().
588 static bool ValidationFailure(SyncExtensionFunction* function);
591 virtual ResponseAction Run() OVERRIDE;
594 class SyncIOThreadExtensionFunction : public IOThreadExtensionFunction {
596 SyncIOThreadExtensionFunction();
599 virtual ~SyncIOThreadExtensionFunction();
601 // Deprecated: Override IOThreadExtensionFunction and implement Run() instead.
603 // SyncIOThreadExtensionFunctions implement this method. Return true to
604 // respond immediately with success, false to respond immediately with an
606 virtual bool RunSync() = 0;
608 // ValidationFailure override to match RunSync().
609 static bool ValidationFailure(SyncIOThreadExtensionFunction* function);
612 virtual ResponseAction Run() OVERRIDE;
615 #endif // EXTENSIONS_BROWSER_EXTENSION_FUNCTION_H_