Source code

Revision control

Other Tools

1
/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2
/* This Source Code Form is subject to the terms of the Mozilla Public
3
* License, v. 2.0. If a copy of the MPL was not distributed with this
4
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
5
6
#include "nsISupports.idl"
7
8
/**
9
* URIs are essentially structured names for things -- anything. This interface
10
* provides accessors to get the most basic components of an URI.
11
* If you need to change some parts of the URI use nsIURIMutator.
12
* Subclasses, including nsIURL, impose greater structure on the URI.
13
*
14
* This interface follows Tim Berners-Lee's URI spec (RFC3986) [1], where the
15
* basic URI components are defined as such:
16
* <pre>
18
* \ / \ / \ / \ /\ / \ / \ /
19
* - --------------- ------ -------- ------- --- -
20
* | | | | | | |
21
* | | | | FilePath Query Ref
22
* | | | Port \ /
23
* | | Host / ------------
24
* | UserPass / |
25
* Scheme / Path
26
* \ /
27
* --------------------------------
28
* |
29
* PrePath
30
* </pre>
31
* The definition of the URI components has been extended to allow for
32
* internationalized domain names [2] and the more generic IRI structure [3].
33
*
37
*/
38
39
%{C++
40
#include "nsString.h"
41
42
#undef GetPort // XXX Windows!
43
#undef SetPort // XXX Windows!
44
45
namespace mozilla {
46
class Encoding;
47
namespace ipc {
48
class URIParams;
49
} // namespace ipc
50
} // namespace mozilla
51
%}
52
53
[ptr] native Encoding(const mozilla::Encoding);
54
[ref] native URIParams(mozilla::ipc::URIParams);
55
interface nsIURIMutator;
56
57
/**
58
* nsIURI - interface for an uniform resource identifier w/ i18n support.
59
*
60
* AUTF8String attributes may contain unescaped UTF-8 characters.
61
* Consumers should be careful to escape the UTF-8 strings as necessary, but
62
* should always try to "display" the UTF-8 version as provided by this
63
* interface.
64
*
65
* AUTF8String attributes may also contain escaped characters.
66
*
67
* Unescaping URI segments is unadvised unless there is intimate
68
* knowledge of the underlying charset or there is no plan to display (or
69
* otherwise enforce a charset on) the resulting URI substring.
70
*
71
* The correct way to create an nsIURI from a string is via
72
* nsIIOService.newURI.
73
*
74
* NOTE: nsBinaryInputStream::ReadObject contains a hackaround to intercept the
75
* old (pre-gecko6) nsIURI IID and swap in the current IID instead, in order
76
* for sessionstore to work after an upgrade. If this IID is revved further,
77
* we will need to add additional checks there for all intermediate IIDs, until
78
* ContentPrincipal is fixed to serialize its URIs as nsISupports (bug 662693).
79
*/
80
[scriptable, builtinclass, uuid(92073a54-6d78-4f30-913a-b871813208c6)]
81
interface nsIURI : nsISupports
82
{
83
/************************************************************************
84
* The URI is broken down into the following principal components:
85
*/
86
87
/**
88
* Returns a string representation of the URI.
89
*
90
* Some characters may be escaped.
91
*/
92
readonly attribute AUTF8String spec;
93
94
%{ C++
95
// An infallible wrapper for GetSpec() that returns a failure indication
96
// string if GetSpec() fails. It is most useful for creating
97
// logging/warning/error messages produced for human consumption, and when
98
// matching a URI spec against a fixed spec such as about:blank.
99
nsCString GetSpecOrDefault()
100
{
101
nsCString spec;
102
nsresult rv = GetSpec(spec);
103
if (NS_FAILED(rv)) {
104
spec.AssignLiteral("[nsIURI::GetSpec failed]");
105
}
106
return spec;
107
}
108
%}
109
110
/**
111
* The prePath (eg. scheme://user:password@host:port) returns the string
112
* before the path. This is useful for authentication or managing sessions.
113
*
114
* Some characters may be escaped.
115
*/
116
readonly attribute AUTF8String prePath;
117
118
/**
119
* The Scheme is the protocol to which this URI refers. The scheme is
120
* restricted to the US-ASCII charset per RFC3986.
121
*/
122
readonly attribute ACString scheme;
123
124
/**
125
* The username:password (or username only if value doesn't contain a ':')
126
*
127
* Some characters may be escaped.
128
*/
129
readonly attribute AUTF8String userPass;
130
131
/**
132
* The optional username and password, assuming the preHost consists of
133
* username:password.
134
*
135
* Some characters may be escaped.
136
*/
137
readonly attribute AUTF8String username;
138
readonly attribute AUTF8String password;
139
140
/**
141
* The host:port (or simply the host, if port == -1).
142
*/
143
readonly attribute AUTF8String hostPort;
144
145
/**
146
* The host is the internet domain name to which this URI refers. It could
147
* be an IPv4 (or IPv6) address literal. Otherwise it is an ASCII or punycode
148
* encoded string.
149
*/
150
readonly attribute AUTF8String host;
151
152
/**
153
* A port value of -1 corresponds to the protocol's default port (eg. -1
154
* implies port 80 for http URIs).
155
*/
156
readonly attribute long port;
157
158
/**
159
* The path, typically including at least a leading '/' (but may also be
160
* empty, depending on the protocol).
161
*
162
* Some characters may be escaped.
163
*
164
* This attribute contains query and ref parts for historical reasons.
165
* Use the 'filePath' attribute if you do not want those parts included.
166
*/
167
readonly attribute AUTF8String pathQueryRef;
168
169
170
/************************************************************************
171
* An URI supports the following methods:
172
*/
173
174
/**
175
* URI equivalence test (not a strict string comparison).
176
*
178
*/
179
boolean equals(in nsIURI other);
180
181
/**
182
* An optimization to do scheme checks without requiring the users of nsIURI
183
* to GetScheme, thereby saving extra allocating and freeing. Returns true if
184
* the schemes match (case ignored).
185
*/
186
boolean schemeIs(in string scheme);
187
188
/*
189
* Infallible version of SchemeIs for C++ callers.
190
*/
191
%{C++
192
bool SchemeIs(const char* aScheme) {
193
bool ret;
194
mozilla::Unused << SchemeIs(aScheme, &ret);
195
return ret;
196
}
197
%}
198
199
/**
200
* This method resolves a relative string into an absolute URI string,
201
* using this URI as the base.
202
*
203
* NOTE: some implementations may have no concept of a relative URI.
204
*/
205
AUTF8String resolve(in AUTF8String relativePath);
206
207
208
/************************************************************************
209
* Additional attributes:
210
*/
211
212
/**
213
* The URI spec with an ASCII compatible encoding. Host portion follows
214
* the IDNA draft spec. Other parts are URL-escaped per the rules of
215
* RFC2396. The result is strictly ASCII.
216
*/
217
readonly attribute ACString asciiSpec;
218
219
/**
220
* The host:port (or simply the host, if port == -1), with an ASCII compatible
221
* encoding. Host portion follows the IDNA draft spec. The result is strictly
222
* ASCII.
223
*/
224
readonly attribute ACString asciiHostPort;
225
226
/**
227
* The URI host with an ASCII compatible encoding. Follows the IDNA
228
* draft spec for converting internationalized domain names (UTF-8) to
229
* ASCII for compatibility with existing internet infrasture.
230
*/
231
readonly attribute ACString asciiHost;
232
233
/************************************************************************
234
* Additional attribute & methods added for .ref support:
235
*/
236
237
/**
238
* Returns the reference portion (the part after the "#") of the URI.
239
* If there isn't one, an empty string is returned.
240
*
241
* Some characters may be escaped.
242
*/
243
readonly attribute AUTF8String ref;
244
245
/**
246
* URI equivalence test (not a strict string comparison), ignoring
247
* the value of the .ref member.
248
*
251
*/
252
boolean equalsExceptRef(in nsIURI other);
253
254
/**
255
* returns a string for the current URI with the ref element cleared.
256
*/
257
readonly attribute AUTF8String specIgnoringRef;
258
259
/**
260
* Returns if there is a reference portion (the part after the "#") of the URI.
261
*/
262
readonly attribute boolean hasRef;
263
264
/************************************************************************
265
* Additional attributes added for .query support:
266
*/
267
268
/**
269
* Returns a path including the directory and file portions of a
270
* URL. For example, the filePath of "http://host/foo/bar.html#baz"
271
* is "/foo/bar.html".
272
*
273
* Some characters may be escaped.
274
*/
275
readonly attribute AUTF8String filePath;
276
277
/**
278
* Returns the query portion (the part after the "?") of the URL.
279
* If there isn't one, an empty string is returned.
280
*
281
* Some characters may be escaped.
282
*/
283
readonly attribute AUTF8String query;
284
285
/**
286
* If the URI has a punycode encoded hostname, this will hold the UTF8
287
* representation of that hostname (if that representation doesn't contain
288
* blacklisted characters, and the network.IDN_show_punycode pref is false)
289
* Otherwise, if the hostname is ASCII, it will return the same as .asciiHost
290
*/
291
readonly attribute AUTF8String displayHost;
292
293
/**
294
* The displayHost:port (or simply the displayHost, if port == -1).
295
*/
296
readonly attribute AUTF8String displayHostPort;
297
298
/**
299
* Returns the same as calling .spec, only with a UTF8 encoded hostname
300
* (if that hostname doesn't contain blacklisted characters, and
301
* the network.IDN_show_punycode pref is false)
302
*/
303
readonly attribute AUTF8String displaySpec;
304
305
/**
306
* Returns the same as calling .prePath, only with a UTF8 encoded hostname
307
* (if that hostname doesn't contain blacklisted characters, and
308
* the network.IDN_show_punycode pref is false)
309
*/
310
readonly attribute AUTF8String displayPrePath;
311
312
/**
313
* Returns an nsIURIMutator that can be used to make changes to the URI.
314
* After performing the setter operations on the mutator, one may call
315
* mutator.finalize() to get a new immutable URI with the desired
316
* properties.
317
*/
318
nsIURIMutator mutate();
319
320
/**
321
* Serializes a URI object to a URIParams data structure in order for being
322
* passed over IPC. For deserialization, see nsIURIMutator.
323
*/
324
[noscript, notxpcom] void serialize(in URIParams aParams);
325
326
%{C++
327
// MOZ_DBG support
328
friend std::ostream& operator<<(std::ostream& aOut, const nsIURI& aURI) {
329
nsIURI* uri = const_cast<nsIURI*>(&aURI);
330
return aOut << "nsIURI { " << uri->GetSpecOrDefault() << " }";
331
}
332
%}
333
};