blob: aa0ed038b0824d59223ff93bc34eb642f163c694 [file] [log] [blame]
// Copyright 2013 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#include <list>
#include <string>
#include "base/callback.h"
#include "base/compiler_specific.h"
#include "base/memory/ref_counted.h"
#include "base/memory/scoped_ptr.h"
#include "base/memory/weak_ptr.h"
#include "base/process/process.h"
#include "base/sequenced_task_runner_helpers.h"
#include "chrome/browser/extensions/extension_function_histogram_value.h"
#include "content/public/browser/browser_thread.h"
#include "content/public/common/console_message_level.h"
#include "extensions/browser/info_map.h"
#include "extensions/common/extension.h"
#include "ipc/ipc_message.h"
class ChromeRenderMessageFilter;
class ExtensionFunction;
class ExtensionFunctionDispatcher;
class UIThreadExtensionFunction;
class IOThreadExtensionFunction;
namespace base {
class ListValue;
class Value;
namespace content {
class BrowserContext;
class RenderViewHost;
class WebContents;
namespace extensions {
class QuotaLimitHeuristic;
#ifdef NDEBUG
if (!(test)) { \
bad_message_ = true; \
return false; \
} \
} while (0)
#else // NDEBUG
#endif // NDEBUG
#define EXTENSION_FUNCTION_ERROR(error) do { \
error_ = error; \
bad_message_ = true; \
return false; \
} while (0)
// Declares a callable extension function with the given |name|. You must also
// supply a unique |histogramvalue| used for histograms of extension function
// invocation (add new ones at the end of the enum in
// extension_function_histogram_value.h).
#define DECLARE_EXTENSION_FUNCTION(name, histogramvalue) \
public: static const char* function_name() { return name; } \
public: static extensions::functions::HistogramValue histogram_value() \
{ return extensions::functions::histogramvalue; }
// Traits that describe how ExtensionFunction should be deleted. This just calls
// the virtual "Destruct" method on ExtensionFunction, allowing derived classes
// to override the behavior.
struct ExtensionFunctionDeleteTraits {
static void Destruct(const ExtensionFunction* x);
// Abstract base class for extension functions the ExtensionFunctionDispatcher
// knows how to dispatch to.
class ExtensionFunction
: public base::RefCountedThreadSafe<ExtensionFunction,
ExtensionFunctionDeleteTraits> {
enum ResponseType {
// The function has succeeded.
// The function has failed.
// The input message is malformed.
typedef base::Callback<void(ResponseType type,
const base::ListValue& results,
const std::string& error)> ResponseCallback;
virtual UIThreadExtensionFunction* AsUIThreadExtensionFunction();
virtual IOThreadExtensionFunction* AsIOThreadExtensionFunction();
// Returns true if the function has permission to run.
// The default implementation is to check the Extension's permissions against
// what this function requires to run, but some APIs may require finer
// grained control, such as tabs.executeScript being allowed for active tabs.
// This will be run after the function has been set up but before Run().
virtual bool HasPermission();
// Execute the API. Clients should initialize the ExtensionFunction using
// SetArgs(), set_request_id(), and the other setters before calling this
// method. Derived classes should be ready to return GetResultList() and
// GetError() before returning from this function.
// Note that once Run() returns, dispatcher() can be NULL, so be sure to
// NULL-check.
virtual void Run();
// Gets whether quota should be applied to this individual function
// invocation. This is different to GetQuotaLimitHeuristics which is only
// invoked once and then cached.
// Returns false by default.
virtual bool ShouldSkipQuotaLimiting() const;
// Optionally adds one or multiple QuotaLimitHeuristic instances suitable for
// this function to |heuristics|. The ownership of the new QuotaLimitHeuristic
// instances is passed to the owner of |heuristics|.
// No quota limiting by default.
// Only called once per lifetime of the QuotaService.
virtual void GetQuotaLimitHeuristics(
extensions::QuotaLimitHeuristics* heuristics) const {}
// Called when the quota limit has been exceeded. The default implementation
// returns an error.
virtual void OnQuotaExceeded(const std::string& violation_error);
// Specifies the raw arguments to the function, as a JSON value.
virtual void SetArgs(const base::ListValue* args);
// Sets a single Value as the results of the function.
void SetResult(base::Value* result);
// Retrieves the results of the function as a ListValue.
const base::ListValue* GetResultList();
// Retrieves any error string from the function.
virtual const std::string GetError();
// Sets the function's error string.
virtual void SetError(const std::string& error);
// Specifies the name of the function.
void set_name(const std::string& name) { name_ = name; }
const std::string& name() const { return name_; }
void set_profile_id(void* profile_id) { profile_id_ = profile_id; }
void* profile_id() const { return profile_id_; }
void set_extension(const extensions::Extension* extension) {
extension_ = extension;
const extensions::Extension* GetExtension() const { return extension_.get(); }
const std::string& extension_id() const { return extension_->id(); }
void set_request_id(int request_id) { request_id_ = request_id; }
int request_id() { return request_id_; }
void set_source_url(const GURL& source_url) { source_url_ = source_url; }
const GURL& source_url() { return source_url_; }
void set_has_callback(bool has_callback) { has_callback_ = has_callback; }
bool has_callback() { return has_callback_; }
void set_include_incognito(bool include) { include_incognito_ = include; }
bool include_incognito() const { return include_incognito_; }
void set_user_gesture(bool user_gesture) { user_gesture_ = user_gesture; }
bool user_gesture() const { return user_gesture_; }
void set_histogram_value(
extensions::functions::HistogramValue histogram_value) {
histogram_value_ = histogram_value; }
extensions::functions::HistogramValue histogram_value() const {
return histogram_value_; }
void set_response_callback(const ResponseCallback& callback) {
response_callback_ = callback;
friend struct ExtensionFunctionDeleteTraits;
virtual ~ExtensionFunction();
// Helper method for ExtensionFunctionDeleteTraits. Deletes this object.
virtual void Destruct() const = 0;
// Derived classes should implement this method to do their work and return
// success/failure.
virtual bool RunImpl() = 0;
// Sends the result back to the extension.
virtual void SendResponse(bool success) = 0;
// Common implementation for SendResponse.
void SendResponseImpl(bool success);
// Return true if the argument to this function at |index| was provided and
// is non-null.
bool HasOptionalArgument(size_t index);
// Id of this request, used to map the response back to the caller.
int request_id_;
// The id of the profile of this function's extension.
void* profile_id_;
// The extension that called this function.
scoped_refptr<const extensions::Extension> extension_;
// The name of this function.
std::string name_;
// The URL of the frame which is making this request
GURL source_url_;
// True if the js caller provides a callback function to receive the response
// of this call.
bool has_callback_;
// True if this callback should include information from incognito contexts
// even if our profile_ is non-incognito. Note that in the case of a "split"
// mode extension, this will always be false, and we will limit access to
// data from within the same profile_ (either incognito or not).
bool include_incognito_;
// True if the call was made in response of user gesture.
bool user_gesture_;
// The arguments to the API. Only non-null if argument were specified.
scoped_ptr<base::ListValue> args_;
// The results of the API. This should be populated by the derived class
// before SendResponse() is called.
scoped_ptr<base::ListValue> results_;
// Any detailed error from the API. This should be populated by the derived
// class before Run() returns.
std::string error_;
// Any class that gets a malformed message should set this to true before
// returning. Usually we want to kill the message sending process.
bool bad_message_;
// The sample value to record with the histogram API when the function
// is invoked.
extensions::functions::HistogramValue histogram_value_;
// The callback to run once the function has done execution.
ResponseCallback response_callback_;
// Extension functions that run on the UI thread. Most functions fall into
// this category.
class UIThreadExtensionFunction : public ExtensionFunction {
// TODO(yzshen): We should be able to remove this interface now that we
// support overriding the response callback.
// A delegate for use in testing, to intercept the call to SendResponse.
class DelegateForTests {
virtual void OnSendResponse(UIThreadExtensionFunction* function,
bool success,
bool bad_message) = 0;
virtual UIThreadExtensionFunction* AsUIThreadExtensionFunction() OVERRIDE;
void set_test_delegate(DelegateForTests* delegate) {
delegate_ = delegate;
// Called when a message was received.
// Should return true if it processed the message.
virtual bool OnMessageReceivedFromRenderView(const IPC::Message& message);
// Set the browser context which contains the extension that has originated
// this function call.
void set_context(content::BrowserContext* context) { context_ = context; }
content::BrowserContext* context() const { return context_; }
void SetRenderViewHost(content::RenderViewHost* render_view_host);
content::RenderViewHost* render_view_host() const {
return render_view_host_;
void set_dispatcher(
const base::WeakPtr<ExtensionFunctionDispatcher>& dispatcher) {
dispatcher_ = dispatcher;
ExtensionFunctionDispatcher* dispatcher() const {
return dispatcher_.get();
// Gets the "current" web contents if any. If there is no associated web
// contents then defaults to the foremost one.
virtual content::WebContents* GetAssociatedWebContents();
// Emits a message to the extension's devtools console.
void WriteToConsole(content::ConsoleMessageLevel level,
const std::string& message);
friend struct content::BrowserThread::DeleteOnThread<
friend class base::DeleteHelper<UIThreadExtensionFunction>;
virtual ~UIThreadExtensionFunction();
virtual void SendResponse(bool success) OVERRIDE;
// The dispatcher that will service this extension function call.
base::WeakPtr<ExtensionFunctionDispatcher> dispatcher_;
// The RenderViewHost we will send responses too.
content::RenderViewHost* render_view_host_;
// The content::BrowserContext of this function's extension.
content::BrowserContext* context_;
class RenderViewHostTracker;
virtual void Destruct() const OVERRIDE;
scoped_ptr<RenderViewHostTracker> tracker_;
DelegateForTests* delegate_;
// Extension functions that run on the IO thread. This type of function avoids
// a roundtrip to and from the UI thread (because communication with the
// extension process happens on the IO thread). It's intended to be used when
// performance is critical (e.g. the webRequest API which can block network
// requests). Generally, UIThreadExtensionFunction is more appropriate and will
// be easier to use and interface with the rest of the browser.
class IOThreadExtensionFunction : public ExtensionFunction {
virtual IOThreadExtensionFunction* AsIOThreadExtensionFunction() OVERRIDE;
void set_ipc_sender(base::WeakPtr<ChromeRenderMessageFilter> ipc_sender,
int routing_id) {
ipc_sender_ = ipc_sender;
routing_id_ = routing_id;
base::WeakPtr<ChromeRenderMessageFilter> ipc_sender_weak() const {
return ipc_sender_;
int routing_id() const { return routing_id_; }
void set_extension_info_map(const extensions::InfoMap* extension_info_map) {
extension_info_map_ = extension_info_map;
const extensions::InfoMap* extension_info_map() const {
return extension_info_map_.get();
friend struct content::BrowserThread::DeleteOnThread<
friend class base::DeleteHelper<IOThreadExtensionFunction>;
virtual ~IOThreadExtensionFunction();
virtual void Destruct() const OVERRIDE;
virtual void SendResponse(bool success) OVERRIDE;
base::WeakPtr<ChromeRenderMessageFilter> ipc_sender_;
int routing_id_;
scoped_refptr<const extensions::InfoMap> extension_info_map_;
// Base class for an extension function that runs asynchronously *relative to
// the browser's UI thread*.
class AsyncExtensionFunction : public UIThreadExtensionFunction {
virtual ~AsyncExtensionFunction();
// A SyncExtensionFunction is an ExtensionFunction that runs synchronously
// *relative to the browser's UI thread*. Note that this has nothing to do with
// running synchronously relative to the extension process. From the extension
// process's point of view, the function is still asynchronous.
// This kind of function is convenient for implementing simple APIs that just
// need to interact with things on the browser UI thread.
class SyncExtensionFunction : public UIThreadExtensionFunction {
virtual void Run() OVERRIDE;
virtual ~SyncExtensionFunction();
class SyncIOThreadExtensionFunction : public IOThreadExtensionFunction {
virtual void Run() OVERRIDE;
virtual ~SyncIOThreadExtensionFunction();