diff options
Diffstat (limited to 'netwerk/base/nsIChannel.idl')
| -rw-r--r-- | netwerk/base/nsIChannel.idl | 357 |
1 files changed, 357 insertions, 0 deletions
diff --git a/netwerk/base/nsIChannel.idl b/netwerk/base/nsIChannel.idl new file mode 100644 index 000000000..743e94292 --- /dev/null +++ b/netwerk/base/nsIChannel.idl @@ -0,0 +1,357 @@ +/* -*- 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" +#include "nsILoadInfo.idl" + +interface nsIURI; +interface nsIInterfaceRequestor; +interface nsIInputStream; +interface nsIStreamListener; + +%{C++ +#include "nsCOMPtr.h" +%} + +/** + * 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(2c389865-23db-4aa7-9fe5-60cc7b00697e)] +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. + * + * NOTE: In some circumstances TLS information is propagated onto + * non-nsIHttpChannel objects to indicate that their contents were likely + * delivered over TLS all the same. For example, document.open() may + * create an nsWyciwygChannel to store the data that will be written to the + * document. In that case, if the caller has TLS information, we propagate + * that info onto the nsWyciwygChannel given that it is likely that the + * caller will be writing data that was delivered over TLS to the document. + */ + 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(); + + /** + * Performs content security check and calls open() + */ + nsIInputStream open2(); + + /** + * 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); + + /** + * Performs content security check and calls asyncOpen(). + */ + void asyncOpen2(in nsIStreamListener aListener); + + /************************************************************************** + * Channel specific load flags: + * + * Bits 26-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, the media-type content sniffer will be allowed + * to override any server-set content-type. Otherwise it will only + * be allowed to override "no content type" and application/octet-stream. + */ + const unsigned long LOAD_MEDIA_SNIFFER_OVERRIDES_CONTENT_TYPE = 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; + + /** + * Set to force bypass of any service worker interception of the channel. + */ + const unsigned long LOAD_BYPASS_SERVICE_WORKER = 1 << 25; + + // nsICachingChannel load flags begin at bit 26. + + /** + * 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; + + /** + * The LoadInfo object contains information about a network load, why it + * was started, and how we plan on using the resulting response. + * If a network request is redirected, the new channel will receive a new + * LoadInfo object. The new object will contain mostly the same + * information as the pre-redirect one, but updated as appropriate. + * For detailed information about what parts of LoadInfo are updated on + * redirect, see documentation on individual properties. + */ + attribute nsILoadInfo loadInfo; + +%{ C++ + inline already_AddRefed<nsILoadInfo> GetLoadInfo() + { + nsCOMPtr<nsILoadInfo> result; + mozilla::DebugOnly<nsresult> rv = GetLoadInfo(getter_AddRefs(result)); + MOZ_ASSERT(NS_SUCCEEDED(rv) || !result); + return result.forget(); + } +%} + +}; |