Home | History | Annotate | Download | only in common 
      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, 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 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   // 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, 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, 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_
    174