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