src/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/files/file_path.h"
  12 #include "base/strings/string_piece.h"
  13 #include "extensions/common/url_pattern.h"
  14 #include "extensions/common/url_pattern_set.h"
  15 #include "url/gurl.h"
  16
  17 class Pickle;
  18 class PickleIterator;
  19
  20 namespace extensions {
  21
  22 // Represents a user script, either a standalone one, or one that is part of an
  23 // extension.
  24 class UserScript {
  25  public:
  26   // The file extension for standalone user scripts.
  27   static const char kFileExtension[];
  28
  29   // Check if a URL should be treated as a user script and converted to an
  30   // extension.
  31   static bool IsURLUserScript(const GURL& url, const std::string& mime_type);
  32
  33   // Get the valid user script schemes for the current process. If
  34   // canExecuteScriptEverywhere is true, this will return ALL_SCHEMES.
  35   static int ValidUserScriptSchemes(bool canExecuteScriptEverywhere = false);
  36
  37   // Locations that user scripts can be run inside the document.
  38   enum RunLocation {
  39     UNDEFINED,
  40     DOCUMENT_START,  // After the documentElement is created, but before
  41                      // anything else happens.
  42     DOCUMENT_END,  // After the entire document is parsed. Same as
  43                    // DOMContentLoaded.
  44     DOCUMENT_IDLE,  // Sometime after DOMContentLoaded, as soon as the document
  45                     // is "idle". Currently this uses the simple heuristic of:
  46                     // min(DOM_CONTENT_LOADED + TIMEOUT, ONLOAD), but no
  47                     // particular injection point is guaranteed.
  48     RUN_LOCATION_LAST  // Leave this as the last item.
  49   };
  50
  51   // Holds actual script file info.
  52   class File {
  53    public:
  54     File(const base::FilePath& extension_root,
  55          const base::FilePath& relative_path,
  56          const GURL& url);
  57     File();
  58     ~File();
  59
  60     const base::FilePath& extension_root() const { return extension_root_; }
  61     const base::FilePath& relative_path() const { return relative_path_; }
  62
  63     const GURL& url() const { return url_; }
  64     void set_url(const GURL& url) { url_ = url; }
  65
  66     // If external_content_ is set returns it as content otherwise it returns
  67     // content_
  68     const base::StringPiece GetContent() const {
  69       if (external_content_.data())
  70         return external_content_;
  71       else
  72         return content_;
  73     }
  74     void set_external_content(const base::StringPiece& content) {
  75       external_content_ = content;
  76     }
  77     void set_content(const base::StringPiece& content) {
  78       content_.assign(content.begin(), content.end());
  79     }
  80
  81     // Serialization support. The content and FilePath members will not be
  82     // serialized!
  83     void Pickle(::Pickle* pickle) const;
  84     void Unpickle(const ::Pickle& pickle, PickleIterator* iter);
  85
  86    private:
  87     // Where the script file lives on the disk. We keep the path split so that
  88     // it can be localized at will.
  89     base::FilePath extension_root_;
  90     base::FilePath relative_path_;
  91
  92     // The url to this scipt file.
  93     GURL url_;
  94
  95     // The script content. It can be set to either loaded_content_ or
  96     // externally allocated string.
  97     base::StringPiece external_content_;
  98
  99     // Set when the content is loaded by LoadContent
 100     std::string content_;
 101   };
 102
 103   typedef std::vector<File> FileList;
 104
 105   // Constructor. Default the run location to document end, which is like
 106   // Greasemonkey and probably more useful for typical scripts.
 107   UserScript();
 108   ~UserScript();
 109
 110   const std::string& name_space() const { return name_space_; }
 111   void set_name_space(const std::string& name_space) {
 112     name_space_ = name_space;
 113   }
 114
 115   const std::string& name() const { return name_; }
 116   void set_name(const std::string& name) { name_ = name; }
 117
 118   const std::string& version() const { return version_; }
 119   void set_version(const std::string& version) {
 120     version_ = version;
 121   }
 122
 123   const std::string& description() const { return description_; }
 124   void set_description(const std::string& description) {
 125     description_ = description;
 126   }
 127
 128   // The place in the document to run the script.
 129   RunLocation run_location() const { return run_location_; }
 130   void set_run_location(RunLocation location) { run_location_ = location; }
 131
 132   // Whether to emulate greasemonkey when running this script.
 133   bool emulate_greasemonkey() const { return emulate_greasemonkey_; }
 134   void set_emulate_greasemonkey(bool val) { emulate_greasemonkey_ = val; }
 135
 136   // Whether to match all frames, or only the top one.
 137   bool match_all_frames() const { return match_all_frames_; }
 138   void set_match_all_frames(bool val) { match_all_frames_ = val; }
 139
 140   // The globs, if any, that determine which pages this script runs against.
 141   // These are only used with "standalone" Greasemonkey-like user scripts.
 142   const std::vector<std::string>& globs() const { return globs_; }
 143   void add_glob(const std::string& glob) { globs_.push_back(glob); }
 144   void clear_globs() { globs_.clear(); }
 145   const std::vector<std::string>& exclude_globs() const {
 146     return exclude_globs_;
 147   }
 148   void add_exclude_glob(const std::string& glob) {
 149     exclude_globs_.push_back(glob);
 150   }
 151   void clear_exclude_globs() { exclude_globs_.clear(); }
 152
 153   // The URLPatterns, if any, that determine which pages this script runs
 154   // against.
 155   const URLPatternSet& url_patterns() const { return url_set_; }
 156   void add_url_pattern(const URLPattern& pattern);
 157   const URLPatternSet& exclude_url_patterns() const {
 158     return exclude_url_set_;
 159   }
 160   void add_exclude_url_pattern(const URLPattern& pattern);
 161
 162   // List of js scripts for this user script
 163   FileList& js_scripts() { return js_scripts_; }
 164   const FileList& js_scripts() const { return js_scripts_; }
 165
 166   // List of css scripts for this user script
 167   FileList& css_scripts() { return css_scripts_; }
 168   const FileList& css_scripts() const { return css_scripts_; }
 169
 170   const std::string& extension_id() const { return extension_id_; }
 171   void set_extension_id(const std::string& id) { extension_id_ = id; }
 172
 173   bool is_incognito_enabled() const { return incognito_enabled_; }
 174   void set_incognito_enabled(bool enabled) { incognito_enabled_ = enabled; }
 175
 176   bool is_standalone() const { return extension_id_.empty(); }
 177
 178   // Returns true if the script should be applied to the specified URL, false
 179   // otherwise.
 180   bool MatchesURL(const GURL& url) const;
 181
 182   // Serialize the UserScript into a pickle. The content of the scripts and
 183   // paths to UserScript::Files will not be serialized!
 184   void Pickle(::Pickle* pickle) const;
 185
 186   // Deserialize the script from a pickle. Note that this always succeeds
 187   // because presumably we were the one that pickled it, and we did it
 188   // correctly.
 189   void Unpickle(const ::Pickle& pickle, PickleIterator* iter);
 190
 191  private:
 192   // Pickle helper functions used to pickle the individual types of components.
 193   void PickleGlobs(::Pickle* pickle,
 194                    const std::vector<std::string>& globs) const;
 195   void PickleURLPatternSet(::Pickle* pickle,
 196                            const URLPatternSet& pattern_list) const;
 197   void PickleScripts(::Pickle* pickle, const FileList& scripts) const;
 198
 199   // Unpickle helper functions used to unpickle individual types of components.
 200   void UnpickleGlobs(const ::Pickle& pickle, PickleIterator* iter,
 201                      std::vector<std::string>* globs);
 202   void UnpickleURLPatternSet(const ::Pickle& pickle, PickleIterator* iter,
 203                              URLPatternSet* pattern_list);
 204   void UnpickleScripts(const ::Pickle& pickle, PickleIterator* iter,
 205                        FileList* scripts);
 206
 207   // The location to run the script inside the document.
 208   RunLocation run_location_;
 209
 210   // The namespace of the script. This is used by Greasemonkey in the same way
 211   // as XML namespaces. Only used when parsing Greasemonkey-style scripts.
 212   std::string name_space_;
 213
 214   // The script's name. Only used when parsing Greasemonkey-style scripts.
 215   std::string name_;
 216
 217   // A longer description. Only used when parsing Greasemonkey-style scripts.
 218   std::string description_;
 219
 220   // A version number of the script. Only used when parsing Greasemonkey-style
 221   // scripts.
 222   std::string version_;
 223
 224   // Greasemonkey-style globs that determine pages to inject the script into.
 225   // These are only used with standalone scripts.
 226   std::vector<std::string> globs_;
 227   std::vector<std::string> exclude_globs_;
 228
 229   // URLPatterns that determine pages to inject the script into. These are
 230   // only used with scripts that are part of extensions.
 231   URLPatternSet url_set_;
 232   URLPatternSet exclude_url_set_;
 233
 234   // List of js scripts defined in content_scripts
 235   FileList js_scripts_;
 236
 237   // List of css scripts defined in content_scripts
 238   FileList css_scripts_;
 239
 240   // The ID of the extension this script is a part of, if any. Can be empty if
 241   // the script is a "standlone" user script.
 242   std::string extension_id_;
 243
 244   // Whether we should try to emulate Greasemonkey's APIs when running this
 245   // script.
 246   bool emulate_greasemonkey_;
 247
 248   // Whether the user script should run in all frames, or only just the top one.
 249   // Defaults to false.
 250   bool match_all_frames_;
 251
 252   // True if the script should be injected into an incognito tab.
 253   bool incognito_enabled_;
 254 };
 255
 256 typedef std::vector<UserScript> UserScriptList;
 257
 258 }  // namespace extensions
 259
 260 #endif  // EXTENSIONS_COMMON_USER_SCRIPT_H_