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 <memory>
10#include <string>
11
12#include "base/gtest_prod_util.h"
13#include "base/macros.h"
14#include "base/memory/singleton.h"
15#include "base/strings/string_piece.h"
16#include "base/values.h"
17#include "extensions/common/features/feature.h"
18#include "extensions/common/features/feature_provider.h"
19#include "extensions/common/url_pattern_set.h"
20
21namespace base {
22class DictionaryValue;
23}
24
25class GURL;
26
27namespace extensions {
28
29class Extension;
30class ExtensionsClient;
31class Feature;
32
33// Used when testing Feature availability to specify whether feature aliases
34// should be ignored or not - i.e. if a feature exposed only through an alias
35// should be considered available.
36enum class CheckAliasStatus {
37 // Includes aliases in an availability check.
38 ALLOWED,
39 // Ignores aliases during an availability check.
40 NOT_ALLOWED
41};
42
43// C++ Wrapper for the JSON API definitions in chrome/common/extensions/api/.
44//
45// WARNING: This class is accessed on multiple threads in the browser process
46// (see ExtensionFunctionDispatcher). No state should be modified after
47// construction.
48class ExtensionAPI {
49 public:
50 // Returns a single shared instance of this class. This is the typical use
51 // case in Chrome.
52 //
53 // TODO(aa): Make this const to enforce thread-safe usage.
54 static ExtensionAPI* GetSharedInstance();
55
56 // Creates a new instance configured the way ExtensionAPI typically is in
57 // Chrome. Use the default constructor to get a clean instance.
58 static ExtensionAPI* CreateWithDefaultConfiguration();
59
60 // Splits a name like "permission:bookmark" into ("permission", "bookmark").
61 // The first part refers to a type of feature, for example "manifest",
62 // "permission", or "api". The second part is the full name of the feature.
63 //
64 // TODO(kalman): ExtensionAPI isn't really the right place for this function.
65 static void SplitDependencyName(const std::string& full_name,
66 std::string* feature_type,
67 std::string* feature_name);
68
69 class OverrideSharedInstanceForTest {
70 public:
71 explicit OverrideSharedInstanceForTest(ExtensionAPI* testing_api);
72 ~OverrideSharedInstanceForTest();
73
74 private:
75 ExtensionAPI* original_api_;
76 };
77
78 // Creates a completely clean instance. Configure using
79 // RegisterDependencyProvider before use.
80 ExtensionAPI();
81 virtual ~ExtensionAPI();
82
83 // Add a FeatureProvider for APIs. The features are used to specify
84 // dependencies and constraints on the availability of APIs.
85 void RegisterDependencyProvider(const std::string& name,
86 const FeatureProvider* provider);
87
88 // Returns true if the API item called |api_full_name| and all of its
89 // dependencies are available in |context|.
90 //
91 // |api_full_name| can be either a namespace name (like "bookmarks") or a
92 // member name (like "bookmarks.create").
93 //
94 // Depending on the configuration of |api| (in _api_features.json), either
95 // |extension| or |url| (or both) may determine its availability, but this is
96 // up to the configuration of the individual feature.
97 //
98 // |check_alias| determines whether it should be tested whether the API
99 // is available through an alias.
100 //
101 // TODO(kalman): This is just an unnecessary combination of finding a Feature
102 // then calling Feature::IsAvailableToContext(..) on it. Just provide that
103 // FindFeature function and let callers compose if they want.
104 Feature::Availability IsAvailable(const std::string& api_full_name,
105 const Extension* extension,
106 Feature::Context context,
107 const GURL& url,
108 CheckAliasStatus check_alias);
109
110 // Determines whether an API, or any parts of that API, can be exposed to
111 // |context|.
112 //
113 // |check_alias| determines whether it should be tested whether the API
114 // is available through an alias.
115 //
116 bool IsAnyFeatureAvailableToContext(const Feature& api,
117 const Extension* extension,
118 Feature::Context context,
119 const GURL& url,
120 CheckAliasStatus check_alias);
121
122 // Gets the StringPiece for the schema specified by |api_name|.
123 base::StringPiece GetSchemaStringPiece(const std::string& api_name);
124
125 // Gets the schema for the extension API with namespace |full_name|.
126 // Ownership remains with this object.
127 // TODO(devlin): Now that we use GetSchemaStringPiece() in the renderer, we
128 // may not really need this anymore.
129 const base::DictionaryValue* GetSchema(const std::string& full_name);
130
131 // Splits a full name from the extension API into its API and child name
132 // parts. Some examples:
133 //
134 // "bookmarks.create" -> ("bookmarks", "create")
135 // "experimental.input.ui.cursorUp" -> ("experimental.input.ui", "cursorUp")
136 // "storage.sync.set" -> ("storage", "sync.get")
137 // "<unknown-api>.monkey" -> ("", "")
138 //
139 // The |child_name| parameter can be be NULL if you don't need that part.
140 std::string GetAPINameFromFullName(const std::string& full_name,
141 std::string* child_name);
142
143 // Gets a feature from any dependency provider registered with ExtensionAPI.
144 // Returns NULL if the feature could not be found.
145 const Feature* GetFeatureDependency(const std::string& dependency_name);
146
147 private:
148 FRIEND_TEST_ALL_PREFIXES(ExtensionAPITest, DefaultConfigurationFeatures);
149 friend struct base::DefaultSingletonTraits<ExtensionAPI>;
150
151 void InitDefaultConfiguration();
152
153 // Returns true if there exists an API with |name|. Declared virtual for
154 // testing purposes.
155 virtual bool IsKnownAPI(const std::string& name, ExtensionsClient* client);
156
157 // Checks if |full_name| is available to provided context and extension under
158 // associated API's alias name.
159 Feature::Availability IsAliasAvailable(const std::string& full_name,
160 const Feature& feature,
161 const Extension* extension,
162 Feature::Context context,
163 const GURL& url);
164
165 bool default_configuration_initialized_;
166
167 // Loads a schema.
168 void LoadSchema(const std::string& name, const base::StringPiece& schema);
169
170 // Schemas for each namespace.
171 using SchemaMap =
172 std::map<std::string, std::unique_ptr<const base::DictionaryValue>>;
173 SchemaMap schemas_;
174
175 using StringPieceMap = std::map<std::string, base::StringPiece>;
176 StringPieceMap schema_strings_;
177
178 // FeatureProviders used for resolving dependencies.
179 typedef std::map<std::string, const FeatureProvider*> FeatureProviderMap;
180 FeatureProviderMap dependency_providers_;
181
182 DISALLOW_COPY_AND_ASSIGN(ExtensionAPI);
183};
184
185} // namespace extensions
186
187#endif // EXTENSIONS_COMMON_EXTENSION_API_H_
188