extensions/common/manifest_handler.h

   1 // Copyright (c) 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_MANIFEST_HANDLER_H_
   6 #define EXTENSIONS_COMMON_MANIFEST_HANDLER_H_
   7
   8 #include <set>
   9 #include <string>
  10 #include <vector>
  11
  12 #include "base/lazy_instance.h"
  13 #include "base/memory/linked_ptr.h"
  14 #include "base/strings/string16.h"
  15 #include "extensions/common/manifest.h"
  16
  17 namespace extensions {
  18 class Extension;
  19 class ManifestPermission;
  20 class ManifestPermissionSet;
  21
  22 // An interface for clients that recognize and parse keys in extension
  23 // manifests.
  24 class ManifestHandler {
  25  public:
  26   ManifestHandler();
  27   virtual ~ManifestHandler();
  28
  29   // Attempts to parse the extension's manifest.
  30   // Returns true on success or false on failure; if false, |error| will
  31   // be set to a failure message.
  32   virtual bool Parse(Extension* extension, base::string16* error) = 0;
  33
  34   // Validate that files associated with this manifest key exist.
  35   // Validation takes place after parsing. May also append a series of
  36   // warning messages to |warnings|.
  37   //
  38   // Otherwise, returns false, and a description of the error is
  39   // returned in |error|.
  40   // TODO(yoz): Change error to base::string16. See crbug.com/71980.
  41   virtual bool Validate(const Extension* extension,
  42                         std::string* error,
  43                         std::vector<InstallWarning>* warnings) const;
  44
  45   // If false (the default), only parse the manifest if a registered
  46   // key is present in the manifest. If true, always attempt to parse
  47   // the manifest for this extension type, even if no registered keys
  48   // are present. This allows specifying a default parsed value for
  49   // extensions that don't declare our key in the manifest.
  50   // TODO(yoz): Use Feature availability instead.
  51   virtual bool AlwaysParseForType(Manifest::Type type) const;
  52
  53   // Same as AlwaysParseForType, but for Validate instead of Parse.
  54   virtual bool AlwaysValidateForType(Manifest::Type type) const;
  55
  56   // The list of keys that, if present, should be parsed before calling our
  57   // Parse (typically, because our Parse needs to read those keys).
  58   // Defaults to empty.
  59   virtual const std::vector<std::string> PrerequisiteKeys() const;
  60
  61   // Associate us with our keys() in the manifest. A handler can register
  62   // for multiple keys. The global registry takes ownership of this;
  63   // if it has an existing handler for |key|, it replaces it with this.
  64   // Manifest handlers must be registered at process startup in
  65   // common_manifest_handlers.cc or chrome_manifest_handlers.cc:
  66   // (new MyManifestHandler)->Register();
  67   void Register();
  68
  69   // Creates a |ManifestPermission| instance for the given manifest key |name|.
  70   // The returned permission does not contain any permission data, so this
  71   // method is usually used before calling |FromValue| or |Read|. Returns
  72   // |NULL| if the manifest handler does not support custom permissions.
  73   virtual ManifestPermission* CreatePermission();
  74
  75   // Creates a |ManifestPermission| instance containing the initial set of
  76   // required manifest permissions for the given |extension|. Returns |NULL| if
  77   // the manifest handler does not support custom permissions or if there was
  78   // no manifest key in the extension manifest for this handler.
  79   virtual ManifestPermission* CreateInitialRequiredPermission(
  80       const Extension* extension);
  81
  82   // Calling FinalizeRegistration indicates that there are no more
  83   // manifest handlers to be registered.
  84   static void FinalizeRegistration();
  85
  86   static bool IsRegistrationFinalized();
  87
  88   // Call Parse on all registered manifest handlers that should parse
  89   // this extension.
  90   static bool ParseExtension(Extension* extension, base::string16* error);
  91
  92   // Call Validate on all registered manifest handlers for this extension.
  93   static bool ValidateExtension(const Extension* extension,
  94                                 std::string* error,
  95                                 std::vector<InstallWarning>* warnings);
  96
  97   // Calls |CreatePermission| on the manifest handler for |key|. Returns |NULL|
  98   // if there is no manifest handler for |key| or if the manifest handler for
  99   // |key| does not support custom permissions.
 100   static ManifestPermission* CreatePermission(const std::string& key);
 101
 102   // Calls |CreateInitialRequiredPermission| on all registered manifest handlers
 103   // and adds the returned permissions to |permission_set|. Note this should be
 104   // called after all manifest data elements have been read, parsed and stored
 105   // in the manifest data property of |extension|, as manifest handlers need
 106   // access to their manifest data to initialize their required manifest
 107   // permission.
 108   static void AddExtensionInitialRequiredPermissions(
 109       const Extension* extension, ManifestPermissionSet* permission_set);
 110
 111  protected:
 112   // A convenience method for handlers that only register for 1 key,
 113   // so that they can define keys() { return SingleKey(kKey); }
 114   static const std::vector<std::string> SingleKey(const std::string& key);
 115
 116  private:
 117   // The keys to register us for (in Register).
 118   virtual const std::vector<std::string> Keys() const = 0;
 119 };
 120
 121 // The global registry for manifest handlers.
 122 class ManifestHandlerRegistry {
 123  private:
 124   friend class ManifestHandler;
 125   friend class ScopedTestingManifestHandlerRegistry;
 126   friend struct base::DefaultLazyInstanceTraits<ManifestHandlerRegistry>;
 127
 128   ManifestHandlerRegistry();
 129   ~ManifestHandlerRegistry();
 130
 131   void Finalize();
 132
 133   void RegisterManifestHandler(const std::string& key,
 134                                linked_ptr<ManifestHandler> handler);
 135   bool ParseExtension(Extension* extension, base::string16* error);
 136   bool ValidateExtension(const Extension* extension,
 137                          std::string* error,
 138                          std::vector<InstallWarning>* warnings);
 139
 140   ManifestPermission* CreatePermission(const std::string& key);
 141
 142   void AddExtensionInitialRequiredPermissions(
 143       const Extension* extension,
 144       ManifestPermissionSet* permission_set);
 145
 146   // Overrides the current global ManifestHandlerRegistry with
 147   // |registry|, returning the current one.
 148   static ManifestHandlerRegistry* SetForTesting(
 149       ManifestHandlerRegistry* new_registry);
 150
 151   typedef std::map<std::string, linked_ptr<ManifestHandler> >
 152       ManifestHandlerMap;
 153   typedef std::map<ManifestHandler*, int> ManifestHandlerPriorityMap;
 154
 155   // Puts the manifest handlers in order such that each handler comes after
 156   // any handlers for their PrerequisiteKeys. If there is no handler for
 157   // a prerequisite key, that dependency is simply ignored.
 158   // CHECKs that there are no manifest handlers with circular dependencies.
 159   void SortManifestHandlers();
 160
 161   // All registered manifest handlers.
 162   ManifestHandlerMap handlers_;
 163
 164   // The priority for each manifest handler. Handlers with lower priority
 165   // values are evaluated first.
 166   ManifestHandlerPriorityMap priority_map_;
 167
 168   bool is_finalized_;
 169 };
 170
 171 }  // namespace extensions
 172
 173 #endif  // EXTENSIONS_COMMON_MANIFEST_HANDLER_H_