netwerk/base/public/nsIURI.idlScriptable
This is an interface for an uniform resource identifier with internationalization support, offering attributes that allow setting and querying the basic components of a URI, and methods for performing basic operations on URIs.
Inherits from: nsISupports Last changed in Gecko 6.0 (Firefox 6.0 / Thunderbird 6.0 / SeaMonkey 2.3)

See the following RFCs for details:

Subclasses of nsIURI, such as nsIURL, impose further structure on the URI.

To create an nsIURI object, you should use nsIIOService.newURI(), like this:

function makeURI(aURL, aOriginCharset, aBaseURI) {
  var ioService = Components.classes["@mozilla.org/network/io-service;1"]
                  .getService(Components.interfaces.nsIIOService);
  return ioService.newURI(aURL, aOriginCharset, aBaseURI);
}

Components of a URI

prePath path
scheme   userPass   host   port   ref
ftp :// username@password @ hostname : portnumber /pathname?query=value #ref

Method overview

nsIURI clone();
nsIURI cloneIgnoringRef();
boolean equals(in nsIURI other);
boolean equalsExceptRef(in nsIURI other);
AUTF8String resolve(in AUTF8String relativePath);
boolean schemeIs(in string scheme);

Attributes

Attribute Type Description
asciiHost ACString

The URI host with an ASCII compatible encoding. Follows the IDNA draft specification for converting internationalized domain names (UTF-8) to ASCII for compatibility with existing Internet infrastructure. Read only.

Note: IPv6 addresses are not enclosed in square brackets.
asciiSpec ACString (US-ASCII) The URI spec with an ASCII compatible encoding. The host portion follows the IDNA draft spec. Other parts are URL-escaped per the rules of RFC3986. The result is strictly ASCII. Read only.
hasRef boolean Returns if there is a reference portion (the part after the "#") of the URI.
host AUTF8String

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.

Exceptions thrown
NS_ERROR_FAILURE
If host is not applicable to the URI scheme (e.g. about:blank)
Note: Characters are not escaped. IPv6 addresses are not enclosed in square brackets.
hostPort AUTF8String

The "host:port" part of the URI (or simply the host, if port is -1).

Exceptions thrown
NS_ERROR_FAILURE
If hostPort is not applicable to the URI scheme (e.g. about:blank)
Note: Characters are not escaped.
originCharset ACString

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 (for example spec, prePath, username, and so on) are all fully URL-escaped. Otherwise, the URI components may contain unescaped multibyte UTF-8 characters. Read only.
password AUTF8String

The optional password, assuming the preHost consists of "username:password".

Exceptions thrown
NS_ERROR_FAILURE
If password is not applicable to the URI scheme (e.g. about:blank)

Note: Some characters may be escaped.
path AUTF8String

The path, typically including at least a leading '/' (but may also be empty, depending on the protocol).

Note: Some characters may be escaped.
port long

The URI's port. A port value of -1 corresponds to the protocol's default port (for example -1 implies port 80 for HTTP URIs).

Exceptions thrown
NS_ERROR_FAILURE
If port is not applicable to the URI scheme (e.g. about:blank)
prePath AUTF8String

The prePath returns the string before the path (such as "scheme://user:password@host:port").

This is related to the Web Origin Concept of RFC6454.

This is useful for authentication, managing sessions, or for checking the origin of an URI to prevent cross-site scripting attacks while using methods such as window.postMessage().

Note: Some characters may be escaped.
Read only.
ref AUTF8String

Returns the reference portion (the part after the "#") of the URI. If there is not one, an empty string is returned.

Note: Some characters may be escaped.
scheme ACString (US-ASCII)

The scheme is the protocol to which this URI refers. The scheme is restricted to the US-ASCII charset per RFC3986.

Warning: Setting this is highly discouraged outside of a protocol handler implementation, since doing so will generally lead to unpredictable results.
spec AUTF8String

Returns a string representation of the URI. Setting the spec causes the new spec to be parsed using the rules for the scheme the URI currently has. If the string cannot be parsed as a URI, NS_ERROR_MALFORMED_URI thrown.

Warning: Because parsing the string is done using the current URI's scheme, setting the spec to a URI with a different scheme will produce incorrect results. Therefore, only protocol handler implementations should do this.

If the URI stores information from the nsIIOService interface's nsIIOService.newURI() call that created it, other than just the parsed string, the behavior of this information when setting the spec attribute is undefined.

Note: Some characters may be escaped.
specIgnoringRef AUTF8String Returns a string representation of the URI without the ref (part after the #) portion.

Note: Some characters may be escaped.
username AUTF8String

The optional username, assuming the preHost consists of "username:password".

Exceptions thrown
NS_ERROR_FAILURE
If username is not applicable to the URI scheme (e.g. about:blank)
Note: Some characters may be escaped.
userPass AUTF8String

The "username:password" (or username only if the value doesn't contain a ':').

Exceptions thrown
NS_ERROR_FAILURE
If userPass is not applicable to the URI scheme (e.g. about:blank)
Note: Some characters may be escaped.

Methods

clone()

Clones the URI, returning a new nsIURI object.

Note: For some protocols, this is more than just an optimization. For example, under Mac OS X, the spec of a file URI doesn't necessarily uniquely identify a file, since two volumes can have the same name.
nsIURI clone();
Parameters

None.

Return value

An nsIURI object that represents the same URI as the current nsIURI.

cloneIgnoringRef()

Clones the current URI, clearing the 'ref' attribute in the clone.

nsIURI cloneIgnoringRef();
Parameters

None.

Return value

An nsIURI object that represents the same URI as the current nsIURI without the 'ref' attribute.

equals()

Compares the current URI with another URI.

Note: This is more than a string comparison, as two different URI strings can represent the same location. For example, comparing "http://foo.com:80/" and "http://foo.com/" will return true.
boolean equals(
  in nsIURI other
);
Parameters
other
Another nsIURI to compare to.
Return value

true if the two URIs represent the same location; otherwise false.

equalsExceptRef()

Compares the current URI with another URI, ignoring the value of the .ref member.

Note: This is more than a string comparison, as two different URI strings can represent the same location. For example, comparing "http://foo.com/#" and "http://foo.com/" or "http://foo.com/#aaa" and "http://foo.com/#bbb" will return true.
boolean equalsExceptRef(
  in nsIURI other
);
Parameters
other
Another nsIURI to compare to.
Return value

true if the two URIs represent the same location; otherwise false.

resolve()

Resolves a relative URI string, using this URI as the base.

Note: Some implementations may have no concept of a relative URI.

AUTF8String resolve(
  in AUTF8String relativePath
);
Parameters
relativePath
The relative path to resolve.
Return value

The resolved absolute URI string.

schemeIs()

Quickly reports whether the nsIURI represents a URI with the specified scheme. This comparison is case-insensitive.

Note: This is an optimization, allowing you to check the scheme of the URI without having to get the scheme and do the comparison yourself; this saves memory allocations.

boolean schemeIs(
  in string scheme
);
Parameters
scheme
A string representing the scheme to compare to.
Return value

true if the URI is for the specified scheme; otherwise false.

See also