nsIURI

From MDC

nsIURI is an interface for an uniform resource identifier with internationalization support.

Contents 1 Interface Code 2 Methods 2.1 equals() 2.2 schemeIs() 2.3 clone() 2.4 resolve() 3 Attributes

nsIURI is defined in netwerk/base/public/nsIURI.idl. It is scriptable and has been frozen since Mozilla 1.0.0.

[edit] Interface Code

[scriptable, uuid(07a22cc0-0ce5-11d3-9331-00104ba0fd40)]
interface nsIURI : nsISupports
{
  attribute AUTF8String spec;
  readonly attribute AUTF8String prePath;
  attribute ACString scheme;
  attribute AUTF8String userPass;
  attribute AUTF8String username;
  attribute AUTF8String password;
  attribute AUTF8String hostPort;
  attribute AUTF8String host;
  attribute long port;
  attribute AUTF8String path;

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

  readonly attribute ACString asciiSpec;
  readonly attribute ACString asciiHost;
  readonly attribute ACString originCharset;
};

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 specification in RFC 2396, where the basic URI components are defined as such:

ftp://user:password@example.org:12345/path/leaf 

Component	Value in Example
scheme	ftp
userPass	user:password
host	example.org
port	12345
path	/path/leaf
prePath	ftp://user:password@example.org:12345

[edit] Methods

[edit] equals()

boolean equals (in nsIURI other);

URI equivalence test (not a strict string comparison). eg. http://example.com:80/ == http://example.com/

[edit] schemeIs()

boolean schemeIs(in string scheme);

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).

[edit] clone()

nsIURI clone();

Clones the current URI. For some protocols, this is more than just an optimization. For example, under MacOS, the spec of a file URL does not necessarily uniquely identify a file since two volumes could share the same name.

[edit] resolve()

AUTF8String resolve(in AUTF8String relativePath);

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.

[edit] Attributes

Attribute	Type	Description
spec	nsACString (UTF-8)	Returns a string representation of the URI. Setting the spec causes the new spec to be parsed, initializing the URI.
prePath	readonly nsACString (UTF-8)	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.
scheme	nsACString (US-ASCII)	The Scheme is the protocol to which this URI refers. The scheme is restricted to the US-ASCII charset per RFC2396.
userPass	nsACString (UTF-8)	The username:password (or username only if value doesn't contain a ':') Some characters may be escaped.
username	nsACString (UTF-8)	The optional username, assuming the preHost consists of username:password. Some characters may be escaped.
password	nsACString (UTF-8)	The optional password, assuming the preHost consists of username:password. Some characters may be escaped.
hostPort	nsACString (UTF-8)	The host:port (or simply the host, if port == -1). Characters are NOT escaped.
host	nsACString (UTF-8)	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.
port	PRInt32	A port value of -1 corresponds to the protocol's default port (eg. -1 implies port 80 for http URIs).
path	nsACString (UTF-8)	The path, typically including at least a leading '/' (but may also be empty, depending on the protocol). Some characters may be escaped.
asciiSpec	readonly nsACString (US-ASCII)	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.
asciiHost	readonly nsACString (US-ASCII)	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.
originCharset	readonly nsACString	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.