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 THIRD_PARTY_MOZILLA_URL_PARSE_H_
6 #define THIRD_PARTY_MOZILLA_URL_PARSE_H_
7 
8 namespace openscreen {
9 
10 // Component ------------------------------------------------------------------
11 
12 // Represents a substring for URL parsing.
13 struct Component {
ComponentComponent14   Component() : begin(0), len(-1) {}
15 
16   // Normal constructor: takes an offset and a length.
ComponentComponent17   Component(int b, int l) : begin(b), len(l) {}
18 
endComponent19   int end() const { return begin + len; }
20 
21   // Returns true if this component is valid, meaning the length is given. Even
22   // valid components may be empty to record the fact that they exist.
is_validComponent23   bool is_valid() const { return (len != -1); }
24 
25   // Returns true if the given component is specified on false, the component
26   // is either empty or invalid.
is_nonemptyComponent27   bool is_nonempty() const { return (len > 0); }
28 
resetComponent29   void reset() {
30     begin = 0;
31     len = -1;
32   }
33 
34   bool operator==(const Component& other) const {
35     return begin == other.begin && len == other.len;
36   }
37 
38   int begin;  // Byte offset in the string of this component.
39   int len;    // Will be -1 if the component is unspecified.
40 };
41 
42 // Helper that returns a component created with the given begin and ending
43 // points. The ending point is non-inclusive.
MakeRange(int begin,int end)44 inline Component MakeRange(int begin, int end) {
45   return Component(begin, end - begin);
46 }
47 
48 // Parsed ---------------------------------------------------------------------
49 
50 // A structure that holds the identified parts of an input URL. This structure
51 // does NOT store the URL itself. The caller will have to store the URL text
52 // and its corresponding Parsed structure separately.
53 //
54 // Typical usage would be:
55 //
56 //    Parsed parsed;
57 //    Component scheme;
58 //    if (!ExtractScheme(url, url_len, &scheme))
59 //      return I_CAN_NOT_FIND_THE_SCHEME_DUDE;
60 //
61 //    if (IsStandardScheme(url, scheme))  // Not provided by this component
62 //      ParseStandardURL(url, url_len, &parsed);
63 //    else if (IsFileURL(url, scheme))    // Not provided by this component
64 //      ParseFileURL(url, url_len, &parsed);
65 //    else
66 //      ParsePathURL(url, url_len, &parsed);
67 //
68 struct Parsed {
69   // Identifies different components.
70   enum ComponentType {
71     SCHEME,
72     USERNAME,
73     PASSWORD,
74     HOST,
75     PORT,
76     PATH,
77     QUERY,
78     REF,
79   };
80 
81   // The default constructor is sufficient for the components, but inner_parsed_
82   // requires special handling.
83   Parsed();
84   Parsed(const Parsed&);
85   Parsed& operator=(const Parsed&);
86   ~Parsed();
87 
88   // Returns the length of the URL (the end of the last component).
89   //
90   // Note that for some invalid, non-canonical URLs, this may not be the length
91   // of the string. For example "http://": the parsed structure will only
92   // contain an entry for the four-character scheme, and it doesn't know about
93   // the "://". For all other last-components, it will return the real length.
94   int Length() const;
95 
96   // Returns the number of characters before the given component if it exists,
97   // or where the component would be if it did exist. This will return the
98   // string length if the component would be appended to the end.
99   //
100   // Note that this can get a little funny for the port, query, and ref
101   // components which have a delimiter that is not counted as part of the
102   // component. The |include_delimiter| flag controls if you want this counted
103   // as part of the component or not when the component exists.
104   //
105   // This example shows the difference between the two flags for two of these
106   // delimited components that is present (the port and query) and one that
107   // isn't (the reference). The components that this flag affects are marked
108   // with a *.
109   //                 0         1         2
110   //                 012345678901234567890
111   // Example input:  http://foo:80/?query
112   //              include_delim=true,  ...=false  ("<-" indicates different)
113   //      SCHEME: 0                    0
114   //    USERNAME: 5                    5
115   //    PASSWORD: 5                    5
116   //        HOST: 7                    7
117   //       *PORT: 10                   11 <-
118   //        PATH: 13                   13
119   //      *QUERY: 14                   15 <-
120   //        *REF: 20                   20
121   //
122   int CountCharactersBefore(ComponentType type, bool include_delimiter) const;
123 
124   // Scheme without the colon: "http://foo"/ would have a scheme of "http".
125   // The length will be -1 if no scheme is specified ("foo.com"), or 0 if there
126   // is a colon but no scheme (":foo"). Note that the scheme is not guaranteed
127   // to start at the beginning of the string if there are preceeding whitespace
128   // or control characters.
129   Component scheme;
130 
131   // Username. Specified in URLs with an @ sign before the host. See |password|
132   Component username;
133 
134   // Password. The length will be -1 if unspecified, 0 if specified but empty.
135   // Not all URLs with a username have a password, as in "http://me@host/".
136   // The password is separated form the username with a colon, as in
137   // "http://me:secret@host/"
138   Component password;
139 
140   // Host name.
141   Component host;
142 
143   // Port number.
144   Component port;
145 
146   // Path, this is everything following the host name, stopping at the query of
147   // ref delimiter (if any). Length will be -1 if unspecified. This includes
148   // the preceeding slash, so the path on http://www.google.com/asdf" is
149   // "/asdf". As a result, it is impossible to have a 0 length path, it will
150   // be -1 in cases like "http://host?foo".
151   // Note that we treat backslashes the same as slashes.
152   Component path;
153 
154   // Stuff between the ? and the # after the path. This does not include the
155   // preceeding ? character. Length will be -1 if unspecified, 0 if there is
156   // a question mark but no query string.
157   Component query;
158 
159   // Indicated by a #, this is everything following the hash sign (not
160   // including it). If there are multiple hash signs, we'll use the last one.
161   // Length will be -1 if there is no hash sign, or 0 if there is one but
162   // nothing follows it.
163   Component ref;
164 
165   // The URL spec from the character after the scheme: until the end of the
166   // URL, regardless of the scheme. This is mostly useful for 'opaque' non-
167   // hierarchical schemes like data: and javascript: as a convient way to get
168   // the string with the scheme stripped off.
169   Component GetContent() const;
170 
171   // True if the URL's source contained a raw `<` character, and whitespace was
172   // removed from the URL during parsing
173   //
174   // TODO(mkwst): Link this to something in a spec if
175   // https://github.com/whatwg/url/pull/284 lands.
176   bool potentially_dangling_markup;
177 
178   // This is used for nested URL types, currently only filesystem.  If you
179   // parse a filesystem URL, the resulting Parsed will have a nested
180   // inner_parsed_ to hold the parsed inner URL's component information.
181   // For all other url types [including the inner URL], it will be NULL.
inner_parsedParsed182   Parsed* inner_parsed() const { return inner_parsed_; }
183 
set_inner_parsedParsed184   void set_inner_parsed(const Parsed& inner_parsed) {
185     if (!inner_parsed_)
186       inner_parsed_ = new Parsed(inner_parsed);
187     else
188       *inner_parsed_ = inner_parsed;
189   }
190 
clear_inner_parsedParsed191   void clear_inner_parsed() {
192     if (inner_parsed_) {
193       delete inner_parsed_;
194       inner_parsed_ = nullptr;
195     }
196   }
197 
198  private:
199   Parsed* inner_parsed_;  // This object is owned and managed by this struct.
200 };
201 
202 // Initialization functions ---------------------------------------------------
203 //
204 // These functions parse the given URL, filling in all of the structure's
205 // components. These functions can not fail, they will always do their best
206 // at interpreting the input given.
207 //
208 // The string length of the URL MUST be specified, we do not check for NULLs
209 // at any point in the process, and will actually handle embedded NULLs.
210 //
211 // IMPORTANT: These functions do NOT hang on to the given pointer or copy it
212 // in any way. See the comment above the struct.
213 //
214 // The 8-bit versions require UTF-8 encoding.
215 
216 // StandardURL is for when the scheme is known to be one that has an
217 // authority (host) like "http". This function will not handle weird ones
218 // like "about:" and "javascript:", or do the right thing for "file:" URLs.
219 void ParseStandardURL(const char* url, int url_len, Parsed* parsed);
220 
221 // PathURL is for when the scheme is known not to have an authority (host)
222 // section but that aren't file URLs either. The scheme is parsed, and
223 // everything after the scheme is considered as the path. This is used for
224 // things like "about:" and "javascript:"
225 void ParsePathURL(const char* url,
226                   int url_len,
227                   bool trim_path_end,
228                   Parsed* parsed);
229 
230 // FileURL is for file URLs. There are some special rules for interpreting
231 // these.
232 void ParseFileURL(const char* url, int url_len, Parsed* parsed);
233 
234 // Filesystem URLs are structured differently than other URLs.
235 void ParseFileSystemURL(const char* url, int url_len, Parsed* parsed);
236 
237 // MailtoURL is for mailto: urls. They are made up scheme,path,query
238 void ParseMailtoURL(const char* url, int url_len, Parsed* parsed);
239 
240 // Helper functions -----------------------------------------------------------
241 
242 // Locates the scheme according to the URL  parser's rules. This function is
243 // designed so the caller can find the scheme and call the correct Init*
244 // function according to their known scheme types.
245 //
246 // It also does not perform any validation on the scheme.
247 //
248 // This function will return true if the scheme is found and will put the
249 // scheme's range into *scheme. False means no scheme could be found. Note
250 // that a URL beginning with a colon has a scheme, but it is empty, so this
251 // function will return true but *scheme will = (0,0).
252 //
253 // The scheme is found by skipping spaces and control characters at the
254 // beginning, and taking everything from there to the first colon to be the
255 // scheme. The character at scheme.end() will be the colon (we may enhance
256 // this to handle full width colons or something, so don't count on the
257 // actual character value). The character at scheme.end()+1 will be the
258 // beginning of the rest of the URL, be it the authority or the path (or the
259 // end of the string).
260 //
261 // The 8-bit version requires UTF-8 encoding.
262 bool ExtractScheme(const char* url, int url_len, Component* scheme);
263 
264 // Returns true if ch is a character that terminates the authority segment
265 // of a URL.
266 bool IsAuthorityTerminator(char ch);
267 
268 // Does a best effort parse of input |spec|, in range |auth|. If a particular
269 // component is not found, it will be set to invalid.
270 void ParseAuthority(const char* spec,
271                     const Component& auth,
272                     Component* username,
273                     Component* password,
274                     Component* hostname,
275                     Component* port_num);
276 
277 // Computes the integer port value from the given port component. The port
278 // component should have been identified by one of the init functions on
279 // |Parsed| for the given input url.
280 //
281 // The return value will be a positive integer between 0 and 64K, or one of
282 // the two special values below.
283 enum SpecialPort { PORT_UNSPECIFIED = -1, PORT_INVALID = -2 };
284 int ParsePort(const char* url, const Component& port);
285 
286 // Extracts the range of the file name in the given url. The path must
287 // already have been computed by the parse function, and the matching URL
288 // and extracted path are provided to this function. The filename is
289 // defined as being everything from the last slash/backslash of the path
290 // to the end of the path.
291 //
292 // The file name will be empty if the path is empty or there is nothing
293 // following the last slash.
294 //
295 // The 8-bit version requires UTF-8 encoding.
296 void ExtractFileName(const char* url,
297                      const Component& path,
298                      Component* file_name);
299 
300 // Extract the first key/value from the range defined by |*query|. Updates
301 // |*query| to start at the end of the extracted key/value pair. This is
302 // designed for use in a loop: you can keep calling it with the same query
303 // object and it will iterate over all items in the query.
304 //
305 // Some key/value pairs may have the key, the value, or both be empty (for
306 // example, the query string "?&"). These will be returned. Note that an empty
307 // last parameter "foo.com?" or foo.com?a&" will not be returned, this case
308 // is the same as "done."
309 //
310 // The initial query component should not include the '?' (this is the default
311 // for parsed URLs).
312 //
313 // If no key/value are found |*key| and |*value| will be unchanged and it will
314 // return false.
315 bool ExtractQueryKeyValue(const char* url,
316                           Component* query,
317                           Component* key,
318                           Component* value);
319 
320 }  // namespace openscreen
321 
322 #endif  // THIRD_PARTY_MOZILLA_URL_PARSE_H_
323