extensions/common/user_script.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_USER_SCRIPT_H_
   6 #define EXTENSIONS_COMMON_USER_SCRIPT_H_
   7
   8 #include <string>
   9 #include <vector>
  10
  11 #include "base/basictypes.h"
  12 #include "base/files/file_path.h"
  13 #include "base/strings/string_piece.h"
  14 #include "extensions/common/host_id.h"
  15 #include "extensions/common/url_pattern.h"
  16 #include "extensions/common/url_pattern_set.h"
  17 #include "url/gurl.h"
  18
  19 namespace base {
  20 class Pickle;
  21 class PickleIterator;
  22 }
  23
  24 namespace extensions {
  25
  26 // Represents a user script, either a standalone one, or one that is part of an
  27 // extension.
  28 class UserScript {
  29  public:
  30   // The file extension for standalone user scripts.
  31   static const char kFileExtension[];
  32
  33   static int GenerateUserScriptID();
  34
  35   // Check if a URL should be treated as a user script and converted to an
  36   // extension.
  37   static bool IsURLUserScript(const GURL& url, const std::string& mime_type);
  38
  39   // Get the valid user script schemes for the current process. If
  40   // canExecuteScriptEverywhere is true, this will return ALL_SCHEMES.
  41   static int ValidUserScriptSchemes(bool canExecuteScriptEverywhere = false);
  42
  43   // TODO(rdevlin.cronin) This and RunLocataion don't really belong here, since
  44   // they are used for more than UserScripts (e.g., tabs.executeScript()).
  45   // The type of injected script.
  46   enum InjectionType {
  47     // A content script specified in the extension's manifest.
  48     CONTENT_SCRIPT,
  49     // A script injected via, e.g. tabs.executeScript().
  50     PROGRAMMATIC_SCRIPT
  51   };
  52   // The last type of injected script; used for enum verification in IPC.
  53   // Update this if you add more injected script types!
  54   static const InjectionType INJECTION_TYPE_LAST = PROGRAMMATIC_SCRIPT;
  55
  56   // Locations that user scripts can be run inside the document.
  57   // The three run locations must strictly follow each other in both load order
  58   // (i.e., start *always* comes before end) and numerically, as we use
  59   // arithmetic checking (e.g., curr == last + 1). So, no bitmasks here!!
  60   enum RunLocation {
  61     UNDEFINED,
  62     DOCUMENT_START,  // After the documentElement is created, but before
  63                      // anything else happens.
  64     DOCUMENT_END,  // After the entire document is parsed. Same as
  65                    // DOMContentLoaded.
  66     DOCUMENT_IDLE,  // Sometime after DOMContentLoaded, as soon as the document
  67                     // is "idle". Currently this uses the simple heuristic of:
  68                     // min(DOM_CONTENT_LOADED + TIMEOUT, ONLOAD), but no
  69                     // particular injection point is guaranteed.
  70     RUN_DEFERRED,  // The user script's injection was deferred for permissions
  71                    // reasons, and was executed at a later time.
  72     BROWSER_DRIVEN,  // The user script will be injected when triggered by an
  73                      // IPC in the browser process.
  74     RUN_LOCATION_LAST  // Leave this as the last item.
  75   };
  76
  77   // Holds actual script file info.
  78   class File {
  79    public:
  80     File(const base::FilePath& extension_root,
  81          const base::FilePath& relative_path,
  82          const GURL& url);
  83     File();
  84     ~File();
  85
  86     const base::FilePath& extension_root() const { return extension_root_; }
  87     const base::FilePath& relative_path() const { return relative_path_; }
  88
  89     const GURL& url() const { return url_; }
  90     void set_url(const GURL& url) { url_ = url; }
  91
  92     // If external_content_ is set returns it as content otherwise it returns
  93     // content_
  94     const base::StringPiece GetContent() const {
  95       if (external_content_.data())
  96         return external_content_;
  97       else
  98         return content_;
  99     }
 100     void set_external_content(const base::StringPiece& content) {
 101       external_content_ = content;
 102     }
 103     void set_content(const base::StringPiece& content) {
 104       content_.assign(content.begin(), content.end());
 105     }
 106
 107     // Serialization support. The content and FilePath members will not be
 108     // serialized!
 109     void Pickle(base::Pickle* pickle) const;
 110     void Unpickle(const base::Pickle& pickle, base::PickleIterator* iter);
 111
 112    private:
 113     // Where the script file lives on the disk. We keep the path split so that
 114     // it can be localized at will.
 115     base::FilePath extension_root_;
 116     base::FilePath relative_path_;
 117
 118     // The url to this scipt file.
 119     GURL url_;
 120
 121     // The script content. It can be set to either loaded_content_ or
 122     // externally allocated string.
 123     base::StringPiece external_content_;
 124
 125     // Set when the content is loaded by LoadContent
 126     std::string content_;
 127   };
 128
 129   typedef std::vector<File> FileList;
 130
 131   // Type of a API consumer instance that user scripts will be injected on.
 132   enum ConsumerInstanceType { TAB, WEBVIEW };
 133
 134   // Constructor. Default the run location to document end, which is like
 135   // Greasemonkey and probably more useful for typical scripts.
 136   UserScript();
 137   ~UserScript();
 138
 139   const std::string& name_space() const { return name_space_; }
 140   void set_name_space(const std::string& name_space) {
 141     name_space_ = name_space;
 142   }
 143
 144   const std::string& name() const { return name_; }
 145   void set_name(const std::string& name) { name_ = name; }
 146
 147   const std::string& version() const { return version_; }
 148   void set_version(const std::string& version) {
 149     version_ = version;
 150   }
 151
 152   const std::string& description() const { return description_; }
 153   void set_description(const std::string& description) {
 154     description_ = description;
 155   }
 156
 157   // The place in the document to run the script.
 158   RunLocation run_location() const { return run_location_; }
 159   void set_run_location(RunLocation location) { run_location_ = location; }
 160
 161   // Whether to emulate greasemonkey when running this script.
 162   bool emulate_greasemonkey() const { return emulate_greasemonkey_; }
 163   void set_emulate_greasemonkey(bool val) { emulate_greasemonkey_ = val; }
 164
 165   // Whether to match all frames, or only the top one.
 166   bool match_all_frames() const { return match_all_frames_; }
 167   void set_match_all_frames(bool val) { match_all_frames_ = val; }
 168
 169   // Whether to match about:blank and about:srcdoc.
 170   bool match_about_blank() const { return match_about_blank_; }
 171   void set_match_about_blank(bool val) { match_about_blank_ = val; }
 172
 173   // The globs, if any, that determine which pages this script runs against.
 174   // These are only used with "standalone" Greasemonkey-like user scripts.
 175   const std::vector<std::string>& globs() const { return globs_; }
 176   void add_glob(const std::string& glob) { globs_.push_back(glob); }
 177   void clear_globs() { globs_.clear(); }
 178   const std::vector<std::string>& exclude_globs() const {
 179     return exclude_globs_;
 180   }
 181   void add_exclude_glob(const std::string& glob) {
 182     exclude_globs_.push_back(glob);
 183   }
 184   void clear_exclude_globs() { exclude_globs_.clear(); }
 185
 186   // The URLPatterns, if any, that determine which pages this script runs
 187   // against.
 188   const URLPatternSet& url_patterns() const { return url_set_; }
 189   void add_url_pattern(const URLPattern& pattern);
 190   const URLPatternSet& exclude_url_patterns() const {
 191     return exclude_url_set_;
 192   }
 193   void add_exclude_url_pattern(const URLPattern& pattern);
 194
 195   // List of js scripts for this user script
 196   FileList& js_scripts() { return js_scripts_; }
 197   const FileList& js_scripts() const { return js_scripts_; }
 198
 199   // List of css scripts for this user script
 200   FileList& css_scripts() { return css_scripts_; }
 201   const FileList& css_scripts() const { return css_scripts_; }
 202
 203   const std::string& extension_id() const { return host_id_.id(); }
 204
 205   const HostID& host_id() const { return host_id_; }
 206   void set_host_id(const HostID& host_id) { host_id_ = host_id; }
 207
 208   const ConsumerInstanceType& consumer_instance_type() const {
 209     return consumer_instance_type_;
 210   }
 211   void set_consumer_instance_type(
 212       const ConsumerInstanceType& consumer_instance_type) {
 213     consumer_instance_type_ = consumer_instance_type;
 214   }
 215
 216   int id() const { return user_script_id_; }
 217   void set_id(int id) { user_script_id_ = id; }
 218
 219   bool is_incognito_enabled() const { return incognito_enabled_; }
 220   void set_incognito_enabled(bool enabled) { incognito_enabled_ = enabled; }
 221
 222   bool is_standalone() const { return extension_id().empty(); }
 223
 224   // Returns true if the script should be applied to the specified URL, false
 225   // otherwise.
 226   bool MatchesURL(const GURL& url) const;
 227
 228   // Serialize the UserScript into a pickle. The content of the scripts and
 229   // paths to UserScript::Files will not be serialized!
 230   void Pickle(base::Pickle* pickle) const;
 231
 232   // Deserialize the script from a pickle. Note that this always succeeds
 233   // because presumably we were the one that pickled it, and we did it
 234   // correctly.
 235   void Unpickle(const base::Pickle& pickle, base::PickleIterator* iter);
 236
 237  private:
 238   // base::Pickle helper functions used to pickle the individual types of
 239   // components.
 240   void PickleGlobs(base::Pickle* pickle,
 241                    const std::vector<std::string>& globs) const;
 242   void PickleHostID(base::Pickle* pickle, const HostID& host_id) const;
 243   void PickleURLPatternSet(base::Pickle* pickle,
 244                            const URLPatternSet& pattern_list) const;
 245   void PickleScripts(base::Pickle* pickle, const FileList& scripts) const;
 246
 247   // Unpickle helper functions used to unpickle individual types of components.
 248   void UnpickleGlobs(const base::Pickle& pickle,
 249                      base::PickleIterator* iter,
 250                      std::vector<std::string>* globs);
 251   void UnpickleHostID(const base::Pickle& pickle,
 252                       base::PickleIterator* iter,
 253                       HostID* host_id);
 254   void UnpickleURLPatternSet(const base::Pickle& pickle,
 255                              base::PickleIterator* iter,
 256                              URLPatternSet* pattern_list);
 257   void UnpickleScripts(const base::Pickle& pickle,
 258                        base::PickleIterator* iter,
 259                        FileList* scripts);
 260
 261   // The location to run the script inside the document.
 262   RunLocation run_location_;
 263
 264   // The namespace of the script. This is used by Greasemonkey in the same way
 265   // as XML namespaces. Only used when parsing Greasemonkey-style scripts.
 266   std::string name_space_;
 267
 268   // The script's name. Only used when parsing Greasemonkey-style scripts.
 269   std::string name_;
 270
 271   // A longer description. Only used when parsing Greasemonkey-style scripts.
 272   std::string description_;
 273
 274   // A version number of the script. Only used when parsing Greasemonkey-style
 275   // scripts.
 276   std::string version_;
 277
 278   // Greasemonkey-style globs that determine pages to inject the script into.
 279   // These are only used with standalone scripts.
 280   std::vector<std::string> globs_;
 281   std::vector<std::string> exclude_globs_;
 282
 283   // URLPatterns that determine pages to inject the script into. These are
 284   // only used with scripts that are part of extensions.
 285   URLPatternSet url_set_;
 286   URLPatternSet exclude_url_set_;
 287
 288   // List of js scripts defined in content_scripts
 289   FileList js_scripts_;
 290
 291   // List of css scripts defined in content_scripts
 292   FileList css_scripts_;
 293
 294   // The ID of the host this script is a part of. The |ID| of the
 295   // |host_id| can be empty if the script is a "standlone" user script.
 296   HostID host_id_;
 297
 298   // The type of the consumer instance that the script will be injected.
 299   ConsumerInstanceType consumer_instance_type_;
 300
 301   // The globally-unique id associated with this user script. Defaults to
 302   // -1 for invalid.
 303   int user_script_id_;
 304
 305   // Whether we should try to emulate Greasemonkey's APIs when running this
 306   // script.
 307   bool emulate_greasemonkey_;
 308
 309   // Whether the user script should run in all frames, or only just the top one.
 310   // Defaults to false.
 311   bool match_all_frames_;
 312
 313   // Whether the user script should run in about:blank and about:srcdoc as well.
 314   // Defaults to false.
 315   bool match_about_blank_;
 316
 317   // True if the script should be injected into an incognito tab.
 318   bool incognito_enabled_;
 319 };
 320
 321 // For storing UserScripts with unique IDs in sets.
 322 bool operator<(const UserScript& script1, const UserScript& script2);
 323
 324 typedef std::vector<UserScript> UserScriptList;
 325
 326 }  // namespace extensions
 327
 328 #endif  // EXTENSIONS_COMMON_USER_SCRIPT_H_