The Tor Browser / file revision

 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */

 /* This Source Code Form is subject to the terms of the Mozilla Public

  * License, v. 2.0. If a copy of the MPL was not distributed with this

  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

 #include "nsIRequest.idl"

 interface nsIURI;

 interface nsIInterfaceRequestor;

 interface nsIInputStream;

 interface nsIStreamListener;

 /**

  * The nsIChannel interface allows clients 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 URI can be fetched

  * by calling nsIChannel::open or nsIChannel::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 corresponding http transaction.

  *

  * This interface must be used only from the XPCOM main thread.

  */

 [scriptable, uuid(2a8a7237-c1e2-4de7-b669-2002af29e42d)]

 interface nsIChannel : nsIRequest

 {

     /**

      * The original URI 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.  This is never null.  Attempts to

      * set it to null must throw.

      *

      * NOTE: this is distinctly different from the http Referer (referring URI),

      * which is typically the page that contained the original URI (accessible

      * from nsIHttpChannel).

      */

     attribute nsIURI originalURI;

     /**

      * The URI corresponding to the channel.  Its value is immutable.

      */

     readonly attribute nsIURI URI;

     /**

      * The owner, corresponding to the entity that is responsible for this

      * channel.  Used by the security manager 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 strong reference to the channel, care must be taken to 

      * explicitly drop its reference to the channel.

      */

     attribute nsISupports owner;

     /**

      * The notification callbacks for the channel.  This is set by clients, who

      * wish to provide a means to receive progress, status and protocol-specific 

      * notifications.  If this value is NULL, the channel implementation may use

      * the notification callbacks from its load group.  The channel may also

      * query the notification callbacks from its load group if its notification

      * callbacks do not supply the requested interface.

      * 

      * Interfaces commonly requested include: nsIProgressEventSink, nsIPrompt,

      * and nsIAuthPrompt/nsIAuthPrompt2.

      *

      * When the channel is done, it must not continue holding references to

      * this object.

      *

      * NOTE: A channel implementation should take care when "caching" an

      * interface pointer queried from its notification callbacks.  If the

      * notification callbacks are changed, then a cached interface pointer may

      * become invalid and may therefore need to be re-queried.

      */

     attribute nsIInterfaceRequestor notificationCallbacks;

     /**

      * Transport-level security information (if any) corresponding to the channel.

      */

     readonly attribute nsISupports securityInfo;

     /**

      * The MIME type of the channel's content if available. 

      * 

      * NOTE: the content type can often be wrongly specified (e.g., 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.

      *

      * Setting contentType before the channel has been opened provides a hint

      * to the channel as to what the MIME type is.  The channel may ignore this

      * hint in deciding on the actual MIME type that it will report.

      *

      * Setting contentType after onStartRequest has been fired or after open()

      * is called will override the type determined by the channel.

      *

      * Setting contentType between the time that asyncOpen() is called and the

      * time when onStartRequest is fired has undefined behavior at this time.

      *

      * The value of the contentType attribute is a lowercase string.  A value

      * assigned to this attribute will be parsed and normalized as follows:

      *  1- any parameters (delimited with a ';') will be stripped.

      *  2- if a charset parameter is given, then its value will replace the

      *     the contentCharset attribute of the channel.

      *  3- the stripped contentType will be lowercased.

      * Any implementation of nsIChannel must follow these rules.

      */

     attribute ACString contentType;

     /**

      * The character set of the channel's content if available and if applicable.

      * This attribute only applies to textual data.

      *

      * The value of the contentCharset attribute is a mixedcase string.

      */

     attribute ACString contentCharset;

     /**

      * The length of the data associated with the channel if available.  A value

      * of -1 indicates that the content length is unknown. Note that this is a

      * 64-bit value and obsoletes the "content-length" property used on some

      * channels.

      */

     attribute int64_t contentLength;

     /**

      * Synchronously open the channel.

      *

      * @return blocking input stream to the channel's data.

      *

      * NOTE: nsIChannel implementations are not required to implement this

      * method.  Moreover, since this method may block the calling thread, it

      * should not be called on a thread that processes UI events.  Like any

      * other nsIChannel method it must not be called on any thread other

      * than the XPCOM main thread.

      *

      * NOTE: Implementations should throw NS_ERROR_IN_PROGRESS if the channel

      * is reopened.

      */

     nsIInputStream open();

     /**

      * Asynchronously open this channel.  Data is fed to the specified stream

      * listener as it becomes available.  The stream listener's methods are

      * called on the thread that calls asyncOpen and are not called until

      * after asyncOpen returns.  If asyncOpen returns successfully, the

      * channel promises to call at least onStartRequest and onStopRequest.

      *

      * If the nsIRequest object passed to the stream listener's methods is not

      * this channel, an appropriate onChannelRedirect notification needs to be

      * sent to the notification callbacks before onStartRequest is called.

      * Once onStartRequest is called, all following method calls on aListener

      * will get the request that was passed to onStartRequest.

      *

      * If the channel's and loadgroup's notification callbacks do not provide

      * an nsIChannelEventSink when onChannelRedirect would be called, that's

      * equivalent to having called onChannelRedirect.

      *

      * If asyncOpen returns successfully, the channel is responsible for

      * keeping itself alive until it has called onStopRequest on aListener or

      * called onChannelRedirect.

      *

      * Implementations are allowed to synchronously add themselves to the

      * associated load group (if any).

      *

      * NOTE: Implementations should throw NS_ERROR_ALREADY_OPENED if the

      * channel is reopened.

      *

      * @param aListener the nsIStreamListener implementation

      * @param aContext an opaque parameter forwarded to aListener's methods

      * @see nsIChannelEventSink for onChannelRedirect

      */

     void asyncOpen(in nsIStreamListener aListener, in nsISupports aContext);

     /**************************************************************************

      * Channel specific load flags:

      *

      * Bits 23-31 are reserved for future use by this interface or one of its

      * derivatives (e.g., see nsICachingChannel).

      */

     /**

      * Set (e.g., by the docshell) to indicate whether or not the channel

      * corresponds to a document URI.

      */

     const unsigned long LOAD_DOCUMENT_URI = 1 << 16;

     /** 

      * If the end consumer for this load has been retargeted after discovering 

      * its content, this flag will be set:

      */

     const unsigned long LOAD_RETARGETED_DOCUMENT_URI = 1 << 17;

     /**

      * This flag is set to indicate that this channel is replacing another

      * channel.  This means that:

      *

      * 1) the stream listener this channel will be notifying was initially

      *    passed to the asyncOpen method of some other channel

      *

      *   and

      *

      * 2) this channel's URI is a better identifier of the resource being

      *    accessed than this channel's originalURI.

      *

      * This flag can be set, for example, for redirects or for cases when a

      * single channel has multiple parts to it (and thus can follow

      * onStopRequest with another onStartRequest/onStopRequest pair, each pair

      * for a different request).

      */

     const unsigned long LOAD_REPLACE = 1 << 18;

     /**

      * Set (e.g., by the docshell) to indicate whether or not the channel

      * corresponds to an initial document URI load (e.g., link click).

      */

     const unsigned long LOAD_INITIAL_DOCUMENT_URI = 1 << 19;

     /**

      * Set (e.g., by the URILoader) to indicate whether or not the end consumer

      * for this load has been determined.

      */

     const unsigned long LOAD_TARGETED = 1 << 20;

     /**

      * If this flag is set, the channel should call the content sniffers as

      * described in nsNetCID.h about NS_CONTENT_SNIFFER_CATEGORY.

      *

      * Note: Channels may ignore this flag; however, new channel implementations

      * should only do so with good reason.

      */

     const unsigned long LOAD_CALL_CONTENT_SNIFFERS = 1 << 21;

     /**

      * This flag tells the channel to use URI classifier service to check

      * the URI when opening the channel.

      */

     const unsigned long LOAD_CLASSIFY_URI = 1 << 22;

     /**

      * If this flag is set and a server's response is Content-Type

      * application/octet-steam, the server's Content-Type will be ignored and

      * the channel content will be sniffed as though no Content-Type had been

      * passed.

      */

     const unsigned long LOAD_TREAT_APPLICATION_OCTET_STREAM_AS_UNKNOWN = 1 << 23;

     /**

      * Set to let explicitely provided credentials be used over credentials

      * we have cached previously. In some situations like form login using HTTP

      * auth via XMLHttpRequest we need to let consumers override the cached

      * credentials explicitely. For form login 403 response instead of 401 is

      * usually used to prevent an auth dialog. But any code other then 401/7

      * will leave original credentials in the cache and there is then no way

      * to override them for the same user name.

      */

     const unsigned long LOAD_EXPLICIT_CREDENTIALS = 1 << 24;

     /**

      * Access to the type implied or stated by the Content-Disposition header

      * if available and if applicable. This allows determining inline versus

      * attachment.

      *

      * Setting contentDisposition provides a hint to the channel about the

      * disposition.  If a normal Content-Disposition header is present its

      * value will always be used.  If it is missing the hinted value will

      * be used if set.

      *

      * Implementations should throw NS_ERROR_NOT_AVAILABLE if the header either

      * doesn't exist for this type of channel or is empty, and return

      * DISPOSITION_ATTACHMENT if an invalid/noncompliant value is present.

      */

     attribute unsigned long contentDisposition;

     const unsigned long DISPOSITION_INLINE = 0;

     const unsigned long DISPOSITION_ATTACHMENT = 1;

     /**

      * Access to the filename portion of the Content-Disposition header if

      * available and if applicable. This allows getting the preferred filename

      * without having to parse it out yourself.

      *

      * Setting contentDispositionFilename provides a hint to the channel about

      * the disposition.  If a normal Content-Disposition header is present its

      * value will always be used.  If it is missing the hinted value will be

      * used if set.

      *

      * Implementations should throw NS_ERROR_NOT_AVAILABLE if the header doesn't

      * exist for this type of channel, if the header is empty, if the header

      * doesn't contain a filename portion, or the value of the filename

      * attribute is empty/missing.

      */

     attribute AString contentDispositionFilename;

     /**

      * Access to the raw Content-Disposition header if available and applicable.

      *

      * Implementations should throw NS_ERROR_NOT_AVAILABLE if the header either

      * doesn't exist for this type of channel or is empty.

      *

      * @deprecated Use contentDisposition/contentDispositionFilename instead.

      */

     readonly attribute ACString contentDispositionHeader;

 };