summaryrefslogtreecommitdiff
path: root/netwerk/base/nsIURI.idl
blob: ef163813aa37cd96f15a5c6861c9e0a5b161fda0 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"

/**
 * URIs are essentially structured names for things -- anything. This interface
 * provides accessors to set and query the most basic components of an URI.
 * Subclasses, including nsIURL, impose greater structure on the URI.
 *
 * This interface follows Tim Berners-Lee's URI spec (RFC3986) [1], where the
 * basic URI components are defined as such:
 * <pre>
 *      ftp://username:password@hostname:portnumber/pathname?query#ref
 *      \ /   \               / \      / \        /\       / \   / \ /
 *       -     ---------------   ------   --------  -------   ---   -
 *       |            |             |        |         |       |    |
 *       |            |             |        |      FilePath Query Ref
 *       |            |             |       Port       \            /
 *       |            |            Host      /          ------------
 *       |         UserPass                 /	              |
 *     Scheme                              /	             Path
 *       \                                /
 *        --------------------------------
 *                       |
 *                    PrePath
 * </pre>
 * The definition of the URI components has been extended to allow for
 * internationalized domain names [2] and the more generic IRI structure [3].
 *
 * [1] https://tools.ietf.org/html/rfc3986
 * [2] https://tools.ietf.org/html/rfc5890
 * [3] https://tools.ietf.org/html/rfc3987
 */

%{C++
#include "nsStringGlue.h"

#undef GetPort  // XXX Windows!
#undef SetPort  // XXX Windows!
%}

/**
 * nsIURI - interface for an uniform resource identifier w/ i18n support.
 *
 * AUTF8String attributes may contain unescaped UTF-8 characters.
 * Consumers should be careful to escape the UTF-8 strings as necessary, but
 * should always try to "display" the UTF-8 version as provided by this
 * interface.
 *
 * AUTF8String attributes may also contain escaped characters.
 * 
 * Unescaping URI segments is unadvised unless there is intimate
 * knowledge of the underlying charset or there is no plan to display (or
 * otherwise enforce a charset on) the resulting URI substring.
 *
 * The correct way to create an nsIURI from a string is via
 * nsIIOService.newURI.
 *
 * NOTE: nsBinaryInputStream::ReadObject contains a hackaround to intercept the
 * old (pre-gecko6) nsIURI IID and swap in the current IID instead, in order
 * for sessionstore to work after an upgrade.  If this IID is revved further,
 * we will need to add additional checks there for all intermediate IIDs, until
 * nsPrincipal is fixed to serialize its URIs as nsISupports (bug 662693).
 */
[scriptable, uuid(92073a54-6d78-4f30-913a-b871813208c6)]
interface nsIURI : nsISupports
{
    /************************************************************************
     * The URI is broken down into the following principal components:
     */

    /**
     * Returns a string representation of the URI. Setting the spec causes
     * the new spec to be parsed per the rules for the scheme the URI
     * currently has.  In particular, setting the spec to a URI string with a
     * different scheme will generally produce incorrect results; no one
     * outside of a protocol handler implementation should be doing that.  If
     * the URI stores information from the nsIIOService.newURI call used to
     * create it other than just the parsed string, then behavior of this
     * information on setting the spec attribute is undefined.
     *
     * Some characters may be escaped.
     */
    attribute AUTF8String spec;

%{ C++
    // An infallible wrapper for GetSpec() that returns a failure indication
    // string if GetSpec() fails. It is most useful for creating
    // logging/warning/error messages produced for human consumption, and when
    // matching a URI spec against a fixed spec such as about:blank.
    nsCString GetSpecOrDefault()
    {
        nsCString spec;
        nsresult rv = GetSpec(spec);
        if (NS_FAILED(rv)) {
            spec.Assign("[nsIURI::GetSpec failed]");
        }
        return spec;
    }
%}

    /**
     * The prePath (eg. scheme://user:password@host:port) returns the string
     * before the path.  This is useful for authentication or managing sessions.
     *
     * Some characters may be escaped.
     */
    readonly attribute AUTF8String prePath;

    /**
     * The Scheme is the protocol to which this URI refers.  The scheme is
     * restricted to the US-ASCII charset per RFC3986.  Setting this is
     * highly discouraged outside of a protocol handler implementation, since
     * that will generally lead to incorrect results.
     */
    attribute ACString scheme;

    /**
     * The username:password (or username only if value doesn't contain a ':')
     *
     * Some characters may be escaped.
     */
    attribute AUTF8String userPass;

    /**
     * The optional username and password, assuming the preHost consists of
     * username:password.
     *
     * Some characters may be escaped.
     */
    attribute AUTF8String username;
    attribute AUTF8String password;

    /**
     * The host:port (or simply the host, if port == -1).
     *
     * If this attribute is set to a value that only has a host part, the port
     * will not be reset. To reset the port as well use setHostAndPort.
     *
     * Characters are NOT escaped.
     */
    attribute AUTF8String hostPort;

    /**
     * This function will always set a host and a port. If the port part is
     * empty, the value of the port will be set to the default value.
     */
    void setHostAndPort(in AUTF8String hostport);

    /**
     * The host is the internet domain name to which this URI refers.  It could
     * be an IPv4 (or IPv6) address literal.  If supported, it could be a
     * non-ASCII internationalized domain name.
     *
     * Characters are NOT escaped.
     */
    attribute AUTF8String host;

    /**
     * A port value of -1 corresponds to the protocol's default port (eg. -1
     * implies port 80 for http URIs).
     */
    attribute long port;

    /**
     * The path, typically including at least a leading '/' (but may also be
     * empty, depending on the protocol).
     *
     * Some characters may be escaped.
     *
     * This attribute contains query and ref parts for historical reasons.
     * Use the 'filePath' attribute if you do not want those parts included.
     */
    attribute AUTF8String path;


    /************************************************************************
     * An URI supports the following methods:
     */

    /**
     * URI equivalence test (not a strict string comparison).
     *
     * eg. http://foo.com:80/ == http://foo.com/
     */
    boolean equals(in nsIURI other);

    /**
     * An optimization to do scheme checks without requiring the users of nsIURI
     * to GetScheme, thereby saving extra allocating and freeing. Returns true if
     * the schemes match (case ignored).
     */
    boolean schemeIs(in string scheme);

    /**
     * Clones the current URI.
     */
    nsIURI clone();

    /**
     * This method resolves a relative string into an absolute URI string,
     * using this URI as the base. 
     *
     * NOTE: some implementations may have no concept of a relative URI.
     */
    AUTF8String resolve(in AUTF8String relativePath);


    /************************************************************************
     * Additional attributes:
     */

    /**
     * The URI spec with an ASCII compatible encoding.  Host portion follows
     * the IDNA draft spec.  Other parts are URL-escaped per the rules of
     * RFC2396.  The result is strictly ASCII.
     */
    readonly attribute ACString asciiSpec;

    /**
     * The host:port (or simply the host, if port == -1), with an ASCII compatible
     * encoding.  Host portion follows the IDNA draft spec.  The result is strictly
     * ASCII.
     */
    readonly attribute ACString asciiHostPort;

    /**
     * The URI host with an ASCII compatible encoding.  Follows the IDNA
     * draft spec for converting internationalized domain names (UTF-8) to
     * ASCII for compatibility with existing internet infrasture.
     */
    readonly attribute ACString asciiHost;

    /**
     * The charset of the document from which this URI originated.  An empty
     * value implies UTF-8.
     *
     * If this value is something other than UTF-8 then the URI components
     * (e.g., spec, prePath, username, etc.) will all be fully URL-escaped.
     * Otherwise, the URI components may contain unescaped multibyte UTF-8
     * characters.
     */
    readonly attribute ACString originCharset;

    /************************************************************************
     * Additional attribute & methods added for .ref support:
     */

    /**
     * Returns the reference portion (the part after the "#") of the URI.
     * If there isn't one, an empty string is returned.
     *
     * Some characters may be escaped.
     */
    attribute AUTF8String ref;

    /**
     * URI equivalence test (not a strict string comparison), ignoring
     * the value of the .ref member.
     *
     * eg. http://foo.com/# == http://foo.com/
     *     http://foo.com/#aaa == http://foo.com/#bbb
     */
    boolean equalsExceptRef(in nsIURI other);

    /**
     * Clones the current URI, clearing the 'ref' attribute in the clone.
     */
    nsIURI cloneIgnoringRef();

    /**
     * Clones the current URI, replacing the 'ref' attribute in the clone with
     * the ref supplied.
     */
    nsIURI cloneWithNewRef(in AUTF8String newRef);

    /**
     * returns a string for the current URI with the ref element cleared.
     */
    readonly attribute AUTF8String specIgnoringRef;

    /**
     * Returns if there is a reference portion (the part after the "#") of the URI.
     */
    readonly attribute boolean hasRef;

    /************************************************************************
     * Additional attributes added for .query support:
     */

    /**
     * Returns a path including the directory and file portions of a
     * URL.  For example, the filePath of "http://host/foo/bar.html#baz"
     * is "/foo/bar.html".
     *
     * Some characters may be escaped.
     */
    attribute AUTF8String filePath;

    /**
     * Returns the query portion (the part after the "?") of the URL.
     * If there isn't one, an empty string is returned.
     *
     * Some characters may be escaped.
     */
    attribute AUTF8String query;
};