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