netwerk/base/nsIChannel.idl

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #include "nsIRequest.idl"
   7 #include "nsILoadInfo.idl"
   8
   9 interface nsIInputStream;
  10 interface nsIInterfaceRequestor;
  11 interface nsIStreamListener;
  12 interface nsITransportSecurityInfo;
  13 interface nsIURI;
  14
  15 %{C++
  16 #include "nsCOMPtr.h"
  17 %}
  18
  19 /**
  20  * The nsIChannel interface allows clients to construct "GET" requests for
  21  * specific protocols, and manage them in a uniform way.  Once a channel is
  22  * created (via nsIIOService::newChannel), parameters for that request may
  23  * be set by using the channel attributes, or by QI'ing to a subclass of
  24  * nsIChannel for protocol-specific parameters.  Then, the URI can be fetched
  25  * by calling nsIChannel::open or nsIChannel::asyncOpen.
  26  *
  27  * After a request has been completed, the channel is still valid for accessing
  28  * protocol-specific results.  For example, QI'ing to nsIHttpChannel allows
  29  * response headers to be retrieved for the corresponding http transaction.
  30  *
  31  * This interface must be used only from the XPCOM main thread.
  32  */
  33 [scriptable, uuid(2c389865-23db-4aa7-9fe5-60cc7b00697e)]
  34 interface nsIChannel : nsIRequest
  35 {
  36     /**
  37      * The original URI used to construct the channel. This is used in
  38      * the case of a redirect or URI "resolution" (e.g. resolving a
  39      * resource: URI to a file: URI) so that the original pre-redirect
  40      * URI can still be obtained.  This is never null.  Attempts to
  41      * set it to null must throw.
  42      *
  43      * NOTE: this is distinctly different from the http Referer (referring URI),
  44      * which is typically the page that contained the original URI (accessible
  45      * from nsIHttpChannel).
  46      *
  47      * NOTE: originalURI isn't yet set on the new channel when
  48      * asyncOnChannelRedirect is called.
  49      */
  50     attribute nsIURI originalURI;
  51
  52     /**
  53      * The URI corresponding to the channel.  Its value is immutable.
  54      */
  55     readonly attribute nsIURI URI;
  56
  57     /**
  58      * The owner, corresponding to the entity that is responsible for this
  59      * channel.  Used by the security manager to grant or deny privileges to
  60      * mobile code loaded from this channel.
  61      *
  62      * NOTE: this is a strong reference to the owner, so if the owner is also
  63      * holding a strong reference to the channel, care must be taken to
  64      * explicitly drop its reference to the channel.
  65      */
  66     attribute nsISupports owner;
  67
  68     /**
  69      * The notification callbacks for the channel.  This is set by clients, who
  70      * wish to provide a means to receive progress, status and protocol-specific
  71      * notifications.  If this value is NULL, the channel implementation may use
  72      * the notification callbacks from its load group.  The channel may also
  73      * query the notification callbacks from its load group if its notification
  74      * callbacks do not supply the requested interface.
  75      *
  76      * Interfaces commonly requested include: nsIProgressEventSink, nsIPrompt,
  77      * and nsIAuthPrompt/nsIAuthPrompt2.
  78      *
  79      * When the channel is done, it must not continue holding references to
  80      * this object.
  81      *
  82      * NOTE: A channel implementation should take care when "caching" an
  83      * interface pointer queried from its notification callbacks.  If the
  84      * notification callbacks are changed, then a cached interface pointer may
  85      * become invalid and may therefore need to be re-queried.
  86      */
  87     attribute nsIInterfaceRequestor notificationCallbacks;
  88
  89     /**
  90      * Transport-level security information (if any) corresponding to the
  91      * channel.
  92      *
  93      * NOTE: In some circumstances TLS information is propagated onto
  94      * non-nsIHttpChannel objects to indicate that their contents were likely
  95      * delivered over TLS all the same.
  96      *
  97      * FIXME(bz, bug 1528449) is that still true now that
  98      * document.open() doesn't do this?
  99      */
 100     readonly attribute nsITransportSecurityInfo securityInfo;
 101
 102     /**
 103      * The MIME type of the channel's content if available.
 104      *
 105      * NOTE: the content type can often be wrongly specified (e.g., wrong file
 106      * extension, wrong MIME type, wrong document type stored on a server, etc.),
 107      * and the caller most likely wants to verify with the actual data.
 108      *
 109      * Setting contentType before the channel has been opened provides a hint
 110      * to the channel as to what the MIME type is.  The channel may ignore this
 111      * hint in deciding on the actual MIME type that it will report.
 112      *
 113      * Setting contentType after onStartRequest has been fired or after open()
 114      * is called will override the type determined by the channel.
 115      *
 116      * Setting contentType between the time that asyncOpen() is called and the
 117      * time when onStartRequest is fired has undefined behavior at this time.
 118      *
 119      * The value of the contentType attribute is a lowercase string.  A value
 120      * assigned to this attribute will be parsed and normalized as follows:
 121      *  1- any parameters (delimited with a ';') will be stripped.
 122      *  2- if a charset parameter is given, then its value will replace the
 123      *     the contentCharset attribute of the channel.
 124      *  3- the stripped contentType will be lowercased.
 125      * Any implementation of nsIChannel must follow these rules.
 126      */
 127     attribute ACString contentType;
 128
 129     /**
 130      * The character set of the channel's content if available and if applicable.
 131      * This attribute only applies to textual data.
 132      *
 133      * The value of the contentCharset attribute is a mixedcase string.
 134      */
 135     attribute ACString contentCharset;
 136
 137     /**
 138      * The length of the data associated with the channel if available.  A value
 139      * of -1 indicates that the content length is unknown. Note that this is a
 140      * 64-bit value and obsoletes the "content-length" property used on some
 141      * channels.
 142      */
 143     attribute int64_t contentLength;
 144
 145     /**
 146      * Synchronously open the channel.
 147      *
 148      * @return blocking input stream to the channel's data.
 149      *
 150      * NOTE: nsIChannel implementations are not required to implement this
 151      * method.  Moreover, since this method may block the calling thread, it
 152      * should not be called on a thread that processes UI events.  Like any
 153      * other nsIChannel method it must not be called on any thread other
 154      * than the XPCOM main thread.
 155      *
 156      * NOTE: Implementations should throw NS_ERROR_IN_PROGRESS if the channel
 157      * is reopened.
 158      */
 159     nsIInputStream open();
 160
 161     /**
 162      * Asynchronously open this channel.  Data is fed to the specified stream
 163      * listener as it becomes available.  The stream listener's methods are
 164      * called on the thread that calls asyncOpen and are not called until
 165      * after asyncOpen returns.  If asyncOpen returns successfully, the
 166      * channel promises to call at least onStartRequest and onStopRequest.
 167      *
 168      * If the nsIRequest object passed to the stream listener's methods is not
 169      * this channel, an appropriate onChannelRedirect notification needs to be
 170      * sent to the notification callbacks before onStartRequest is called.
 171      * Once onStartRequest is called, all following method calls on aListener
 172      * will get the request that was passed to onStartRequest.
 173      *
 174      * If the channel's and loadgroup's notification callbacks do not provide
 175      * an nsIChannelEventSink when onChannelRedirect would be called, that's
 176      * equivalent to having called onChannelRedirect.
 177      *
 178      * If asyncOpen returns successfully, the channel is responsible for
 179      * keeping itself alive until it has called onStopRequest on aListener or
 180      * called onChannelRedirect.
 181      *
 182      * Implementations are allowed to synchronously add themselves to the
 183      * associated load group (if any).
 184      *
 185      * NOTE: Implementations should throw NS_ERROR_ALREADY_OPENED if the
 186      * channel is reopened.
 187      * NOTE: Implementations should throw an error if the channel has been
 188      * cancelled prior asyncOpen being called.
 189      *
 190      * @param aListener the nsIStreamListener implementation
 191      * @see nsIChannelEventSink for onChannelRedirect
 192      */
 193     void asyncOpen(in nsIStreamListener aListener);
 194
 195     /**
 196      * True if the channel has been canceled.
 197      */
 198     [must_use] readonly attribute boolean canceled;
 199
 200     /**************************************************************************
 201      * Channel specific load flags:
 202      *
 203      * Bits 16-31 are reserved for future use by this interface or one of its
 204      * derivatives (e.g., see nsICachingChannel).
 205      */
 206
 207     /**
 208      * Set (e.g., by the docshell) to indicate whether or not the channel
 209      * corresponds to a document URI.
 210      * While setting this flag is sufficient to mark a channel as a document
 211      * load, _checking_ whether the channel is a document load requires the use
 212      * of the new channel.isDocument
 213      */
 214     const unsigned long LOAD_DOCUMENT_URI = 1 << 16;
 215
 216     /**
 217      * If the end consumer for this load has been retargeted after discovering
 218      * its content, this flag will be set:
 219      */
 220     const unsigned long LOAD_RETARGETED_DOCUMENT_URI = 1 << 17;
 221
 222     /**
 223      * This flag is set to indicate that this channel is replacing another
 224      * channel.  This means that:
 225      *
 226      * 1) the stream listener this channel will be notifying was initially
 227      *    passed to the asyncOpen method of some other channel
 228      *
 229      *   and
 230      *
 231      * 2) this channel's URI is a better identifier of the resource being
 232      *    accessed than this channel's originalURI.
 233      *
 234      * This flag can be set, for example, for redirects or for cases when a
 235      * single channel has multiple parts to it (and thus can follow
 236      * onStopRequest with another onStartRequest/onStopRequest pair, each pair
 237      * for a different request).
 238      */
 239     const unsigned long LOAD_REPLACE = 1 << 18;
 240
 241     /**
 242      * Set (e.g., by the docshell) to indicate whether or not the channel
 243      * corresponds to an initial document URI load (e.g., link click).
 244      */
 245     const unsigned long LOAD_INITIAL_DOCUMENT_URI = 1 << 19;
 246
 247     /**
 248      * Set (e.g., by the URILoader) to indicate whether or not the end consumer
 249      * for this load has been determined.
 250      */
 251     const unsigned long LOAD_TARGETED = 1 << 20;
 252
 253     /**
 254      * If this flag is set, the channel should call the content sniffers as
 255      * described in nsNetCID.h about NS_CONTENT_SNIFFER_CATEGORY.
 256      *
 257      * Note: Channels may ignore this flag; however, new channel implementations
 258      * should only do so with good reason.
 259      */
 260     const unsigned long LOAD_CALL_CONTENT_SNIFFERS = 1 << 21;
 261
 262     /**
 263      * This flag tells the channel to bypass URL classifier service check
 264      * when opening the channel.
 265      */
 266     const unsigned long LOAD_BYPASS_URL_CLASSIFIER = 1 << 22;
 267
 268     /**
 269      * If this flag is set, the media-type content sniffer will be allowed
 270      * to override any server-set content-type. Otherwise it will only
 271      * be allowed to override "no content type" and application/octet-stream.
 272      */
 273     const unsigned long LOAD_MEDIA_SNIFFER_OVERRIDES_CONTENT_TYPE = 1 << 23;
 274
 275     /**
 276      * Set to let explicitely provided credentials be used over credentials
 277      * we have cached previously. In some situations like form login using HTTP
 278      * auth via XMLHttpRequest we need to let consumers override the cached
 279      * credentials explicitely. For form login 403 response instead of 401 is
 280      * usually used to prevent an auth dialog. But any code other then 401/7
 281      * will leave original credentials in the cache and there is then no way
 282      * to override them for the same user name.
 283      */
 284     const unsigned long LOAD_EXPLICIT_CREDENTIALS = 1 << 24;
 285
 286     /**
 287      * Set to force bypass of any service worker interception of the channel.
 288      */
 289     const unsigned long LOAD_BYPASS_SERVICE_WORKER = 1 << 25;
 290
 291     // nsICachingChannel load flags begin at bit 26.
 292
 293     /**
 294      * Access to the type implied or stated by the Content-Disposition header
 295      * if available and if applicable. This allows determining inline versus
 296      * attachment.
 297      *
 298      * Setting contentDisposition provides a hint to the channel about the
 299      * disposition.  If the hint is DISPOSITION_ATTACHMENT and a normal
 300      * Content-Disposition header is present, the hinted value will always be
 301      * used. If the hint is DISPOSITION_FORCE_INLINE then the disposition is
 302      * inline and the header is not used. The value from Content-Disposition
 303      * header is only used when the hinted value is not DISPOSITION_INLINE or
 304      * DISPOSITION_FORCE_INLINE.
 305      * If the header is missing the hinted value will be used if set.
 306      *
 307      * Implementations should throw NS_ERROR_NOT_AVAILABLE if the header either
 308      * doesn't exist for this type of channel or is empty, and return
 309      * DISPOSITION_ATTACHMENT if an invalid/noncompliant value is present.
 310      */
 311     attribute unsigned long contentDisposition;
 312     const unsigned long DISPOSITION_INLINE = 0;
 313     const unsigned long DISPOSITION_ATTACHMENT = 1;
 314     const unsigned long DISPOSITION_FORCE_INLINE = 2;
 315
 316     /**
 317      * Access to the filename portion of the Content-Disposition header if
 318      * available and if applicable. This allows getting the preferred filename
 319      * without having to parse it out yourself.
 320      *
 321      * Setting contentDispositionFilename provides a hint to the channel about
 322      * the disposition.  If a normal Content-Disposition header is present its
 323      * value will always be used.  If it is missing the hinted value will be
 324      * used if set.
 325      *
 326      * Implementations should throw NS_ERROR_NOT_AVAILABLE if the header doesn't
 327      * exist for this type of channel, if the header is empty, if the header
 328      * doesn't contain a filename portion, or the value of the filename
 329      * attribute is empty/missing.
 330      */
 331     attribute AString contentDispositionFilename;
 332
 333     /**
 334      * Access to the raw Content-Disposition header if available and applicable.
 335      *
 336      * Implementations should throw NS_ERROR_NOT_AVAILABLE if the header either
 337      * doesn't exist for this type of channel or is empty.
 338      *
 339      * @deprecated Use contentDisposition/contentDispositionFilename instead.
 340      */
 341     readonly attribute ACString contentDispositionHeader;
 342
 343     /**
 344      * The LoadInfo object contains information about a network load, why it
 345      * was started, and how we plan on using the resulting response.
 346      * If a network request is redirected, the new channel will receive a new
 347      * LoadInfo object. The new object will contain mostly the same
 348      * information as the pre-redirect one, but updated as appropriate.
 349      * For detailed information about what parts of LoadInfo are updated on
 350      * redirect, see documentation on individual properties.
 351      */
 352     attribute nsILoadInfo loadInfo;
 353
 354     /**
 355      * Returns true if the channel is used to create a document.
 356      * It returns true if the loadFlags have LOAD_DOCUMENT_URI set, or if
 357      * LOAD_HTML_OBJECT_DATA is set and the channel has the appropriate
 358      * MIME type.
 359      * Note: May have the wrong value if called before OnStartRequest as we
 360      * don't know the MIME type yet.
 361      */
 362     readonly attribute bool isDocument;
 363
 364 %{ C++
 365   inline bool IsDocument()
 366   {
 367     bool isDocument = false;
 368     if (NS_SUCCEEDED(GetIsDocument(&isDocument)) && isDocument) {
 369       return true;
 370     }
 371     return false;
 372   }
 373
 374   inline already_AddRefed<nsILoadInfo> LoadInfo()
 375   {
 376     nsCOMPtr<nsILoadInfo> result;
 377     mozilla::DebugOnly<nsresult> rv = GetLoadInfo(getter_AddRefs(result));
 378     MOZ_ASSERT(NS_SUCCEEDED(rv) && result);
 379     return result.forget();
 380   }
 381 %}
 382
 383 };
 384
 385 [builtinclass, scriptable, uuid(1ebbff64-d742-4f4a-aad5-4df2d1eb937a)]
 386 interface nsIIdentChannel : nsIChannel
 387 {
 388     /**
 389      * Unique ID of the channel, shared between parent and child. Needed if
 390      * the channel activity needs to be monitored across process boundaries,
 391      * like in devtools net monitor. See bug 1274556.
 392      */
 393     [must_use] attribute uint64_t channelId;
 394
 395 %{ C++
 396   inline uint64_t ChannelId()
 397   {
 398     uint64_t value = 0;
 399     if (NS_SUCCEEDED(GetChannelId(&value))) {
 400       return value;
 401     }
 402     return 0;
 403   }
 404 %}
 405 };