gecko-dev/netwerk/base/public/nsIChannel.idl

/* -*- Mode: C++; tab-width: 4; 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 "nsIRequest.idl"

interface nsIURI;
interface nsIInterfaceRequestor;
interface nsIInputStream;
interface nsIStreamListener;

/**
 * The nsIChannel interface allows the user to construct GET requests for
 * specific protocols, and manage them in a uniform way. Once a channel
 * is created (via nsIIOService::NewChannel), parameters for that request
 * may be set by using the channel attributes, or by QI'ing to a subclass
 * of nsIChannel for protocol-specific parameters. Then the actual request
 * can be issued via Open or AsyncOpen.
 *
 * After a request has been completed, the channel is still valid for
 * accessing protocol-specific results. For example, QI'ing to nsIHTTPChannel
 * allows response headers to be retrieved for the http transaction. 
 */
[scriptable, uuid(1788e79e-f947-11d3-8cda-0060b0fc14a3)]
interface nsIChannel : nsIRequest
{
    /**
     * Returns the original URL used to construct the channel.
     * This is used in the case of a redirect or URI "resolution" (e.g. 
     * resolving a resource: URI to a file: URI) so that the original
     * pre-redirect URI can still be obtained. 
     *
     * Note that this is distinctly different from the http referrer
     * (referring URI) which is typically the page that contained the 
     * original URI (accessible from nsIHTTPChannel).
     */
    attribute nsIURI originalURI;

    /**
     * Returns the URL to which the channel currently refers. If a redirect
     * or URI resolution occurs, this accessor returns the current location
     * to which the channel is referring.
     */
    readonly attribute nsIURI URI;

    /**
     * Accesses the owner corresponding to the entity that is 
     * responsible for this channel. Used by security code to grant
     * or deny privileges to mobile code loaded from this channel. 
     *
     * Note: This is a strong reference to the owner, so if the owner is also
     * holding a pointer to the channel, care must be taken to explicitly drop
     * its reference to the channel -- otherwise a leak will result.
     */
    attribute nsISupports owner;

    /**
     * Accesses the capabilities callbacks of the channel. This is set by clients
     * who wish to provide a means to receive progress, status and protocol-specific 
     * notifications.  Interfaces commonly requested include: nsIProgressEventSink
     * and nsIPrompt.
     */
    attribute nsIInterfaceRequestor notificationCallbacks;

    /**
     * Any security information about this channel.  This can be null.
     */
    readonly attribute nsISupports securityInfo;

    /**
     * Returns the content MIME type of the channel if available. Note that the 
     * content type can often be wrongly specified (wrong file extension, wrong
     * MIME type, wrong document type stored on a server, etc.) and the caller
     * most likely wants to verify with the actual data. 
     */
    attribute string contentType;

    /**
     * Returns the length of the data associated with the channel if available.
     * If the length is unknown then -1 is returned.
     */
    attribute long contentLength;

    /**
     * Synchronously open this channel.  Returns a blocking input stream to this
     * channel's data.
     */
    nsIInputStream open();

    /**
     * Asynchronously open this channel.  Data is fed to the specified stream
     * listener as it becomes available.
     */
    void asyncOpen(in nsIStreamListener listener, in nsISupports ctxt);

    /**************************************************************************
     * Channel specific load flags:
     */

    /**
     * Used exclusively by the uriloader and docshell to indicate whether or
     * not this request corresponds to the toplevel document.
     */
    const unsigned long LOAD_DOCUMENT_URI = 1 << 16;

    /** 
     * If the end consumer for this load has been retargeted after discovering 
     * it's content, this flag will be set:
     */
    const unsigned long LOAD_RETARGETED_DOCUMENT_URI = 1 << 17;

	/**
	 * This flag is set to indicate that onStopRequest may be followed by
     * another onStartRequest/onStopRequest pair.  This flag is, for example,
     * used by the multipart/replace stream converter.
	 */
	const unsigned long LOAD_REPLACE = 1 << 18;

    /**************************************************************************
     * This flag is OBSOLETE and will be removed once the old cache is
     * removed from the code base.  Support for CACHE_AS_FILE is now provided
     * via nsICachingChannel.
     */
    const unsigned long CACHE_AS_FILE = 1 << 19;


%{C++
// There is no content available (when asyncOpen is called)
#define NS_ERROR_NO_CONTENT NS_ERROR_GENERATE_FAILURE(NS_ERROR_MODULE_NETWORK, 17)
%}
};