You are currently viewing a snapshot of www.mozilla.org taken on April 21, 2008. Most of this content is highly out of date (some pages haven't been updated since the project began in 1998) and exists for historical purposes only. If there are any pages on this archive site that you think should be added back to www.mozilla.org, please file a bug.


TOC PREV NEXT INDEX

Embedding Gecko API


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.


Written by:Ellen Evans | Comments, questions, complaints? Bug 143387
TOC PREV NEXT INDEX