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
22namespace base {
23class DictionaryValue;
24class Value;
25}
26
27class GURL;
28
29namespace extensions {
30
31class Extension;
32class 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.
39class 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