extensions/common/extension_api.h

   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.
   4
   5 #ifndef EXTENSIONS_COMMON_EXTENSION_API_H_
   6 #define EXTENSIONS_COMMON_EXTENSION_API_H_
   7
   8 #include <map>
   9 #include <string>
  10
  11 #include "base/basictypes.h"
  12 #include "base/gtest_prod_util.h"
  13 #include "base/memory/linked_ptr.h"
  14 #include "base/memory/scoped_ptr.h"
  15 #include "base/memory/singleton.h"
  16 #include "base/strings/string_piece.h"
  17 #include "base/values.h"
  18 #include "extensions/common/features/feature.h"
  19 #include "extensions/common/features/feature_provider.h"
  20 #include "extensions/common/url_pattern_set.h"
  21
  22 namespace base {
  23 class DictionaryValue;
  24 class Value;
  25 }
  26
  27 class GURL;
  28
  29 namespace extensions {
  30
  31 class Extension;
  32 class Feature;
  33
  34 // C++ Wrapper for the JSON API definitions in chrome/common/extensions/api/.
  35 //
  36 // WARNING: This class is accessed on multiple threads in the browser process
  37 // (see ExtensionFunctionDispatcher). No state should be modified after
  38 // construction.
  39 class ExtensionAPI {
  40  public:
  41   // Returns a single shared instance of this class. This is the typical use
  42   // case in Chrome.
  43   //
  44   // TODO(aa): Make this const to enforce thread-safe usage.
  45   static ExtensionAPI* GetSharedInstance();
  46
  47   // Creates a new instance configured the way ExtensionAPI typically is in
  48   // Chrome. Use the default constructor to get a clean instance.
  49   static ExtensionAPI* CreateWithDefaultConfiguration();
  50
  51   // Splits a name like "permission:bookmark" into ("permission", "bookmark").
  52   // The first part refers to a type of feature, for example "manifest",
  53   // "permission", or "api". The second part is the full name of the feature.
  54   //
  55   // TODO(kalman): ExtensionAPI isn't really the right place for this function.
  56   static void SplitDependencyName(const std::string& full_name,
  57                                   std::string* feature_type,
  58                                   std::string* feature_name);
  59
  60   class OverrideSharedInstanceForTest {
  61    public:
  62     explicit OverrideSharedInstanceForTest(ExtensionAPI* testing_api);
  63     ~OverrideSharedInstanceForTest();
  64
  65    private:
  66     ExtensionAPI* original_api_;
  67   };
  68
  69   // Creates a completely clean instance. Configure using RegisterSchema() and
  70   // RegisterDependencyProvider before use.
  71   ExtensionAPI();
  72   virtual ~ExtensionAPI();
  73
  74   // Add a (non-generated) API schema resource.
  75   void RegisterSchemaResource(const std::string& api_name, int resource_id);
  76
  77   // Add a FeatureProvider for APIs. The features are used to specify
  78   // dependencies and constraints on the availability of APIs.
  79   void RegisterDependencyProvider(const std::string& name,
  80                                   const FeatureProvider* provider);
  81
  82   // Returns true if the API item called |api_full_name| and all of its
  83   // dependencies are available in |context|.
  84   //
  85   // |api_full_name| can be either a namespace name (like "bookmarks") or a
  86   // member name (like "bookmarks.create").
  87   //
  88   // Depending on the configuration of |api| (in _api_features.json), either
  89   // |extension| or |url| (or both) may determine its availability, but this is
  90   // up to the configuration of the individual feature.
  91   //
  92   // TODO(kalman): This is just an unnecessary combination of finding a Feature
  93   // then calling Feature::IsAvailableToContext(..) on it. Just provide that
  94   // FindFeature function and let callers compose if they want.
  95   Feature::Availability IsAvailable(const std::string& api_full_name,
  96                                     const Extension* extension,
  97                                     Feature::Context context,
  98                                     const GURL& url);
  99
 100   // Determines whether an API, or any parts of that API, are available in
 101   // |context|.
 102   bool IsAnyFeatureAvailableToContext(const Feature& api,
 103                                       const Extension* extension,
 104                                       Feature::Context context,
 105                                       const GURL& url);
 106
 107   // Returns true if |name| is available to |extension| in any untrusted
 108   // extension context, such as content scripts, iframes, or web pages.
 109   bool IsAvailableInUntrustedContext(const std::string& name,
 110                                      const Extension* extension);
 111
 112   // Returns true if |name| is available to WebUI contexts on |url|.
 113   bool IsAvailableToWebUI(const std::string& name, const GURL& url);
 114
 115   // Gets the schema for the extension API with namespace |full_name|.
 116   // Ownership remains with this object.
 117   const base::DictionaryValue* GetSchema(const std::string& full_name);
 118
 119   // Splits a full name from the extension API into its API and child name
 120   // parts. Some examples:
 121   //
 122   // "bookmarks.create" -> ("bookmarks", "create")
 123   // "experimental.input.ui.cursorUp" -> ("experimental.input.ui", "cursorUp")
 124   // "storage.sync.set" -> ("storage", "sync.get")
 125   // "<unknown-api>.monkey" -> ("", "")
 126   //
 127   // The |child_name| parameter can be be NULL if you don't need that part.
 128   std::string GetAPINameFromFullName(const std::string& full_name,
 129                                      std::string* child_name);
 130
 131   // Gets a feature from any dependency provider registered with ExtensionAPI.
 132   // Returns NULL if the feature could not be found.
 133   Feature* GetFeatureDependency(const std::string& dependency_name);
 134
 135  private:
 136   FRIEND_TEST_ALL_PREFIXES(ExtensionAPITest, DefaultConfigurationFeatures);
 137   FRIEND_TEST_ALL_PREFIXES(ExtensionAPITest, TypesHaveNamespace);
 138   friend struct DefaultSingletonTraits<ExtensionAPI>;
 139
 140   void InitDefaultConfiguration();
 141
 142   bool default_configuration_initialized_;
 143
 144   // Loads a schema.
 145   void LoadSchema(const std::string& name, const base::StringPiece& schema);
 146
 147   // Map from each API that hasn't been loaded yet to the schema which defines
 148   // it. Note that there may be multiple APIs per schema.
 149   typedef std::map<std::string, int> UnloadedSchemaMap;
 150   UnloadedSchemaMap unloaded_schemas_;
 151
 152   // Schemas for each namespace.
 153   typedef std::map<std::string, linked_ptr<const base::DictionaryValue> >
 154         SchemaMap;
 155   SchemaMap schemas_;
 156
 157   // FeatureProviders used for resolving dependencies.
 158   typedef std::map<std::string, const FeatureProvider*> FeatureProviderMap;
 159   FeatureProviderMap dependency_providers_;
 160
 161   DISALLOW_COPY_AND_ASSIGN(ExtensionAPI);
 162 };
 163
 164 }  // namespace extensions
 165
 166 #endif  // EXTENSIONS_COMMON_EXTENSION_API_H_