Mozilla

• About
• Developers
• Store
• Support
• Products

nsIProtocolHandler

---

This interface provides protocol management.

Methods

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 URIs at the present time, so we must be careful about tracking the native charset of the origin server.)

Syntax:

nsIURI nsIProtocolHandler::newURI(in AUTF8String aSpec,
	in string aOriginCharset,in nsIURI aBaseURI) 

Parameters:

aSpec: The URI string in UTF-8 encoding. Depending on the protocol implementation, unicode character sequences may or may not be %xx escaped.

aOriginCharset: The charset of the document from which this URI string originated. This corresponds to the charset that should be used when communicating this URI to an origin server, for example. If null, then UTF-8 encoding is assumed (i.e., no charset transformation from aSpec).

aBaseURI:If null, aSpec must specify an absolute URI. Otherwise, aSpec will be resolved as relative aBaseURI.

Returns:

The URI object.

newChannel

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

Syntax:

nsIChannel nsIProtocolHandler::newChannel(
	in nsIURI aURI)  

Parameters:

aURI: The URI.

Returns:

The channel.

allowPort

Allows a protocol to override blacklisted ports. This method will be called when there is an attempt to connect to a port that is blacklisted. For example, for most protocols, port 25 (Simple Mail Transfer) is banned. When a URI containing this "known-to-do-bad-things" port number is encountered, this function will be called to ask if the protocol handler wants to override the ban.

Syntax:

boolean nsIProtocolHandler::allowPort(in long port,
	in string scheme)  

Parameters:

port: The port number.

scheme: The protocol in question.

Returns:

TRUE if the protocol can override the blacklisted port.

FALSE otherwise.

Attributes and Constants

readonly attribute ACString nsIProtocolHandler::scheme

Gets the scheme of this protocol (e.g., "file").

readonly attribute long nsIProtocolHandler::defaultPort

Gets the default port, ie, the port that this protocol normally uses. If a port does not make sense for the protocol (e.g., "about:") then -1 will be returned.

readonly attribute unsigned long nsIProtocolHandler::protocolFlags

Gets the protocol specific flags (see flag definitions below).

const unsigned long nsIProtocolHandler::URI_STD=0

Protocol specific flag. This indicates a standard full URI with authority component and concept of relative URIs (http, ftp, ...). It is the default mask; the others are deviations.

Note: Implementations must ignore any flags they do not understand.

const unsigned long nsIProtocolHandler::URI_NORELATIVE=(1<<0)

Protocol specific flag. This indicates a protocol handler with no concept of relative URIs (about, javascript, finger, ...).

const unsigned long nsIProtocolHandler::URI_NOAUTH=(1<<1)

Protocol specific flag. This indicates a protocol handler with no authority component (file, ...).

const unsigned long nsIProtocolHandler::ALLOWS_PROXY=(1<<2)

Protocol specific flag. This indicates a protocol handler that can be proxied via a proxy (socks or http) (e.g., irc, smtp, http, etc.). If the protocol supports transparent proxying, the handler should implement nsIProxiedProtocolHandler. If it supports only HTTP proxying, then it need not support nsIProxiedProtocolHandler, but should instead set the ALLOWS_PROXY_HTTP flag (see below).

See also: nsIProxiedProtocolHandler

const unsigned long nsIProtocolHandler::ALLOWS_PROXY_HTTP=(1<<3)

This protocol handler can be proxied using a http proxy (e.g., http, ftp, etc.). 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.

• Site Map
• Security Updates
• Contact Us
• Donate

Portions of this content are © 1998–2009 by individual mozilla.org contributors; content available under a Creative Commons license | Details.

Last modified May 7, 2003 Document History