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_ 167