/gecko_sdk/idl/nsIChannel.idl

  1/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
  2/* ***** BEGIN LICENSE BLOCK *****
  3 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  4 *
  5 * The contents of this file are subject to the Mozilla Public License Version
  6 * 1.1 (the "License"); you may not use this file except in compliance with
  7 * the License. You may obtain a copy of the License at
  8 * http://www.mozilla.org/MPL/
  9 *
 10 * Software distributed under the License is distributed on an "AS IS" basis,
 11 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 12 * for the specific language governing rights and limitations under the
 13 * License.
 14 *
 15 * The Original Code is mozilla.org code.
 16 *
 17 * The Initial Developer of the Original Code is
 18 * Netscape Communications Corporation.
 19 * Portions created by the Initial Developer are Copyright (C) 1998
 20 * the Initial Developer. All Rights Reserved.
 21 *
 22 * Contributor(s):
 23 *
 24 * Alternatively, the contents of this file may be used under the terms of
 25 * either the GNU General Public License Version 2 or later (the "GPL"), or
 26 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
 27 * in which case the provisions of the GPL or the LGPL are applicable instead
 28 * of those above. If you wish to allow use of your version of this file only
 29 * under the terms of either the GPL or the LGPL, and not to allow others to
 30 * use your version of this file under the terms of the MPL, indicate your
 31 * decision by deleting the provisions above and replace them with the notice
 32 * and other provisions required by the GPL or the LGPL. If you do not delete
 33 * the provisions above, a recipient may use your version of this file under
 34 * the terms of any one of the MPL, the GPL or the LGPL.
 35 *
 36 * ***** END LICENSE BLOCK ***** */
 37
 38#include "nsIRequest.idl"
 39
 40interface nsIURI;
 41interface nsIInterfaceRequestor;
 42interface nsIInputStream;
 43interface nsIStreamListener;
 44
 45/**
 46 * The nsIChannel interface allows clients to construct "GET" requests for
 47 * specific protocols, and manage them in a uniform way.  Once a channel is
 48 * created (via nsIIOService::newChannel), parameters for that request may
 49 * be set by using the channel attributes, or by QI'ing to a subclass of
 50 * nsIChannel for protocol-specific parameters.  Then, the URI can be fetched
 51 * by calling nsIChannel::open or nsIChannel::asyncOpen.
 52 *
 53 * After a request has been completed, the channel is still valid for accessing
 54 * protocol-specific results.  For example, QI'ing to nsIHttpChannel allows
 55 * response headers to be retrieved for the corresponding http transaction. 
 56 *
 57 * @status FROZEN
 58 */
 59[scriptable, uuid(c63a055a-a676-4e71-bf3c-6cfa11082018)]
 60interface nsIChannel : nsIRequest
 61{
 62    /**
 63     * The original URI used to construct the channel. This is used in the case
 64     * of a redirect or URI "resolution" (e.g. resolving a resource: URI to a
 65     * file: URI) so that the original pre-redirect URI can still be obtained. 
 66     *
 67     * NOTE: this is distinctly different from the http Referer (referring URI),
 68     * which is typically the page that contained the original URI (accessible
 69     * from nsIHttpChannel).
 70     */
 71    attribute nsIURI originalURI;
 72
 73    /**
 74     * The URI corresponding to the channel.  Its value is immutable.
 75     */
 76    readonly attribute nsIURI URI;
 77
 78    /**
 79     * The owner, corresponding to the entity that is responsible for this
 80     * channel.  Used by the security manager to grant or deny privileges to
 81     * mobile code loaded from this channel.
 82     *
 83     * NOTE: this is a strong reference to the owner, so if the owner is also
 84     * holding a strong reference to the channel, care must be taken to 
 85     * explicitly drop its reference to the channel.
 86     */
 87    attribute nsISupports owner;
 88
 89    /**
 90     * The notification callbacks for the channel.  This is set by clients, who
 91     * wish to provide a means to receive progress, status and protocol-specific 
 92     * notifications.  If this value is NULL, the channel implementation may use
 93     * the notification callbacks from its load group.  The channel may also
 94     * query the notification callbacks from its load group if its notification
 95     * callbacks do not supply the requested interface.
 96     * 
 97     * Interfaces commonly requested include: nsIProgressEventSink, nsIPrompt,
 98     * and nsIAuthPrompt/nsIAuthPrompt2.
 99     *
100     * When the channel is done, it must not continue holding references to
101     * this object.
102     *
103     * NOTE: A channel implementation should take care when "caching" an
104     * interface pointer queried from its notification callbacks.  If the
105     * notification callbacks are changed, then a cached interface pointer may
106     * become invalid and may therefore need to be re-queried.
107     */
108    attribute nsIInterfaceRequestor notificationCallbacks;
109
110    /**
111     * Transport-level security information (if any) corresponding to the channel.
112     */
113    readonly attribute nsISupports securityInfo;
114
115    /**
116     * The MIME type of the channel's content if available. 
117     * 
118     * NOTE: the content type can often be wrongly specified (e.g., wrong file
119     * extension, wrong MIME type, wrong document type stored on a server, etc.),
120     * and the caller most likely wants to verify with the actual data.
121     *
122     * Setting contentType before the channel has been opened provides a hint
123     * to the channel as to what the MIME type is.  The channel may ignore this
124     * hint in deciding on the actual MIME type that it will report.
125     *
126     * Setting contentType after onStartRequest has been fired or after open()
127     * is called will override the type determined by the channel.
128     *
129     * Setting contentType between the time that asyncOpen() is called and the
130     * time when onStartRequest is fired has undefined behavior at this time.
131     *
132     * The value of the contentType attribute is a lowercase string.  A value
133     * assigned to this attribute will be parsed and normalized as follows:
134     *  1- any parameters (delimited with a ';') will be stripped.
135     *  2- if a charset parameter is given, then its value will replace the
136     *     the contentCharset attribute of the channel.
137     *  3- the stripped contentType will be lowercased.
138     * Any implementation of nsIChannel must follow these rules.
139     */
140    attribute ACString contentType;
141
142    /**
143     * The character set of the channel's content if available and if applicable.
144     * This attribute only applies to textual data.
145     *
146     * The value of the contentCharset attribute is a mixedcase string.
147     */
148    attribute ACString contentCharset;
149
150    /**
151     * The length of the data associated with the channel if available.  A value
152     * of -1 indicates that the content length is unknown.
153     *
154     * Callers should prefer getting the "content-length" property
155     * as 64-bit value by QIing the channel to nsIPropertyBag2,
156     * if that interface is exposed by the channel.
157     */
158    attribute long contentLength;
159
160    /**
161     * Synchronously open the channel.
162     *
163     * @return blocking input stream to the channel's data.
164     *
165     * NOTE: nsIChannel implementations are not required to implement this
166     * method.  Moreover, since this method may block the calling thread, it
167     * should not be called on a thread that processes UI events.
168     *
169     * NOTE: Implementations should throw NS_ERROR_IN_PROGRESS if the channel
170     * is reopened.
171     */
172    nsIInputStream open();
173
174    /**
175     * Asynchronously open this channel.  Data is fed to the specified stream
176     * listener as it becomes available.  The stream listener's methods are
177     * called on the thread that calls asyncOpen and are not called until
178     * after asyncOpen returns.  If asyncOpen returns successfully, the
179     * channel promises to call at least onStartRequest and onStopRequest.
180     *
181     * If the nsIRequest object passed to the stream listener's methods is not
182     * this channel, an appropriate onChannelRedirect notification needs to be
183     * sent to the notification callbacks before onStartRequest is called.
184     * Once onStartRequest is called, all following method calls on aListener
185     * will get the request that was passed to onStartRequest.
186     *
187     * If the channel's and loadgroup's notification callbacks do not provide
188     * an nsIChannelEventSink when onChannelRedirect would be called, that's
189     * equivalent to having called onChannelRedirect.
190     *
191     * If asyncOpen returns successfully, the channel is responsible for
192     * keeping itself alive until it has called onStopRequest on aListener or
193     * called onChannelRedirect.
194     *
195     * Implementations are allowed to synchronously add themselves to the
196     * associated load group (if any).
197     *
198     * NOTE: Implementations should throw NS_ERROR_ALREADY_OPENED if the
199     * channel is reopened.
200     *
201     * @param aListener the nsIStreamListener implementation
202     * @param aContext an opaque parameter forwarded to aListener's methods
203     * @see nsIChannelEventSink for onChannelRedirect
204     */
205    void asyncOpen(in nsIStreamListener aListener, in nsISupports aContext);
206
207    /**************************************************************************
208     * Channel specific load flags:
209     *
210     * Bits 22-31 are reserved for future use by this interface or one of its
211     * derivatives (e.g., see nsICachingChannel).
212     */
213
214    /**
215     * Set (e.g., by the docshell) to indicate whether or not the channel
216     * corresponds to a document URI.
217     */
218    const unsigned long LOAD_DOCUMENT_URI = 1 << 16;
219
220    /** 
221     * If the end consumer for this load has been retargeted after discovering 
222     * its content, this flag will be set:
223     */
224    const unsigned long LOAD_RETARGETED_DOCUMENT_URI = 1 << 17;
225
226    /**
227     * This flag is set to indicate that this channel is replacing another
228     * channel.  This means that:
229     *
230     * 1) the stream listener this channel will be notifying was initially
231     *    passed to the asyncOpen method of some other channel
232     *
233     *   and
234     *
235     * 2) this channel's URI is a better identifier of the resource being
236     *    accessed than this channel's originalURI.
237     *
238     * This flag can be set, for example, for redirects or for cases when a
239     * single channel has multiple parts to it (and thus can follow
240     * onStopRequest with another onStartRequest/onStopRequest pair, each pair
241     * for a different request).
242     */
243    const unsigned long LOAD_REPLACE = 1 << 18;
244
245    /**
246     * Set (e.g., by the docshell) to indicate whether or not the channel
247     * corresponds to an initial document URI load (e.g., link click).
248     */
249    const unsigned long LOAD_INITIAL_DOCUMENT_URI = 1 << 19;
250
251    /**
252     * Set (e.g., by the URILoader) to indicate whether or not the end consumer
253     * for this load has been determined.
254     */
255    const unsigned long LOAD_TARGETED = 1 << 20;
256
257    /**
258     * If this flag is set, the channel should call the content sniffers as
259     * described in nsNetCID.h about NS_CONTENT_SNIFFER_CATEGORY.
260     *
261     * Note: Channels may ignore this flag; however, new channel implementations
262     * should only do so with good reason.
263     */
264    const unsigned long LOAD_CALL_CONTENT_SNIFFERS = 1 << 21;
265};