nsIProtocolHandler

netwerk/base/nsIProtocolHandler.idlScriptable

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.

Method overview

Attributes

Constants

Methods

allowPort()

Parameters

Return value

newChannel()

Parameters

Return value

newURI()

Parameters

Return value

See also

Document Tags and Contributors