extensions/common/features/feature.h

   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_FEATURES_FEATURE_H_
   6 #define EXTENSIONS_COMMON_FEATURES_FEATURE_H_
   7
   8 #include <set>
   9 #include <string>
  10
  11 #include "base/values.h"
  12 #include "extensions/common/manifest.h"
  13
  14 class GURL;
  15
  16 namespace extensions {
  17
  18 class Extension;
  19
  20 // Represents a single feature accessible to an extension developer, such as a
  21 // top-level manifest key, a permission, or a programmatic API. A feature can
  22 // express requirements for where it can be accessed, and supports testing
  23 // support for those requirements. If platforms are not specified, then feature
  24 // is available on all platforms.
  25 class Feature {
  26  public:
  27   // The JavaScript contexts the feature is supported in.
  28   enum Context {
  29     UNSPECIFIED_CONTEXT,
  30
  31     // A context in a privileged extension process.
  32     BLESSED_EXTENSION_CONTEXT,
  33
  34     // A context in an unprivileged extension process.
  35     UNBLESSED_EXTENSION_CONTEXT,
  36
  37     // A context from a content script.
  38     CONTENT_SCRIPT_CONTEXT,
  39
  40     // A normal web page. This should have an associated URL matching pattern.
  41     WEB_PAGE_CONTEXT,
  42
  43     // A web page context which has been blessed by the user. Typically this
  44     // will be via the installation of a hosted app, so this may host an
  45     // extension. This is not affected by the URL matching pattern.
  46     BLESSED_WEB_PAGE_CONTEXT,
  47
  48     // A page within webui.
  49     WEBUI_CONTEXT,
  50
  51     // A context belonging to a service worker.
  52     SERVICE_WORKER_CONTEXT,
  53   };
  54
  55   // The platforms the feature is supported in.
  56   enum Platform {
  57     UNSPECIFIED_PLATFORM,
  58     CHROMEOS_PLATFORM,
  59     LINUX_PLATFORM,
  60     MACOSX_PLATFORM,
  61     WIN_PLATFORM
  62   };
  63
  64   // Whether a feature is available in a given situation or not, and if not,
  65   // why not.
  66   enum AvailabilityResult {
  67     IS_AVAILABLE,
  68     NOT_FOUND_IN_WHITELIST,
  69     INVALID_URL,
  70     INVALID_TYPE,
  71     INVALID_CONTEXT,
  72     INVALID_LOCATION,
  73     INVALID_PLATFORM,
  74     INVALID_MIN_MANIFEST_VERSION,
  75     INVALID_MAX_MANIFEST_VERSION,
  76     NOT_PRESENT,
  77     UNSUPPORTED_CHANNEL,
  78     FOUND_IN_BLACKLIST,
  79     MISSING_COMMAND_LINE_SWITCH,
  80   };
  81
  82   // Container for AvailabiltyResult that also exposes a user-visible error
  83   // message in cases where the feature is not available.
  84   class Availability {
  85    public:
  86     Availability(AvailabilityResult result, const std::string& message)
  87         : result_(result), message_(message) {}
  88
  89     AvailabilityResult result() const { return result_; }
  90     bool is_available() const { return result_ == IS_AVAILABLE; }
  91     const std::string& message() const { return message_; }
  92
  93    private:
  94     friend class SimpleFeature;
  95     friend class Feature;
  96
  97     const AvailabilityResult result_;
  98     const std::string message_;
  99   };
 100
 101   Feature();
 102   virtual ~Feature();
 103
 104   const std::string& name() const { return name_; }
 105   void set_name(const std::string& name) { name_ = name; }
 106   bool no_parent() const { return no_parent_; }
 107
 108   // Gets the platform the code is currently running on.
 109   static Platform GetCurrentPlatform();
 110
 111   // Tests whether this is an internal API or not.
 112   virtual bool IsInternal() const = 0;
 113
 114   // Returns true if the feature is available to be parsed into a new extension
 115   // manifest.
 116   Availability IsAvailableToManifest(const std::string& extension_id,
 117                                      Manifest::Type type,
 118                                      Manifest::Location location,
 119                                      int manifest_version) const {
 120     return IsAvailableToManifest(extension_id, type, location, manifest_version,
 121                                  GetCurrentPlatform());
 122   }
 123   virtual Availability IsAvailableToManifest(const std::string& extension_id,
 124                                              Manifest::Type type,
 125                                              Manifest::Location location,
 126                                              int manifest_version,
 127                                              Platform platform) const = 0;
 128
 129   // Returns true if the feature is available to |extension|.
 130   Availability IsAvailableToExtension(const Extension* extension) const;
 131
 132   // Returns true if the feature is available to be used in the specified
 133   // extension and context.
 134   Availability IsAvailableToContext(const Extension* extension,
 135                                     Context context,
 136                                     const GURL& url) const {
 137     return IsAvailableToContext(extension, context, url, GetCurrentPlatform());
 138   }
 139   virtual Availability IsAvailableToContext(const Extension* extension,
 140                                             Context context,
 141                                             const GURL& url,
 142                                             Platform platform) const = 0;
 143
 144   virtual std::string GetAvailabilityMessage(AvailabilityResult result,
 145                                              Manifest::Type type,
 146                                              const GURL& url,
 147                                              Context context) const = 0;
 148
 149   // Returns true if the feature is available to the current environment,
 150   // without needing to know information about an Extension or any other
 151   // contextual information. Typically used when the Feature is purely
 152   // configured by command line flags and/or Chrome channel.
 153   //
 154   // Generally try not to use this function. Even if you don't think a Feature
 155   // relies on an Extension now - maybe it will, one day, so if there's an
 156   // Extension available (or a runtime context, etc) then use the more targeted
 157   // method instead.
 158   Availability IsAvailableToEnvironment() const;
 159
 160   virtual bool IsIdInBlacklist(const std::string& extension_id) const = 0;
 161   virtual bool IsIdInWhitelist(const std::string& extension_id) const = 0;
 162
 163  protected:
 164   std::string name_;
 165   bool no_parent_;
 166 };
 167
 168 }  // namespace extensions
 169
 170 #endif  // EXTENSIONS_COMMON_FEATURES_FEATURE_H_