nsIURI

IID:07a22cc0-0ce5-11d3-9331-00104ba0fd40
Inherits From:nsISupports
Status:FROZEN

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 \ / \ / \ / \ /\ / - --------------- ------ -------- ------- Path Port Host / UserPass / Scheme / \ / -------------------------------- PrePath

The definition of the URI components has been extended to allow for internationalized domain names [2] and the more generic IRI structure [3].

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

An object of this interface must be created in the following way:

ioService.newURI(uri, charset, baseuri);

This interface is implemented by the following components:


Properties

readonly ACString 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 ACString 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.

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

AUTF8String hostPort

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

Characters are NOT escaped.

readonly ACString 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.

AUTF8String password

AUTF8String path

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

Some characters may be escaped.

PRInt32 port

A port value of -1 corresponds to the protocol's default port (eg. -1 implies port 80 for http URIs).

readonly AUTF8String prePath

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.

ACString scheme

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

AUTF8String spec

Returns a string representation of the URI. Setting the spec causes the new spec to be parsed, initializing the URI.

Some characters may be escaped.

AUTF8String username

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

Some characters may be escaped.

AUTF8String userPass

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

Some characters may be escaped.


Methods

nsIURI clone ( ) PRBool equals ( nsIURI other ) AUTF8String resolve ( AUTF8String relativePath ) PRBool schemeIs ( char* scheme )

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.


PRBool equals ( nsIURI other )

URI equivalence test (not a strict string comparison).

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

Arguments:
other

AUTF8String resolve ( 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.

Arguments:
relativePath

PRBool schemeIs ( char* 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).

Arguments:
scheme

References

This interface is the type of the following properties:

imgIRequest.URI, nsIChannel.URI, nsIChannel.originalURI, nsIContextMenuInfo.backgroundImageSrc, nsIContextMenuInfo.imageSrc, nsIDOMParser.baseURI, nsIDOMPopupBlockedEvent.popupWindowURI, nsIDOMPopupBlockedEvent.requestingWindowURI, nsIDocShellLoadInfo.referrer, nsIDownload.source, nsIDownload.target, nsIHelperAppLauncher.source, nsIHistoryEntry.URI, nsIHttpChannel.referrer, nsIHttpChannelInternal.documentURI, nsIImageLoadingContent.currentURI, nsIIncrementalDownload.URI, nsIIncrementalDownload.finalURI, nsIJARURI.JARFile, nsIMozIconURI.iconFile, nsIMsgMailNewsUrl.baseURI, nsIPrincipal.URI, nsIPrincipal.domain, nsISHEntry.referrerURI, nsIWebNavigation.currentURI, nsIWebNavigation.referringURI

This interface is passed as an argument to the following methods:

imgICache.findEntryProperties, imgICache.removeEntry, imgILoader.loadImage, nsIAboutModule.newChannel, nsIAppShellService.createTopLevelWindow, nsIBrowserDOMWindow.openURI, nsIBrowserHistory.addPageWithDetails, nsIBrowserHistory.hidePage, nsIBrowserHistory.markPageAsTyped, nsIBrowserHistory.removePage, nsICRLManager.importCrl, nsIChromeRegistry.convertChromeURL, nsIContentPolicy.shouldLoad, nsIContentPolicy.shouldProcess, nsICookieConsent.getConsent, nsICookiePermission.canAccess, nsICookiePermission.canSetCookie, nsICookiePermission.setAccess, nsICookieService.getCookieString, nsICookieService.getCookieStringFromHttp, nsICookieService.setCookieString, nsICookieService.setCookieStringFromHttp, nsIDOMPopupBlockedEvent.initPopupBlockedEvent, nsIDocShell.internalLoad, nsIDocShell.loadStream, nsIDocShell.loadURI, nsIDocShell.setCurrentURI, nsIDownloadManager.addDownload, nsIDownloadProgressListener.onLocationChange, nsIExternalProtocolService.loadURI, nsIExternalProtocolService.loadUrl, nsIGlobalHistory2.addURI, nsIGlobalHistory2.isVisited, nsIGlobalHistory2.setPageTitle, nsIGnomeVFSService.showURI, nsIIOService.newChannel, nsIIOService.newChannelFromURI, nsIIOService.newURI, nsIImapMockChannel.setURI, nsIImapProtocol.GetRunningUrl, nsIImapProtocol.LoadImapUrl, nsIImapService.addMessageFlags, nsIImapService.appendMessageFromFile, nsIImapService.biff, nsIImapService.deleteAllMessages, nsIImapService.deleteMessages, nsIImapService.discoverAllAndSubscribedFolders, nsIImapService.discoverAllFolders, nsIImapService.discoverChildren, nsIImapService.discoverLevelChildren, nsIImapService.expunge, nsIImapService.fetchMessage, nsIImapService.getHeaders, nsIImapService.liteSelectFolder, nsIImapService.noop, nsIImapService.onlineMessageCopy, nsIImapService.selectFolder, nsIImapService.setMessageFlags, nsIImapService.subtractMessageFlags, nsIIncrementalDownload.init, nsIInputStreamChannel.setURI, nsIMIMEService.getTypeFromURI, nsIMimeEmitter.Initialize, nsIMimeStreamConverter.SetStreamURI, nsIMsgAccountManager.findServerByURI, nsIMsgComposeService.OpenComposeWindowWithURI, nsIMsgComposeService.getParamsForMailto, nsIMsgImapMailFolder.playbackOfflineFolderCreate, nsIMsgImapMailFolder.setImapFlags, nsIMsgMessageFetchPartService.fetchMimePart, nsIMsgMessageService.CopyMessage, nsIMsgMessageService.CopyMessages, nsIMsgMessageService.DisplayMessage, nsIMsgMessageService.DisplayMessageForPrinting, nsIMsgMessageService.GetUrlForUri, nsIMsgMessageService.SaveMessageToDisk, nsIMsgSend.deliverAsMailExit, nsIMsgSend.deliverAsNewsExit, nsINNTPProtocol.Initialize, nsINNTPProtocol.LoadNewsUrl, nsINntpIncomingServer.getNntpConnection, nsIPermissionManager.add, nsIPermissionManager.testPermission, nsIPluginHost.instantiateEmbeddedPlugin, nsIPluginHost.instantiateFullPagePlugin, nsIPluginHost.setUpPluginInstance, nsIPop3Sink.IncorporateBegin, nsIPopupWindowManager.testPermission, nsIPrefetchService.prefetchURI, nsIProtocolHandler.newChannel, nsIProtocolHandler.newURI, nsIProtocolProxyCallback.onProxyAvailable, nsIProtocolProxyFilter.applyFilter, nsIProtocolProxyService.asyncResolve, nsIProtocolProxyService.getFailoverForProxy, nsIProtocolProxyService.resolve, nsIProxiedProtocolHandler.newProxiedChannel, nsIRDFXMLParser.parseAsync, nsIRDFXMLParser.parseString, nsIRefreshURI.refreshURI, nsIRefreshURI.setupRefreshURIFromHeader, nsIResProtocolHandler.resolveURI, nsIResProtocolHandler.setSubstitution, nsISHEntry.create, nsISHEntry.setURI, nsISHistoryListener.OnHistoryGoBack, nsISHistoryListener.OnHistoryGoForward, nsISHistoryListener.OnHistoryGotoIndex, nsISHistoryListener.OnHistoryNewEntry, nsISHistoryListener.OnHistoryReload, nsIScriptLoaderObserver.scriptAvailable, nsIScriptSecurityManager.checkConnect, nsIScriptSecurityManager.checkLoadURI, nsIScriptSecurityManager.checkLoadURIFromScript, nsIScriptSecurityManager.checkLoadURIWithPrincipal, nsIScriptSecurityManager.checkSameOrigin, nsIScriptSecurityManager.checkSameOriginURI, nsIScriptSecurityManager.getCertificatePrincipal, nsIScriptSecurityManager.getCodebasePrincipal, nsIScriptSecurityManager.securityCompareURIs, nsISmtpService.SendMailMessage, nsIStandardURL.init, nsIStyleSheetService.loadAndRegisterSheet, nsIStyleSheetService.sheetRegistered, nsIStyleSheetService.unregisterSheet, nsISyncLoadDOMService.loadDocument, nsISyncLoadDOMService.loadDocumentAsXML, nsISyncLoadDOMService.loadLocalDocument, nsIToolkitChromeRegistry.processContentsManifest, nsITransfer.init, nsIURI.equals, nsIURIChecker.init, nsIURIContentListener.onStartURIOpen, nsIURIFixup.createExposableURI, nsIURL.getCommonBaseSpec, nsIURL.getRelativeSpec, nsIURLFetcher.fireURLRequest, nsIUrlListener.OnStartRunningUrl, nsIUrlListener.OnStopRunningUrl, nsIWebBrowserPersist.saveURI, nsIWebBrowserStream.openStream, nsIWebNavigation.loadURI, nsIWebProgressListener.onLocationChange, nsIWebScriptsAccessService.canAccess, nsIWindowCreator2.createChromeWindow2, nsIXULChromeRegistry.allowScriptsForPackage, nsIXULOverlayProvider.getStyleOverlays, nsIXULOverlayProvider.getXULOverlays, nsPICertNotification.onCertAvailable

This interface is returned from the following methods:

nsIAccessibleHyperLink.getURI, nsIChromeRegistry.convertChromeURL, nsICommandLine.resolveURI, nsIFileProtocolHandler.newFileURI, nsIFileProtocolHandler.readURLFile, nsIIOService.newFileURI, nsIIOService.newURI, nsIImapIncomingServer.subscribeToFolder, nsIImapService.createFolder, nsIImapService.deleteFolder, nsIImapService.ensureFolderExists, nsIImapService.fetchCustomMsgAttribute, nsIImapService.getFolderAdminUrl, nsIImapService.issueCommandOnMsgs, nsIImapService.listFolder, nsIImapService.moveFolder, nsIImapService.renameLeaf, nsIImapService.storeCustomKeywords, nsIImapService.subscribeFolder, nsIImapService.unsubscribeFolder, nsIImapService.updateFolderStatus, nsILocalMailIncomingServer.getNewMail, nsIMailboxService.ParseMailbox, nsIMovemailService.CheckForNewMail, nsIMovemailService.GetNewMail, nsIMsgImapMailFolder.fetchCustomMsgAttribute, nsIMsgImapMailFolder.issueCommandOnMsgs, nsIMsgImapMailFolder.storeCustomKeywords, nsIMsgMessageFetchPartService.fetchMimePart, nsIMsgMessageService.streamMessage, nsINntpService.cancelMessage, nsINntpService.fetchMessage, nsINntpService.getNewNews, nsINntpService.postMessage, nsIPop3Service.CheckForNewMail, nsIPop3Service.GetNewMail, nsIProtocolHandler.newURI, nsIResProtocolHandler.getSubstitution, nsIURI.clone, nsIURIFixup.createExposableURI, nsIURIFixup.createFixupURI

Reference documentation is generated from Mozilla's source.

Add a note User Contributed Notes
August 28, 2004, 4:36 pm jruderman at hmc dot edu
The correct way to construct an nsIURI is Components. classes["@mozilla.org/network/io-service;1"]. getService(Components.interfaces.nsIIOService). newURI(...);

If you use Components. classes['@mozilla.org/network/standard-url;1']. createInstance(Components.interfaces.nsIURI); and then set its spec, you'll end up with an nsIURI that works for some things but not for other things.

Copyright © 1999 - 2005 XULPlanet.com