nsIURI

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:

RFC3490: Internationalizing Domain Names in Applications (IDNA)
RFC3986: Uniform Resource Identifier (URI): Generic Syntax
RFC3987: Internationalized Resource Identifiers

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.

Components of a URI

Method overview

Attributes

Exceptions thrown

Exceptions thrown

Exceptions thrown

Exceptions thrown

Exceptions thrown

Exceptions thrown

Methods

clone()

Parameters

Return value

cloneIgnoringRef()

Parameters

Return value

equals()

Parameters

Return value

equalsExceptRef()

Parameters

Return value

resolve()

Parameters

Return value

schemeIs()

Parameters

Return value

See also

Document Tags and Contributors