michael@0: /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public michael@0: * License, v. 2.0. If a copy of the MPL was not distributed with this michael@0: * file, You can obtain one at http://mozilla.org/MPL/2.0/. */ michael@0: michael@0: #include "nsIRequest.idl" michael@0: michael@0: interface nsIURI; michael@0: interface nsIInterfaceRequestor; michael@0: interface nsIInputStream; michael@0: interface nsIStreamListener; michael@0: michael@0: /** michael@0: * The nsIChannel interface allows clients to construct "GET" requests for michael@0: * specific protocols, and manage them in a uniform way. Once a channel is michael@0: * created (via nsIIOService::newChannel), parameters for that request may michael@0: * be set by using the channel attributes, or by QI'ing to a subclass of michael@0: * nsIChannel for protocol-specific parameters. Then, the URI can be fetched michael@0: * by calling nsIChannel::open or nsIChannel::asyncOpen. michael@0: * michael@0: * After a request has been completed, the channel is still valid for accessing michael@0: * protocol-specific results. For example, QI'ing to nsIHttpChannel allows michael@0: * response headers to be retrieved for the corresponding http transaction. michael@0: * michael@0: * This interface must be used only from the XPCOM main thread. michael@0: */ michael@0: [scriptable, uuid(2a8a7237-c1e2-4de7-b669-2002af29e42d)] michael@0: interface nsIChannel : nsIRequest michael@0: { michael@0: /** michael@0: * The original URI used to construct the channel. This is used in michael@0: * the case of a redirect or URI "resolution" (e.g. resolving a michael@0: * resource: URI to a file: URI) so that the original pre-redirect michael@0: * URI can still be obtained. This is never null. Attempts to michael@0: * set it to null must throw. michael@0: * michael@0: * NOTE: this is distinctly different from the http Referer (referring URI), michael@0: * which is typically the page that contained the original URI (accessible michael@0: * from nsIHttpChannel). michael@0: */ michael@0: attribute nsIURI originalURI; michael@0: michael@0: /** michael@0: * The URI corresponding to the channel. Its value is immutable. michael@0: */ michael@0: readonly attribute nsIURI URI; michael@0: michael@0: /** michael@0: * The owner, corresponding to the entity that is responsible for this michael@0: * channel. Used by the security manager to grant or deny privileges to michael@0: * mobile code loaded from this channel. michael@0: * michael@0: * NOTE: this is a strong reference to the owner, so if the owner is also michael@0: * holding a strong reference to the channel, care must be taken to michael@0: * explicitly drop its reference to the channel. michael@0: */ michael@0: attribute nsISupports owner; michael@0: michael@0: /** michael@0: * The notification callbacks for the channel. This is set by clients, who michael@0: * wish to provide a means to receive progress, status and protocol-specific michael@0: * notifications. If this value is NULL, the channel implementation may use michael@0: * the notification callbacks from its load group. The channel may also michael@0: * query the notification callbacks from its load group if its notification michael@0: * callbacks do not supply the requested interface. michael@0: * michael@0: * Interfaces commonly requested include: nsIProgressEventSink, nsIPrompt, michael@0: * and nsIAuthPrompt/nsIAuthPrompt2. michael@0: * michael@0: * When the channel is done, it must not continue holding references to michael@0: * this object. michael@0: * michael@0: * NOTE: A channel implementation should take care when "caching" an michael@0: * interface pointer queried from its notification callbacks. If the michael@0: * notification callbacks are changed, then a cached interface pointer may michael@0: * become invalid and may therefore need to be re-queried. michael@0: */ michael@0: attribute nsIInterfaceRequestor notificationCallbacks; michael@0: michael@0: /** michael@0: * Transport-level security information (if any) corresponding to the channel. michael@0: */ michael@0: readonly attribute nsISupports securityInfo; michael@0: michael@0: /** michael@0: * The MIME type of the channel's content if available. michael@0: * michael@0: * NOTE: the content type can often be wrongly specified (e.g., wrong file michael@0: * extension, wrong MIME type, wrong document type stored on a server, etc.), michael@0: * and the caller most likely wants to verify with the actual data. michael@0: * michael@0: * Setting contentType before the channel has been opened provides a hint michael@0: * to the channel as to what the MIME type is. The channel may ignore this michael@0: * hint in deciding on the actual MIME type that it will report. michael@0: * michael@0: * Setting contentType after onStartRequest has been fired or after open() michael@0: * is called will override the type determined by the channel. michael@0: * michael@0: * Setting contentType between the time that asyncOpen() is called and the michael@0: * time when onStartRequest is fired has undefined behavior at this time. michael@0: * michael@0: * The value of the contentType attribute is a lowercase string. A value michael@0: * assigned to this attribute will be parsed and normalized as follows: michael@0: * 1- any parameters (delimited with a ';') will be stripped. michael@0: * 2- if a charset parameter is given, then its value will replace the michael@0: * the contentCharset attribute of the channel. michael@0: * 3- the stripped contentType will be lowercased. michael@0: * Any implementation of nsIChannel must follow these rules. michael@0: */ michael@0: attribute ACString contentType; michael@0: michael@0: /** michael@0: * The character set of the channel's content if available and if applicable. michael@0: * This attribute only applies to textual data. michael@0: * michael@0: * The value of the contentCharset attribute is a mixedcase string. michael@0: */ michael@0: attribute ACString contentCharset; michael@0: michael@0: /** michael@0: * The length of the data associated with the channel if available. A value michael@0: * of -1 indicates that the content length is unknown. Note that this is a michael@0: * 64-bit value and obsoletes the "content-length" property used on some michael@0: * channels. michael@0: */ michael@0: attribute int64_t contentLength; michael@0: michael@0: /** michael@0: * Synchronously open the channel. michael@0: * michael@0: * @return blocking input stream to the channel's data. michael@0: * michael@0: * NOTE: nsIChannel implementations are not required to implement this michael@0: * method. Moreover, since this method may block the calling thread, it michael@0: * should not be called on a thread that processes UI events. Like any michael@0: * other nsIChannel method it must not be called on any thread other michael@0: * than the XPCOM main thread. michael@0: * michael@0: * NOTE: Implementations should throw NS_ERROR_IN_PROGRESS if the channel michael@0: * is reopened. michael@0: */ michael@0: nsIInputStream open(); michael@0: michael@0: /** michael@0: * Asynchronously open this channel. Data is fed to the specified stream michael@0: * listener as it becomes available. The stream listener's methods are michael@0: * called on the thread that calls asyncOpen and are not called until michael@0: * after asyncOpen returns. If asyncOpen returns successfully, the michael@0: * channel promises to call at least onStartRequest and onStopRequest. michael@0: * michael@0: * If the nsIRequest object passed to the stream listener's methods is not michael@0: * this channel, an appropriate onChannelRedirect notification needs to be michael@0: * sent to the notification callbacks before onStartRequest is called. michael@0: * Once onStartRequest is called, all following method calls on aListener michael@0: * will get the request that was passed to onStartRequest. michael@0: * michael@0: * If the channel's and loadgroup's notification callbacks do not provide michael@0: * an nsIChannelEventSink when onChannelRedirect would be called, that's michael@0: * equivalent to having called onChannelRedirect. michael@0: * michael@0: * If asyncOpen returns successfully, the channel is responsible for michael@0: * keeping itself alive until it has called onStopRequest on aListener or michael@0: * called onChannelRedirect. michael@0: * michael@0: * Implementations are allowed to synchronously add themselves to the michael@0: * associated load group (if any). michael@0: * michael@0: * NOTE: Implementations should throw NS_ERROR_ALREADY_OPENED if the michael@0: * channel is reopened. michael@0: * michael@0: * @param aListener the nsIStreamListener implementation michael@0: * @param aContext an opaque parameter forwarded to aListener's methods michael@0: * @see nsIChannelEventSink for onChannelRedirect michael@0: */ michael@0: void asyncOpen(in nsIStreamListener aListener, in nsISupports aContext); michael@0: michael@0: /************************************************************************** michael@0: * Channel specific load flags: michael@0: * michael@0: * Bits 23-31 are reserved for future use by this interface or one of its michael@0: * derivatives (e.g., see nsICachingChannel). michael@0: */ michael@0: michael@0: /** michael@0: * Set (e.g., by the docshell) to indicate whether or not the channel michael@0: * corresponds to a document URI. michael@0: */ michael@0: const unsigned long LOAD_DOCUMENT_URI = 1 << 16; michael@0: michael@0: /** michael@0: * If the end consumer for this load has been retargeted after discovering michael@0: * its content, this flag will be set: michael@0: */ michael@0: const unsigned long LOAD_RETARGETED_DOCUMENT_URI = 1 << 17; michael@0: michael@0: /** michael@0: * This flag is set to indicate that this channel is replacing another michael@0: * channel. This means that: michael@0: * michael@0: * 1) the stream listener this channel will be notifying was initially michael@0: * passed to the asyncOpen method of some other channel michael@0: * michael@0: * and michael@0: * michael@0: * 2) this channel's URI is a better identifier of the resource being michael@0: * accessed than this channel's originalURI. michael@0: * michael@0: * This flag can be set, for example, for redirects or for cases when a michael@0: * single channel has multiple parts to it (and thus can follow michael@0: * onStopRequest with another onStartRequest/onStopRequest pair, each pair michael@0: * for a different request). michael@0: */ michael@0: const unsigned long LOAD_REPLACE = 1 << 18; michael@0: michael@0: /** michael@0: * Set (e.g., by the docshell) to indicate whether or not the channel michael@0: * corresponds to an initial document URI load (e.g., link click). michael@0: */ michael@0: const unsigned long LOAD_INITIAL_DOCUMENT_URI = 1 << 19; michael@0: michael@0: /** michael@0: * Set (e.g., by the URILoader) to indicate whether or not the end consumer michael@0: * for this load has been determined. michael@0: */ michael@0: const unsigned long LOAD_TARGETED = 1 << 20; michael@0: michael@0: /** michael@0: * If this flag is set, the channel should call the content sniffers as michael@0: * described in nsNetCID.h about NS_CONTENT_SNIFFER_CATEGORY. michael@0: * michael@0: * Note: Channels may ignore this flag; however, new channel implementations michael@0: * should only do so with good reason. michael@0: */ michael@0: const unsigned long LOAD_CALL_CONTENT_SNIFFERS = 1 << 21; michael@0: michael@0: /** michael@0: * This flag tells the channel to use URI classifier service to check michael@0: * the URI when opening the channel. michael@0: */ michael@0: const unsigned long LOAD_CLASSIFY_URI = 1 << 22; michael@0: michael@0: /** michael@0: * If this flag is set and a server's response is Content-Type michael@0: * application/octet-steam, the server's Content-Type will be ignored and michael@0: * the channel content will be sniffed as though no Content-Type had been michael@0: * passed. michael@0: */ michael@0: const unsigned long LOAD_TREAT_APPLICATION_OCTET_STREAM_AS_UNKNOWN = 1 << 23; michael@0: michael@0: /** michael@0: * Set to let explicitely provided credentials be used over credentials michael@0: * we have cached previously. In some situations like form login using HTTP michael@0: * auth via XMLHttpRequest we need to let consumers override the cached michael@0: * credentials explicitely. For form login 403 response instead of 401 is michael@0: * usually used to prevent an auth dialog. But any code other then 401/7 michael@0: * will leave original credentials in the cache and there is then no way michael@0: * to override them for the same user name. michael@0: */ michael@0: const unsigned long LOAD_EXPLICIT_CREDENTIALS = 1 << 24; michael@0: michael@0: /** michael@0: * Access to the type implied or stated by the Content-Disposition header michael@0: * if available and if applicable. This allows determining inline versus michael@0: * attachment. michael@0: * michael@0: * Setting contentDisposition provides a hint to the channel about the michael@0: * disposition. If a normal Content-Disposition header is present its michael@0: * value will always be used. If it is missing the hinted value will michael@0: * be used if set. michael@0: * michael@0: * Implementations should throw NS_ERROR_NOT_AVAILABLE if the header either michael@0: * doesn't exist for this type of channel or is empty, and return michael@0: * DISPOSITION_ATTACHMENT if an invalid/noncompliant value is present. michael@0: */ michael@0: attribute unsigned long contentDisposition; michael@0: const unsigned long DISPOSITION_INLINE = 0; michael@0: const unsigned long DISPOSITION_ATTACHMENT = 1; michael@0: michael@0: /** michael@0: * Access to the filename portion of the Content-Disposition header if michael@0: * available and if applicable. This allows getting the preferred filename michael@0: * without having to parse it out yourself. michael@0: * michael@0: * Setting contentDispositionFilename provides a hint to the channel about michael@0: * the disposition. If a normal Content-Disposition header is present its michael@0: * value will always be used. If it is missing the hinted value will be michael@0: * used if set. michael@0: * michael@0: * Implementations should throw NS_ERROR_NOT_AVAILABLE if the header doesn't michael@0: * exist for this type of channel, if the header is empty, if the header michael@0: * doesn't contain a filename portion, or the value of the filename michael@0: * attribute is empty/missing. michael@0: */ michael@0: attribute AString contentDispositionFilename; michael@0: michael@0: /** michael@0: * Access to the raw Content-Disposition header if available and applicable. michael@0: * michael@0: * Implementations should throw NS_ERROR_NOT_AVAILABLE if the header either michael@0: * doesn't exist for this type of channel or is empty. michael@0: * michael@0: * @deprecated Use contentDisposition/contentDispositionFilename instead. michael@0: */ michael@0: readonly attribute ACString contentDispositionHeader; michael@0: };