1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/netwerk/base/public/nsIChannel.idl Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,305 @@
1.4 +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
1.5 +/* This Source Code Form is subject to the terms of the Mozilla Public
1.6 + * License, v. 2.0. If a copy of the MPL was not distributed with this
1.7 + * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
1.8 +
1.9 +#include "nsIRequest.idl"
1.10 +
1.11 +interface nsIURI;
1.12 +interface nsIInterfaceRequestor;
1.13 +interface nsIInputStream;
1.14 +interface nsIStreamListener;
1.15 +
1.16 +/**
1.17 + * The nsIChannel interface allows clients to construct "GET" requests for
1.18 + * specific protocols, and manage them in a uniform way. Once a channel is
1.19 + * created (via nsIIOService::newChannel), parameters for that request may
1.20 + * be set by using the channel attributes, or by QI'ing to a subclass of
1.21 + * nsIChannel for protocol-specific parameters. Then, the URI can be fetched
1.22 + * by calling nsIChannel::open or nsIChannel::asyncOpen.
1.23 + *
1.24 + * After a request has been completed, the channel is still valid for accessing
1.25 + * protocol-specific results. For example, QI'ing to nsIHttpChannel allows
1.26 + * response headers to be retrieved for the corresponding http transaction.
1.27 + *
1.28 + * This interface must be used only from the XPCOM main thread.
1.29 + */
1.30 +[scriptable, uuid(2a8a7237-c1e2-4de7-b669-2002af29e42d)]
1.31 +interface nsIChannel : nsIRequest
1.32 +{
1.33 + /**
1.34 + * The original URI used to construct the channel. This is used in
1.35 + * the case of a redirect or URI "resolution" (e.g. resolving a
1.36 + * resource: URI to a file: URI) so that the original pre-redirect
1.37 + * URI can still be obtained. This is never null. Attempts to
1.38 + * set it to null must throw.
1.39 + *
1.40 + * NOTE: this is distinctly different from the http Referer (referring URI),
1.41 + * which is typically the page that contained the original URI (accessible
1.42 + * from nsIHttpChannel).
1.43 + */
1.44 + attribute nsIURI originalURI;
1.45 +
1.46 + /**
1.47 + * The URI corresponding to the channel. Its value is immutable.
1.48 + */
1.49 + readonly attribute nsIURI URI;
1.50 +
1.51 + /**
1.52 + * The owner, corresponding to the entity that is responsible for this
1.53 + * channel. Used by the security manager to grant or deny privileges to
1.54 + * mobile code loaded from this channel.
1.55 + *
1.56 + * NOTE: this is a strong reference to the owner, so if the owner is also
1.57 + * holding a strong reference to the channel, care must be taken to
1.58 + * explicitly drop its reference to the channel.
1.59 + */
1.60 + attribute nsISupports owner;
1.61 +
1.62 + /**
1.63 + * The notification callbacks for the channel. This is set by clients, who
1.64 + * wish to provide a means to receive progress, status and protocol-specific
1.65 + * notifications. If this value is NULL, the channel implementation may use
1.66 + * the notification callbacks from its load group. The channel may also
1.67 + * query the notification callbacks from its load group if its notification
1.68 + * callbacks do not supply the requested interface.
1.69 + *
1.70 + * Interfaces commonly requested include: nsIProgressEventSink, nsIPrompt,
1.71 + * and nsIAuthPrompt/nsIAuthPrompt2.
1.72 + *
1.73 + * When the channel is done, it must not continue holding references to
1.74 + * this object.
1.75 + *
1.76 + * NOTE: A channel implementation should take care when "caching" an
1.77 + * interface pointer queried from its notification callbacks. If the
1.78 + * notification callbacks are changed, then a cached interface pointer may
1.79 + * become invalid and may therefore need to be re-queried.
1.80 + */
1.81 + attribute nsIInterfaceRequestor notificationCallbacks;
1.82 +
1.83 + /**
1.84 + * Transport-level security information (if any) corresponding to the channel.
1.85 + */
1.86 + readonly attribute nsISupports securityInfo;
1.87 +
1.88 + /**
1.89 + * The MIME type of the channel's content if available.
1.90 + *
1.91 + * NOTE: the content type can often be wrongly specified (e.g., wrong file
1.92 + * extension, wrong MIME type, wrong document type stored on a server, etc.),
1.93 + * and the caller most likely wants to verify with the actual data.
1.94 + *
1.95 + * Setting contentType before the channel has been opened provides a hint
1.96 + * to the channel as to what the MIME type is. The channel may ignore this
1.97 + * hint in deciding on the actual MIME type that it will report.
1.98 + *
1.99 + * Setting contentType after onStartRequest has been fired or after open()
1.100 + * is called will override the type determined by the channel.
1.101 + *
1.102 + * Setting contentType between the time that asyncOpen() is called and the
1.103 + * time when onStartRequest is fired has undefined behavior at this time.
1.104 + *
1.105 + * The value of the contentType attribute is a lowercase string. A value
1.106 + * assigned to this attribute will be parsed and normalized as follows:
1.107 + * 1- any parameters (delimited with a ';') will be stripped.
1.108 + * 2- if a charset parameter is given, then its value will replace the
1.109 + * the contentCharset attribute of the channel.
1.110 + * 3- the stripped contentType will be lowercased.
1.111 + * Any implementation of nsIChannel must follow these rules.
1.112 + */
1.113 + attribute ACString contentType;
1.114 +
1.115 + /**
1.116 + * The character set of the channel's content if available and if applicable.
1.117 + * This attribute only applies to textual data.
1.118 + *
1.119 + * The value of the contentCharset attribute is a mixedcase string.
1.120 + */
1.121 + attribute ACString contentCharset;
1.122 +
1.123 + /**
1.124 + * The length of the data associated with the channel if available. A value
1.125 + * of -1 indicates that the content length is unknown. Note that this is a
1.126 + * 64-bit value and obsoletes the "content-length" property used on some
1.127 + * channels.
1.128 + */
1.129 + attribute int64_t contentLength;
1.130 +
1.131 + /**
1.132 + * Synchronously open the channel.
1.133 + *
1.134 + * @return blocking input stream to the channel's data.
1.135 + *
1.136 + * NOTE: nsIChannel implementations are not required to implement this
1.137 + * method. Moreover, since this method may block the calling thread, it
1.138 + * should not be called on a thread that processes UI events. Like any
1.139 + * other nsIChannel method it must not be called on any thread other
1.140 + * than the XPCOM main thread.
1.141 + *
1.142 + * NOTE: Implementations should throw NS_ERROR_IN_PROGRESS if the channel
1.143 + * is reopened.
1.144 + */
1.145 + nsIInputStream open();
1.146 +
1.147 + /**
1.148 + * Asynchronously open this channel. Data is fed to the specified stream
1.149 + * listener as it becomes available. The stream listener's methods are
1.150 + * called on the thread that calls asyncOpen and are not called until
1.151 + * after asyncOpen returns. If asyncOpen returns successfully, the
1.152 + * channel promises to call at least onStartRequest and onStopRequest.
1.153 + *
1.154 + * If the nsIRequest object passed to the stream listener's methods is not
1.155 + * this channel, an appropriate onChannelRedirect notification needs to be
1.156 + * sent to the notification callbacks before onStartRequest is called.
1.157 + * Once onStartRequest is called, all following method calls on aListener
1.158 + * will get the request that was passed to onStartRequest.
1.159 + *
1.160 + * If the channel's and loadgroup's notification callbacks do not provide
1.161 + * an nsIChannelEventSink when onChannelRedirect would be called, that's
1.162 + * equivalent to having called onChannelRedirect.
1.163 + *
1.164 + * If asyncOpen returns successfully, the channel is responsible for
1.165 + * keeping itself alive until it has called onStopRequest on aListener or
1.166 + * called onChannelRedirect.
1.167 + *
1.168 + * Implementations are allowed to synchronously add themselves to the
1.169 + * associated load group (if any).
1.170 + *
1.171 + * NOTE: Implementations should throw NS_ERROR_ALREADY_OPENED if the
1.172 + * channel is reopened.
1.173 + *
1.174 + * @param aListener the nsIStreamListener implementation
1.175 + * @param aContext an opaque parameter forwarded to aListener's methods
1.176 + * @see nsIChannelEventSink for onChannelRedirect
1.177 + */
1.178 + void asyncOpen(in nsIStreamListener aListener, in nsISupports aContext);
1.179 +
1.180 + /**************************************************************************
1.181 + * Channel specific load flags:
1.182 + *
1.183 + * Bits 23-31 are reserved for future use by this interface or one of its
1.184 + * derivatives (e.g., see nsICachingChannel).
1.185 + */
1.186 +
1.187 + /**
1.188 + * Set (e.g., by the docshell) to indicate whether or not the channel
1.189 + * corresponds to a document URI.
1.190 + */
1.191 + const unsigned long LOAD_DOCUMENT_URI = 1 << 16;
1.192 +
1.193 + /**
1.194 + * If the end consumer for this load has been retargeted after discovering
1.195 + * its content, this flag will be set:
1.196 + */
1.197 + const unsigned long LOAD_RETARGETED_DOCUMENT_URI = 1 << 17;
1.198 +
1.199 + /**
1.200 + * This flag is set to indicate that this channel is replacing another
1.201 + * channel. This means that:
1.202 + *
1.203 + * 1) the stream listener this channel will be notifying was initially
1.204 + * passed to the asyncOpen method of some other channel
1.205 + *
1.206 + * and
1.207 + *
1.208 + * 2) this channel's URI is a better identifier of the resource being
1.209 + * accessed than this channel's originalURI.
1.210 + *
1.211 + * This flag can be set, for example, for redirects or for cases when a
1.212 + * single channel has multiple parts to it (and thus can follow
1.213 + * onStopRequest with another onStartRequest/onStopRequest pair, each pair
1.214 + * for a different request).
1.215 + */
1.216 + const unsigned long LOAD_REPLACE = 1 << 18;
1.217 +
1.218 + /**
1.219 + * Set (e.g., by the docshell) to indicate whether or not the channel
1.220 + * corresponds to an initial document URI load (e.g., link click).
1.221 + */
1.222 + const unsigned long LOAD_INITIAL_DOCUMENT_URI = 1 << 19;
1.223 +
1.224 + /**
1.225 + * Set (e.g., by the URILoader) to indicate whether or not the end consumer
1.226 + * for this load has been determined.
1.227 + */
1.228 + const unsigned long LOAD_TARGETED = 1 << 20;
1.229 +
1.230 + /**
1.231 + * If this flag is set, the channel should call the content sniffers as
1.232 + * described in nsNetCID.h about NS_CONTENT_SNIFFER_CATEGORY.
1.233 + *
1.234 + * Note: Channels may ignore this flag; however, new channel implementations
1.235 + * should only do so with good reason.
1.236 + */
1.237 + const unsigned long LOAD_CALL_CONTENT_SNIFFERS = 1 << 21;
1.238 +
1.239 + /**
1.240 + * This flag tells the channel to use URI classifier service to check
1.241 + * the URI when opening the channel.
1.242 + */
1.243 + const unsigned long LOAD_CLASSIFY_URI = 1 << 22;
1.244 +
1.245 + /**
1.246 + * If this flag is set and a server's response is Content-Type
1.247 + * application/octet-steam, the server's Content-Type will be ignored and
1.248 + * the channel content will be sniffed as though no Content-Type had been
1.249 + * passed.
1.250 + */
1.251 + const unsigned long LOAD_TREAT_APPLICATION_OCTET_STREAM_AS_UNKNOWN = 1 << 23;
1.252 +
1.253 + /**
1.254 + * Set to let explicitely provided credentials be used over credentials
1.255 + * we have cached previously. In some situations like form login using HTTP
1.256 + * auth via XMLHttpRequest we need to let consumers override the cached
1.257 + * credentials explicitely. For form login 403 response instead of 401 is
1.258 + * usually used to prevent an auth dialog. But any code other then 401/7
1.259 + * will leave original credentials in the cache and there is then no way
1.260 + * to override them for the same user name.
1.261 + */
1.262 + const unsigned long LOAD_EXPLICIT_CREDENTIALS = 1 << 24;
1.263 +
1.264 + /**
1.265 + * Access to the type implied or stated by the Content-Disposition header
1.266 + * if available and if applicable. This allows determining inline versus
1.267 + * attachment.
1.268 + *
1.269 + * Setting contentDisposition provides a hint to the channel about the
1.270 + * disposition. If a normal Content-Disposition header is present its
1.271 + * value will always be used. If it is missing the hinted value will
1.272 + * be used if set.
1.273 + *
1.274 + * Implementations should throw NS_ERROR_NOT_AVAILABLE if the header either
1.275 + * doesn't exist for this type of channel or is empty, and return
1.276 + * DISPOSITION_ATTACHMENT if an invalid/noncompliant value is present.
1.277 + */
1.278 + attribute unsigned long contentDisposition;
1.279 + const unsigned long DISPOSITION_INLINE = 0;
1.280 + const unsigned long DISPOSITION_ATTACHMENT = 1;
1.281 +
1.282 + /**
1.283 + * Access to the filename portion of the Content-Disposition header if
1.284 + * available and if applicable. This allows getting the preferred filename
1.285 + * without having to parse it out yourself.
1.286 + *
1.287 + * Setting contentDispositionFilename provides a hint to the channel about
1.288 + * the disposition. If a normal Content-Disposition header is present its
1.289 + * value will always be used. If it is missing the hinted value will be
1.290 + * used if set.
1.291 + *
1.292 + * Implementations should throw NS_ERROR_NOT_AVAILABLE if the header doesn't
1.293 + * exist for this type of channel, if the header is empty, if the header
1.294 + * doesn't contain a filename portion, or the value of the filename
1.295 + * attribute is empty/missing.
1.296 + */
1.297 + attribute AString contentDispositionFilename;
1.298 +
1.299 + /**
1.300 + * Access to the raw Content-Disposition header if available and applicable.
1.301 + *
1.302 + * Implementations should throw NS_ERROR_NOT_AVAILABLE if the header either
1.303 + * doesn't exist for this type of channel or is empty.
1.304 + *
1.305 + * @deprecated Use contentDisposition/contentDispositionFilename instead.
1.306 + */
1.307 + readonly attribute ACString contentDispositionHeader;
1.308 +};
