The Tor Browser / file comparison
comparison: netwerk/base/public/nsIURI.idl
netwerk/base/public/nsIURI.idl
- branch
- TOR_BUG_9701
- changeset 15
- b8a032363ba2
equal
deleted
inserted
replaced
| -1:000000000000 | 0:54b9c695cf5c |
|---|---|
| 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 set and query the most basic components of an URI. | |
| 11 * Subclasses, including nsIURL, impose greater structure on the URI. | |
| 12 * | |
| 13 * This interface follows Tim Berners-Lee's URI spec (RFC2396) [1], where the | |
| 14 * basic URI components are defined as such: | |
| 15 * <pre> | |
| 16 * ftp://username:password@hostname:portnumber/pathname#ref | |
| 17 * \ / \ / \ / \ /\ \ / | |
| 18 * - --------------- ------ -------- | - | |
| 19 * | | | | | | | |
| 20 * | | | | | Ref | |
| 21 * | | | Port \ / | |
| 22 * | | Host / -------- | |
| 23 * | UserPass / | | |
| 24 * Scheme / Path | |
| 25 * \ / | |
| 26 * -------------------------------- | |
| 27 * | | |
| 28 * PrePath | |
| 29 * </pre> | |
| 30 * The definition of the URI components has been extended to allow for | |
| 31 * internationalized domain names [2] and the more generic IRI structure [3]. | |
| 32 * | |
| 33 * Note also that the RFC defines #-separated fragment identifiers as being | |
| 34 * "not part of the URI". Despite this, we bundle them as part of the URI, for | |
| 35 * convenience. | |
| 36 * | |
| 37 * [1] http://www.ietf.org/rfc/rfc2396.txt | |
| 38 * [2] http://www.ietf.org/internet-drafts/draft-ietf-idn-idna-06.txt | |
| 39 * [3] http://www.ietf.org/internet-drafts/draft-masinter-url-i18n-08.txt | |
| 40 */ | |
| 41 | |
| 42 %{C++ | |
| 43 #undef GetPort // XXX Windows! | |
| 44 #undef SetPort // XXX Windows! | |
| 45 %} | |
| 46 | |
| 47 /** | |
| 48 * nsIURI - interface for an uniform resource identifier w/ i18n support. | |
| 49 * | |
| 50 * AUTF8String attributes may contain unescaped UTF-8 characters. | |
| 51 * Consumers should be careful to escape the UTF-8 strings as necessary, but | |
| 52 * should always try to "display" the UTF-8 version as provided by this | |
| 53 * interface. | |
| 54 * | |
| 55 * AUTF8String attributes may also contain escaped characters. | |
| 56 * | |
| 57 * Unescaping URI segments is unadvised unless there is intimate | |
| 58 * knowledge of the underlying charset or there is no plan to display (or | |
| 59 * otherwise enforce a charset on) the resulting URI substring. | |
| 60 * | |
| 61 * The correct way to create an nsIURI from a string is via | |
| 62 * nsIIOService.newURI. | |
| 63 * | |
| 64 * NOTE: nsBinaryInputStream::ReadObject contains a hackaround to intercept the | |
| 65 * old (pre-gecko6) nsIURI IID and swap in the current IID instead, in order | |
| 66 * for sessionstore to work after an upgrade. If this IID is revved further, | |
| 67 * we will need to add additional checks there for all intermediate IIDs, until | |
| 68 * nsPrincipal is fixed to serialize its URIs as nsISupports (bug 662693). | |
| 69 */ | |
| 70 [scriptable, uuid(395fe045-7d18-4adb-a3fd-af98c8a1af11)] | |
| 71 interface nsIURI : nsISupports | |
| 72 { | |
| 73 /************************************************************************ | |
| 74 * The URI is broken down into the following principal components: | |
| 75 */ | |
| 76 | |
| 77 /** | |
| 78 * Returns a string representation of the URI. Setting the spec causes | |
| 79 * the new spec to be parsed per the rules for the scheme the URI | |
| 80 * currently has. In particular, setting the spec to a URI string with a | |
| 81 * different scheme will generally produce incorrect results; no one | |
| 82 * outside of a protocol handler implementation should be doing that. If | |
| 83 * the URI stores information from the nsIIOService.newURI call used to | |
| 84 * create it other than just the parsed string, then behavior of this | |
| 85 * information on setting the spec attribute is undefined. | |
| 86 * | |
| 87 * Some characters may be escaped. | |
| 88 */ | |
| 89 attribute AUTF8String spec; | |
| 90 | |
| 91 /** | |
| 92 * The prePath (eg. scheme://user:password@host:port) returns the string | |
| 93 * before the path. This is useful for authentication or managing sessions. | |
| 94 * | |
| 95 * Some characters may be escaped. | |
| 96 */ | |
| 97 readonly attribute AUTF8String prePath; | |
| 98 | |
| 99 /** | |
| 100 * The Scheme is the protocol to which this URI refers. The scheme is | |
| 101 * restricted to the US-ASCII charset per RFC2396. Setting this is | |
| 102 * highly discouraged outside of a protocol handler implementation, since | |
| 103 * that will generally lead to incorrect results. | |
| 104 */ | |
| 105 attribute ACString scheme; | |
| 106 | |
| 107 /** | |
| 108 * The username:password (or username only if value doesn't contain a ':') | |
| 109 * | |
| 110 * Some characters may be escaped. | |
| 111 */ | |
| 112 attribute AUTF8String userPass; | |
| 113 | |
| 114 /** | |
| 115 * The optional username and password, assuming the preHost consists of | |
| 116 * username:password. | |
| 117 * | |
| 118 * Some characters may be escaped. | |
| 119 */ | |
| 120 attribute AUTF8String username; | |
| 121 attribute AUTF8String password; | |
| 122 | |
| 123 /** | |
| 124 * The host:port (or simply the host, if port == -1). | |
| 125 * | |
| 126 * Characters are NOT escaped. | |
| 127 */ | |
| 128 attribute AUTF8String hostPort; | |
| 129 | |
| 130 /** | |
| 131 * The host is the internet domain name to which this URI refers. It could | |
| 132 * be an IPv4 (or IPv6) address literal. If supported, it could be a | |
| 133 * non-ASCII internationalized domain name. | |
| 134 * | |
| 135 * Characters are NOT escaped. | |
| 136 */ | |
| 137 attribute AUTF8String host; | |
| 138 | |
| 139 /** | |
| 140 * A port value of -1 corresponds to the protocol's default port (eg. -1 | |
| 141 * implies port 80 for http URIs). | |
| 142 */ | |
| 143 attribute long port; | |
| 144 | |
| 145 /** | |
| 146 * The path, typically including at least a leading '/' (but may also be | |
| 147 * empty, depending on the protocol). | |
| 148 * | |
| 149 * Some characters may be escaped. | |
| 150 */ | |
| 151 attribute AUTF8String path; | |
| 152 | |
| 153 | |
| 154 /************************************************************************ | |
| 155 * An URI supports the following methods: | |
| 156 */ | |
| 157 | |
| 158 /** | |
| 159 * URI equivalence test (not a strict string comparison). | |
| 160 * | |
| 161 * eg. http://foo.com:80/ == http://foo.com/ | |
| 162 */ | |
| 163 boolean equals(in nsIURI other); | |
| 164 | |
| 165 /** | |
| 166 * An optimization to do scheme checks without requiring the users of nsIURI | |
| 167 * to GetScheme, thereby saving extra allocating and freeing. Returns true if | |
| 168 * the schemes match (case ignored). | |
| 169 */ | |
| 170 boolean schemeIs(in string scheme); | |
| 171 | |
| 172 /** | |
| 173 * Clones the current URI. | |
| 174 */ | |
| 175 nsIURI clone(); | |
| 176 | |
| 177 /** | |
| 178 * This method resolves a relative string into an absolute URI string, | |
| 179 * using this URI as the base. | |
| 180 * | |
| 181 * NOTE: some implementations may have no concept of a relative URI. | |
| 182 */ | |
| 183 AUTF8String resolve(in AUTF8String relativePath); | |
| 184 | |
| 185 | |
| 186 /************************************************************************ | |
| 187 * Additional attributes: | |
| 188 */ | |
| 189 | |
| 190 /** | |
| 191 * The URI spec with an ASCII compatible encoding. Host portion follows | |
| 192 * the IDNA draft spec. Other parts are URL-escaped per the rules of | |
| 193 * RFC2396. The result is strictly ASCII. | |
| 194 */ | |
| 195 readonly attribute ACString asciiSpec; | |
| 196 | |
| 197 /** | |
| 198 * The URI host with an ASCII compatible encoding. Follows the IDNA | |
| 199 * draft spec for converting internationalized domain names (UTF-8) to | |
| 200 * ASCII for compatibility with existing internet infrasture. | |
| 201 */ | |
| 202 readonly attribute ACString asciiHost; | |
| 203 | |
| 204 /** | |
| 205 * The charset of the document from which this URI originated. An empty | |
| 206 * value implies UTF-8. | |
| 207 * | |
| 208 * If this value is something other than UTF-8 then the URI components | |
| 209 * (e.g., spec, prePath, username, etc.) will all be fully URL-escaped. | |
| 210 * Otherwise, the URI components may contain unescaped multibyte UTF-8 | |
| 211 * characters. | |
| 212 */ | |
| 213 readonly attribute ACString originCharset; | |
| 214 | |
| 215 /************************************************************************ | |
| 216 * Additional attribute & methods added for .ref support: | |
| 217 */ | |
| 218 | |
| 219 /** | |
| 220 * Returns the reference portion (the part after the "#") of the URI. | |
| 221 * If there isn't one, an empty string is returned. | |
| 222 * | |
| 223 * Some characters may be escaped. | |
| 224 */ | |
| 225 attribute AUTF8String ref; | |
| 226 | |
| 227 /** | |
| 228 * URI equivalence test (not a strict string comparison), ignoring | |
| 229 * the value of the .ref member. | |
| 230 * | |
| 231 * eg. http://foo.com/# == http://foo.com/ | |
| 232 * http://foo.com/#aaa == http://foo.com/#bbb | |
| 233 */ | |
| 234 boolean equalsExceptRef(in nsIURI other); | |
| 235 | |
| 236 /** | |
| 237 * Clones the current URI, clearing the 'ref' attribute in the clone. | |
| 238 */ | |
| 239 nsIURI cloneIgnoringRef(); | |
| 240 | |
| 241 /** | |
| 242 * returns a string for the current URI with the ref element cleared. | |
| 243 */ | |
| 244 readonly attribute AUTF8String specIgnoringRef; | |
| 245 | |
| 246 /** | |
| 247 * Returns if there is a reference portion (the part after the "#") of the URI. | |
| 248 */ | |
| 249 readonly attribute boolean hasRef; | |
| 250 }; |
