Public Member Functions | Public Attributes

nsIURI Interface Reference

URIs are essentially structured names for things -- anything. More...

import "nsIURI.idl";

Inheritance diagram for nsIURI:

List of all members.

Public Member Functions

boolean equals (in nsIURI other)
 URI equivalence test (not a strict string comparison).
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.
nsIURI clone ()
 Clones the current URI.
AUTF8String resolve (in AUTF8String relativePath)
 This method resolves a relative string into an absolute URI string, using this URI as the base.

Public Attributes

attribute AUTF8String spec
 Returns a string representation of the URI.
readonly attribute AUTF8String prePath
 The prePath (eg.
attribute ACString scheme
 The Scheme is the protocol to which this URI refers.
attribute AUTF8String userPass
 The username:password (or username only if value doesn't contain a ':').
attribute AUTF8String username
 The optional username and password, assuming the preHost consists of username:password.
attribute AUTF8String password
attribute AUTF8String hostPort
 The host:port (or simply the host, if port == -1).
attribute AUTF8String host
 The host is the internet domain name to which this URI refers.
attribute long port
 A port value of -1 corresponds to the protocol's default port (eg.
attribute AUTF8String path
 The path, typically including at least a leading '/' (but may also be empty, depending on the protocol).
readonly attribute ACString asciiSpec
 The URI spec with an ASCII compatible encoding.
readonly attribute ACString asciiHost
 The URI host with an ASCII compatible encoding.
readonly attribute ACString originCharset
 The charset of the document from which this URI originated.

Detailed Description

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 spec (RFC2396) [1], where the basic URI components are defined as such:

 
      ftp://username:password@hostname:portnumber/pathname
      \ /   \               / \      / \        /\       /

 [1] http://www.ietf.org/rfc/rfc2396.txt
 [2] http://www.ietf.org/internet-drafts/draft-ietf-idn-idna-06.txt
 [3] http://www.ietf.org/internet-drafts/draft-masinter-url-i18n-08.txt
 nsIURI - interface for an uniform resource identifier w/ i18n support.
 AUTF8String attributes may contain unescaped UTF-8 characters.
 Consumers should be careful to escape the UTF-8 strings as necessary, but
 should always try to "display" the UTF-8 version as provided by this
 interface.
 AUTF8String attributes may also contain escaped characters.
 Unescaping URI segments is unadvised unless there is intimate
 knowledge of the underlying charset or there is no plan to display (or
 otherwise enforce a charset on) the resulting URI substring.
 The correct way to create an nsIURI from a string is via
 nsIIOService.newURI.
 
Status:
FROZEN

Member Function Documentation

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

boolean nsIURI::equals ( in nsIURI  other  ) 

URI equivalence test (not a strict string comparison).

eg. http://foo.com:80/ == http://foo.com/

AUTF8String nsIURI::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.

boolean nsIURI::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).


Member Data Documentation

readonly attribute ACString nsIURI::asciiHost

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.

readonly attribute ACString nsIURI::asciiSpec

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.

attribute AUTF8String nsIURI::host

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.

attribute AUTF8String nsIURI::hostPort

The host:port (or simply the host, if port == -1).

Characters are NOT escaped.

readonly attribute ACString nsIURI::originCharset

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.

attribute AUTF8String nsIURI::password
attribute AUTF8String nsIURI::path

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

Some characters may be escaped.

attribute long nsIURI::port

A port value of -1 corresponds to the protocol's default port (eg.

-1 implies port 80 for http URIs).

readonly attribute AUTF8String nsIURI::prePath

The prePath (eg.

scheme://user:password:port) returns the string before the path. This is useful for authentication or managing sessions.

Some characters may be escaped.

attribute ACString nsIURI::scheme

The Scheme is the protocol to which this URI refers.

The scheme is restricted to the US-ASCII charset per RFC2396. Setting this is highly discouraged outside of a protocol handler implementation, since that will generally lead to incorrect results.

attribute AUTF8String nsIURI::spec

Returns a string representation of the URI.

Setting the spec causes the new spec to be parsed per the rules for the scheme the URI currently has. In particular, setting the spec to a URI string with a different scheme will generally produce incorrect results; no one outside of a protocol handler implementation should be doing that. If the URI stores information from the nsIIOService.newURI call used to create it other than just the parsed string, then behavior of this information on setting the spec attribute is undefined.

Some characters may be escaped.

attribute AUTF8String nsIURI::username

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

Some characters may be escaped.

attribute AUTF8String nsIURI::userPass

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

Some characters may be escaped.


The documentation for this interface was generated from the following file: