nsIProtocolHandler

This interface is used to implement protocol handlers. If you wish to create a new protocol handler, you need to implement this interface.
Inherits from: nsISupports Last changed in Gecko 2.0 (Firefox 4 / Thunderbird 3.3 / SeaMonkey 2.1)

Method overview

boolean allowPort(in long port, in string scheme);
nsIChannel newChannel(in nsIURI aURI);
nsIURI newURI(in AUTF8String aSpec, in string aOriginCharset, in nsIURI aBaseURI);

Attributes

Attribute Type Description
defaultPort long The default port is the port the protocol uses by default. If the protocol doesn't need a port (for example, the "about" protocol), this attribute is -1. Read only.
protocolFlags unsigned long Protocol-specific flags. Read only.

Note: Starting with Firefox 3, one of URI_LOADABLE_BY_ANYONE, URI_DANGEROUS_TO_LOAD, URI_IS_UI_RESOURCE, or URI_IS_LOCAL_FILE must be set on every protocol handler. Current versions of Firefox assume that the URI has URI_LOADABLE_BY_ANYONE set, but this will not work starting with the Mozilla 2 platform.
scheme ACString The scheme for this protocol ("file", "http", and so forth). Read only.

Constants

Constant Value Description
URI_STD 0 A standard full URI with authority component and understanding relative URIs; this includes http and ftp, for example.
URI_NORELATIVE 1<<0 The protocol doesn't support relative URIs (for example, about and javascript).
URI_NOAUTH 1<<1 The protocol doesn't have an authority component (for example, file).
URI_INHERITS_SECURITY_CONTEXT 1<<4 URIs for this protocol have no inherent security context, so documents loaded using this protocol should inherit the security context of the document that loads them.
URI_FORBIDS_AUTOMATIC_DOCUMENT_REPLACEMENT 1<<5 "Automatic" loads that would replace the document (such as a meta refresh, certain types of XLinks, and other non-user-triggered loads) are not allowed if the originating URI has this protocol flag. Keep in mind that the decision of what constitutes an automatic load is made externally, by the caller of nsIScriptSecurityManager.CheckLoadURI(). Typically, this flag is used by protocols that show highly untrusted content in a viewing area that the user expects to have a lot of control over, such as an email reader.
URI_LOADABLE_BY_ANYONE 1<<6 Anyone can load the URIs for this protocol; for example, any web site can load a URI for this protocol. Web-safe protocols such as HTTP should use this flag.
URI_DANGEROUS_TO_LOAD 1<<7 URIs using this protocol are unsafe if loaded by untrusted web content and may only be loaded by privileged code (for example, code that has the system principal). Various internal protocols use this flag.
URI_IS_UI_RESOURCE 1<<8 The URIs for this protocol refer to resources that are part of the application's user interface. There are cases in which such resources may be made accessible to untrusted content such as web pages, so this is less restrictive than URI_DANGEROUS_TO_LOAD but more restrictive than URI_LOADABLE_BY_ANYONE.
URI_IS_LOCAL_FILE 1<<9 URIs for this protocol from other origins should only be allowed if those origins should have access to the local file system. It's up to the application to decide what origins should have such access. Protocols like file that point to local data should set this flag.
URI_LOADABLE_BY_SUBSUMERS 1<<14 The URIs for this protocol can be loaded only by callers with a principal that subsumes this uri. For example, privileged code and websites that are same origin as this uri.
URI_NON_PERSISTABLE 1<<10 Loading channels from this protocol has side-effects that make it unsuitable for saving to a local file.
URI_DOES_NOT_RETURN_DATA 1<<11

Channels using this protocol never call OnDataAvailable() on the listener passed to AsyncOpen(), and therefore do not return any usable data.

URI_IS_LOCAL_RESOURCE 1<<12 URIs for this protocol are considered to be local resources. This could be a local file (URI_IS_LOCAL_FILE), a UI resource (URI_IS_UI_RESOURCE), or something else that would not hit the network.
URI_OPENING_EXECUTES_SCRIPT 1<<13 URIs for this protocol execute script when they are opened.
ALLOWS_PROXY 1<<2 This protocol handler can be proxied via SOCKS or HTTP (such as IRC, SMTP, and HTTP, for example). If the protocol supports transparent proxying, the handler should implement the nsIProxiedProtocolHandler interface. If the protocol only supports HTTP proxying, it doesn't need to support nsIProxiedProtocolHandler, but should instead set the ALLOWS_PROXY_HTTP flag.
ALLOWS_PROXY_HTTP 1<<3 The protocol handler can be proxied using an HTTP proxy (for example, HTTP and FTP). nsIIOService.newChannelFromURI() will feed URIs from this protocol handler to the HTTP protocol handler instead. This flag is ignored if ALLOWS_PROXY is not set.

Methods

allowPort()

Lets a protocol override blacklisted ports. This method is called when there's an attempt to connect to a port that is blacklisted. For example, for most protocols, port 25 (Simple Mail Transfer Protocol) is banned. When a URI containing this port number is encountered, this method is called to ask if the protocol handler wants to override the ban.

boolean allowPort(
  in long port,
  in string scheme
);
Parameters
port
The port for which an override is being requested.
scheme
The scheme for which an override is being requested.
Return value

Return true if the override is approved; otherwise, return false.

newChannel()

Constructs a new channel from the given URI for this protocol handler.

nsIChannel newChannel(
  in nsIURI aURI
);
Parameters
aURI
The URI for which to construct a channel.
Return value

Return the newly constructed channel.

newURI()

Makes a URI object that is suitable for loading by this protocol, where the URI string is given as an UTF-8 string. The caller may provide the charset from which the URI string originated, so that the URI string can be translated back to that charset (if necessary) before communicating with, for example, the origin server of the URI string. (Many servers do not support UTF-8 IRIs at the present time, so we must be careful about tracking the native charset of the origin server.)

nsIURI newURI(
  in AUTF8String aSpec,
  in string aOriginCharset,
  in nsIURI aBaseURI
);
Parameters
aSpec
The URI string in UTF-8 encoding. Depending on the protocol's implementation, Unicode character sequences may or may not be %xx escaped.
aOriginCharset
The character set of the document from which this URI string originated. This corresponds to the character set that should be used when communicating this URI to an origin server. If this is null, then UTF-8 encoding is assumed and no character transformation is not performed.
aBaseURI
If null, aSpec must specify an absolute URI. Otherwise, aSpec may be resolved relative to aBaseURI, depending on the protocol. If the protocol has no concept of relative URIs, this parameter is ignored.
Return value

The new URI object suitable for loading using the protocol.

See also