/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 4 -*-
 *
 * The contents of this file are subject to the Netscape Public
 * License Version 1.1 (the "License"); you may not use this file
 * except in compliance with the License. You may obtain a copy of
 * the License at http://www.mozilla.org/NPL/
 *
 * Software distributed under the License is distributed on an "AS
 * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
 * implied. See the License for the specific language governing
 * rights and limitations under the License.
 *
 * The Original Code is mozilla.org code.
 *
 * The Initial Developer of the Original Code is Netscape
 * Communications Corporation.  Portions created by Netscape are
 * Copyright (C) 1998 Netscape Communications Corporation. All
 * Rights Reserved.
 *
 * Contributor(s): 
 */

#include "nsISupports.idl"
#include "nsIChannel.idl"

interface nsIURI;

[scriptable, uuid(15fd6940-8ea7-11d3-93ad-00104ba0fd40)]
interface nsIProtocolHandler : nsISupports
{
    readonly attribute string scheme;

	/** 
	 * Default Port will be the port that this protocol normally
	 * uses.  If a port does not make sense for the protocol (eg about://)
	 * -1 will be returned.
	 */

    readonly attribute long defaultPort;

    /**
     * Makes a URI object that is suitable for loading by this protocol.
     * In the usual case (when only the accessors provided by nsIURI are 
     * needed), this method just constructs a standard URI using the
     * component manager with kStandardURLCID.  aBaseURI may be nsnull.
     */
    nsIURI newURI(in string aSpec, in nsIURI aBaseURI);

    /**
     * Constructs a new channel for this protocol handler. 
     *
     * @param originalURI - Specifies the original URI which caused the creation
     * of this channel. This can occur when the construction of one channel
     * (e.g. for resource:) causes another channel to be created on its behalf
     * (e.g. a file: channel), or if a redirect occurs, causing the current
     * URL to become different from the original URL. If NULL, the aURI parameter
     * will be used as the originalURI instead.
     */
    nsIChannel newChannel(in nsIURI aURI);

    /**
     * Allows a protocol to override blacklisted ports.
     *
     * |allowPort| 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 url 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 band.  
     */
     
    boolean allowPort(in long port, in string scheme);
};

%{C++

#define NS_NETWORK_PROTOCOL_CONTRACTID               "@mozilla.org/network/protocol;1"
#define NS_NETWORK_PROTOCOL_CONTRACTID_PREFIX        NS_NETWORK_PROTOCOL_CONTRACTID "?name="
#define NS_NETWORK_PROTOCOL_CONTRACTID_PREFIX_LENGTH 37     // nsCRT::strlen(NS_NETWORK_PROTOCOL_CONTRACTID_PREFIX)

// Unknown Protocol Error
#define NS_ERROR_UNKNOWN_PROTOCOL  NS_ERROR_GENERATE_FAILURE(NS_ERROR_MODULE_NETWORK, 18)

%}
