1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/netwerk/base/public/nsIURI.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,250 @@
1.4 +/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#include "nsISupports.idl"
1.10 +
1.11 +/**
1.12 + * URIs are essentially structured names for things -- anything. This interface
1.13 + * provides accessors to set and query the most basic components of an URI.
1.14 + * Subclasses, including nsIURL, impose greater structure on the URI.
1.15 + *
1.16 + * This interface follows Tim Berners-Lee's URI spec (RFC2396) [1], where the
1.17 + * basic URI components are defined as such:
1.18 + * <pre>
1.19 + * ftp://username:password@hostname:portnumber/pathname#ref
1.20 + * \ / \ / \ / \ /\ \ /
1.21 + * - --------------- ------ -------- | -
1.22 + * | | | | | |
1.23 + * | | | | | Ref
1.24 + * | | | Port \ /
1.25 + * | | Host / --------
1.26 + * | UserPass / |
1.27 + * Scheme / Path
1.28 + * \ /
1.29 + * --------------------------------
1.30 + * |
1.31 + * PrePath
1.32 + * </pre>
1.33 + * The definition of the URI components has been extended to allow for
1.34 + * internationalized domain names [2] and the more generic IRI structure [3].
1.35 + *
1.36 + * Note also that the RFC defines #-separated fragment identifiers as being
1.37 + * "not part of the URI". Despite this, we bundle them as part of the URI, for
1.38 + * convenience.
1.39 + *
1.40 + * [1] http://www.ietf.org/rfc/rfc2396.txt
1.41 + * [2] http://www.ietf.org/internet-drafts/draft-ietf-idn-idna-06.txt
1.42 + * [3] http://www.ietf.org/internet-drafts/draft-masinter-url-i18n-08.txt
1.43 + */
1.44 +
1.45 +%{C++
1.46 +#undef GetPort // XXX Windows!
1.47 +#undef SetPort // XXX Windows!
1.48 +%}
1.49 +
1.50 +/**
1.51 + * nsIURI - interface for an uniform resource identifier w/ i18n support.
1.52 + *
1.53 + * AUTF8String attributes may contain unescaped UTF-8 characters.
1.54 + * Consumers should be careful to escape the UTF-8 strings as necessary, but
1.55 + * should always try to "display" the UTF-8 version as provided by this
1.56 + * interface.
1.57 + *
1.58 + * AUTF8String attributes may also contain escaped characters.
1.59 + *
1.60 + * Unescaping URI segments is unadvised unless there is intimate
1.61 + * knowledge of the underlying charset or there is no plan to display (or
1.62 + * otherwise enforce a charset on) the resulting URI substring.
1.63 + *
1.64 + * The correct way to create an nsIURI from a string is via
1.65 + * nsIIOService.newURI.
1.66 + *
1.67 + * NOTE: nsBinaryInputStream::ReadObject contains a hackaround to intercept the
1.68 + * old (pre-gecko6) nsIURI IID and swap in the current IID instead, in order
1.69 + * for sessionstore to work after an upgrade. If this IID is revved further,
1.70 + * we will need to add additional checks there for all intermediate IIDs, until
1.71 + * nsPrincipal is fixed to serialize its URIs as nsISupports (bug 662693).
1.72 + */
1.73 +[scriptable, uuid(395fe045-7d18-4adb-a3fd-af98c8a1af11)]
1.74 +interface nsIURI : nsISupports
1.75 +{
1.76 + /************************************************************************
1.77 + * The URI is broken down into the following principal components:
1.78 + */
1.79 +
1.80 + /**
1.81 + * Returns a string representation of the URI. Setting the spec causes
1.82 + * the new spec to be parsed per the rules for the scheme the URI
1.83 + * currently has. In particular, setting the spec to a URI string with a
1.84 + * different scheme will generally produce incorrect results; no one
1.85 + * outside of a protocol handler implementation should be doing that. If
1.86 + * the URI stores information from the nsIIOService.newURI call used to
1.87 + * create it other than just the parsed string, then behavior of this
1.88 + * information on setting the spec attribute is undefined.
1.89 + *
1.90 + * Some characters may be escaped.
1.91 + */
1.92 + attribute AUTF8String spec;
1.93 +
1.94 + /**
1.95 + * The prePath (eg. scheme://user:password@host:port) returns the string
1.96 + * before the path. This is useful for authentication or managing sessions.
1.97 + *
1.98 + * Some characters may be escaped.
1.99 + */
1.100 + readonly attribute AUTF8String prePath;
1.101 +
1.102 + /**
1.103 + * The Scheme is the protocol to which this URI refers. The scheme is
1.104 + * restricted to the US-ASCII charset per RFC2396. Setting this is
1.105 + * highly discouraged outside of a protocol handler implementation, since
1.106 + * that will generally lead to incorrect results.
1.107 + */
1.108 + attribute ACString scheme;
1.109 +
1.110 + /**
1.111 + * The username:password (or username only if value doesn't contain a ':')
1.112 + *
1.113 + * Some characters may be escaped.
1.114 + */
1.115 + attribute AUTF8String userPass;
1.116 +
1.117 + /**
1.118 + * The optional username and password, assuming the preHost consists of
1.119 + * username:password.
1.120 + *
1.121 + * Some characters may be escaped.
1.122 + */
1.123 + attribute AUTF8String username;
1.124 + attribute AUTF8String password;
1.125 +
1.126 + /**
1.127 + * The host:port (or simply the host, if port == -1).
1.128 + *
1.129 + * Characters are NOT escaped.
1.130 + */
1.131 + attribute AUTF8String hostPort;
1.132 +
1.133 + /**
1.134 + * The host is the internet domain name to which this URI refers. It could
1.135 + * be an IPv4 (or IPv6) address literal. If supported, it could be a
1.136 + * non-ASCII internationalized domain name.
1.137 + *
1.138 + * Characters are NOT escaped.
1.139 + */
1.140 + attribute AUTF8String host;
1.141 +
1.142 + /**
1.143 + * A port value of -1 corresponds to the protocol's default port (eg. -1
1.144 + * implies port 80 for http URIs).
1.145 + */
1.146 + attribute long port;
1.147 +
1.148 + /**
1.149 + * The path, typically including at least a leading '/' (but may also be
1.150 + * empty, depending on the protocol).
1.151 + *
1.152 + * Some characters may be escaped.
1.153 + */
1.154 + attribute AUTF8String path;
1.155 +
1.156 +
1.157 + /************************************************************************
1.158 + * An URI supports the following methods:
1.159 + */
1.160 +
1.161 + /**
1.162 + * URI equivalence test (not a strict string comparison).
1.163 + *
1.164 + * eg. http://foo.com:80/ == http://foo.com/
1.165 + */
1.166 + boolean equals(in nsIURI other);
1.167 +
1.168 + /**
1.169 + * An optimization to do scheme checks without requiring the users of nsIURI
1.170 + * to GetScheme, thereby saving extra allocating and freeing. Returns true if
1.171 + * the schemes match (case ignored).
1.172 + */
1.173 + boolean schemeIs(in string scheme);
1.174 +
1.175 + /**
1.176 + * Clones the current URI.
1.177 + */
1.178 + nsIURI clone();
1.179 +
1.180 + /**
1.181 + * This method resolves a relative string into an absolute URI string,
1.182 + * using this URI as the base.
1.183 + *
1.184 + * NOTE: some implementations may have no concept of a relative URI.
1.185 + */
1.186 + AUTF8String resolve(in AUTF8String relativePath);
1.187 +
1.188 +
1.189 + /************************************************************************
1.190 + * Additional attributes:
1.191 + */
1.192 +
1.193 + /**
1.194 + * The URI spec with an ASCII compatible encoding. Host portion follows
1.195 + * the IDNA draft spec. Other parts are URL-escaped per the rules of
1.196 + * RFC2396. The result is strictly ASCII.
1.197 + */
1.198 + readonly attribute ACString asciiSpec;
1.199 +
1.200 + /**
1.201 + * The URI host with an ASCII compatible encoding. Follows the IDNA
1.202 + * draft spec for converting internationalized domain names (UTF-8) to
1.203 + * ASCII for compatibility with existing internet infrasture.
1.204 + */
1.205 + readonly attribute ACString asciiHost;
1.206 +
1.207 + /**
1.208 + * The charset of the document from which this URI originated. An empty
1.209 + * value implies UTF-8.
1.210 + *
1.211 + * If this value is something other than UTF-8 then the URI components
1.212 + * (e.g., spec, prePath, username, etc.) will all be fully URL-escaped.
1.213 + * Otherwise, the URI components may contain unescaped multibyte UTF-8
1.214 + * characters.
1.215 + */
1.216 + readonly attribute ACString originCharset;
1.217 +
1.218 + /************************************************************************
1.219 + * Additional attribute & methods added for .ref support:
1.220 + */
1.221 +
1.222 + /**
1.223 + * Returns the reference portion (the part after the "#") of the URI.
1.224 + * If there isn't one, an empty string is returned.
1.225 + *
1.226 + * Some characters may be escaped.
1.227 + */
1.228 + attribute AUTF8String ref;
1.229 +
1.230 + /**
1.231 + * URI equivalence test (not a strict string comparison), ignoring
1.232 + * the value of the .ref member.
1.233 + *
1.234 + * eg. http://foo.com/# == http://foo.com/
1.235 + * http://foo.com/#aaa == http://foo.com/#bbb
1.236 + */
1.237 + boolean equalsExceptRef(in nsIURI other);
1.238 +
1.239 + /**
1.240 + * Clones the current URI, clearing the 'ref' attribute in the clone.
1.241 + */
1.242 + nsIURI cloneIgnoringRef();
1.243 +
1.244 + /**
1.245 + * returns a string for the current URI with the ref element cleared.
1.246 + */
1.247 + readonly attribute AUTF8String specIgnoringRef;
1.248 +
1.249 + /**
1.250 + * Returns if there is a reference portion (the part after the "#") of the URI.
1.251 + */
1.252 + readonly attribute boolean hasRef;
1.253 +};
