Version 1.8 of gecko-sdk. Downloaded from here:...

gecko-sdk/idl/nsIChannel.idl

+/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
+/* ***** BEGIN LICENSE BLOCK *****
+ * Version: MPL 1.1/GPL 2.0/LGPL 2.1
+ *
+ * The contents of this file are subject to the Mozilla Public License Version
+ * 1.1 (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ * http://www.mozilla.org/MPL/
+ *
+ * Software distributed under the License is distributed on an "AS IS" basis,
+ * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
+ * for the specific language governing rights and limitations under the
+ * License.
+ *
+ * The Original Code is mozilla.org code.
+ *
+ * The Initial Developer of the Original Code is
+ * Netscape Communications Corporation.
+ * Portions created by the Initial Developer are Copyright (C) 1998
+ * the Initial Developer. All Rights Reserved.
+ *
+ * Contributor(s):
+ *
+ * Alternatively, the contents of this file may be used under the terms of
+ * either the GNU General Public License Version 2 or later (the "GPL"), or
+ * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
+ * in which case the provisions of the GPL or the LGPL are applicable instead
+ * of those above. If you wish to allow use of your version of this file only
+ * under the terms of either the GPL or the LGPL, and not to allow others to
+ * use your version of this file under the terms of the MPL, indicate your
+ * decision by deleting the provisions above and replace them with the notice
+ * and other provisions required by the GPL or the LGPL. If you do not delete
+ * the provisions above, a recipient may use your version of this file under
+ * the terms of any one of the MPL, the GPL or the LGPL.
+ *
+ * ***** END LICENSE BLOCK ***** */
+
+#include "nsIRequest.idl"
+
+interface nsIURI;
+interface nsIInterfaceRequestor;
+interface nsIInputStream;
+interface nsIStreamListener;
+
+/**
+ * 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. 
+ *
+ * @status FROZEN
+ */
+[scriptable, uuid(c63a055a-a676-4e71-bf3c-6cfa11082018)]
+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. 
+     *
+     * 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.
+     *
+     * 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.
+     */
+    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.
+     *
+     * Callers should prefer getting the "content-length" property
+     * as 64-bit value by QIing the channel to nsIPropertyBag2,
+     * if that interface is exposed by the channel.
+     */
+    attribute long 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.
+     */
+    nsIInputStream open();
+
+    /**
+     * 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.
+     *
+     * @param aListener the nsIStreamListener implementation
+     * @param aContext an opaque parameter forwarded to aListener's methods
+     */
+    void asyncOpen(in nsIStreamListener aListener, in nsISupports aContext);
+
+    /**************************************************************************
+     * Channel specific load flags:
+     *
+     * Bits 21-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 
+     * it's content, this flag will be set:
+     */
+    const unsigned long LOAD_RETARGETED_DOCUMENT_URI = 1 << 17;
+
+    /**
+     * This flag is set to indicate that onStopRequest may be followed by
+     * another onStartRequest/onStopRequest pair.  This flag is, for example,
+     * used by the multipart/replace stream converter.
+     */
+    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;
+};