/* -*- 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.0 (the "NPL"); you may not use this file except in
 * compliance with the NPL.  You may obtain a copy of the NPL at
 * http://www.mozilla.org/NPL/
 *
 * Software distributed under the NPL is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the NPL
 * for the specific language governing rights and limitations under the
 * NPL.
 *
 * The Initial Developer of this code under the NPL is Netscape
 * Communications Corporation.  Portions created by Netscape are
 * Copyright (C) 1998 Netscape Communications Corporation.  All Rights
 * Reserved.
 */

#include "nsIRequest.idl"

interface nsIURI;
interface nsIInputStream;
interface nsIOutputStream;
interface nsIStreamObserver;
interface nsIStreamListener;
interface nsILoadGroup;

typedef unsigned long nsLoadFlags;

/**
 * nsIChannel is the abstract base class for transports and URLs.
 * It's abstract in that it doesn't provide a means to specify the
 * location/destination of the data being accessed. 
 */
[scriptable, uuid(89f4afe0-1868-11d3-9337-00104ba0fd40)]
interface nsIChannel : nsIRequest
{
    /**
     * Returns the URL to which the channel refers.
     */
    readonly attribute nsIURI URI;

    /**
     * Opens a blocking input stream to the URL's specified source.
     * @param startPosition - The offset from the start of the data
     *   from which to read.
     * @param readCount - The number of bytes to read. If -1, everything
     *   up to the end of the data is read. If greater than the end of 
     *   the data, the amount available is returned in the stream.
     */
    nsIInputStream openInputStream(in unsigned long startPosition,
                                   in long readCount);

    /**
     * Opens a blocking output stream to the URL's specified destination.
     * @param startPosition - The offset from the start of the data
     *   from which to begin writing.
     */
    nsIOutputStream openOutputStream(in unsigned long startPosition);

    /**
     * Opens the channel asynchronously. The nsIStreamObserver's OnStartRequest
     * method is called back when the channel actually becomes open, providing 
     * the content type. Its OnStopRequest method is called when the channel
     * becomes closed.
     */
    void asyncOpen(in nsIStreamObserver observer, 
                   in nsISupports ctxt);

    /**
     * Reads asynchronously from the URL's specified source. Notifications
     * are provided to the stream listener on the thread of the specified
     * event queue.
     * The startPosition argument designates the offset in the source where
     * the data will be read.
     * If the readCount == -1 then all the available data is delivered to
     * the stream listener.
     */
    void asyncRead(in unsigned long startPosition,
                   in long readCount,
                   in nsISupports ctxt,
                   in nsIStreamListener listener);

    /**
     * Writes asynchronously to the URL's specified destination. Notifications
     * are provided to the stream observer on the thread of the specified
     * event queue.
     * The startPosition argument designates the offset in the destination where
     * the data will be written.
     * If the writeCount == -1, then all the available data in the input
     * stream is written.
     */
    void asyncWrite(in nsIInputStream fromStream,
                    in unsigned long startPosition,
                    in long writeCount,
                    in nsISupports ctxt,
                    in nsIStreamObserver observer);

    /**
     * Load attribute flags. These may be or'd together.
     *
     * Note that more will follow for each protocol's implementation of a channel, 
     * although channel writers have to be careful to not let the flag bits 
     * overlap. Otherwise, users won't be able to create a single flag word
     * of load attributes that applies to a number of different channel types.
     */
    const unsigned long LOAD_NORMAL     = 0;      /* no special load attributes -- use defaults */
    const unsigned long LOAD_BACKGROUND = 1 << 0; /* don't deliver status notifications to the
                                                   * nsIProgressEventSink, or keep this load from
                                                   * completing the nsILoadGroup it may belong to */

    /**
     * Accesses the load attributes for the channel. E.g. setting the load 
     * attributes with the LOAD_QUIET bit set causes the loading process to
     * not deliver status notifications to the program performing the load,
     * and to not contribute to keeping any nsILoadGroup it may be contained
     * in from firing its OnLoadComplete notification.
     */
    attribute nsLoadFlags loadAttributes;

    /**
     * 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. 
     */
    readonly attribute string contentType;

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

    /**
     * Accesses the owner corresponding to the entity that is 
     * responsible for this channel. Used by security code to grant
     * or diminish privileges to mobile code loaded from this channel. 
     */
    attribute nsISupports owner;

    /**
     * Returns the load group in which the channel is a currently a member.
     */
    readonly attribute nsILoadGroup loadGroup;

};