/gecko_sdk/idl/nsIChannel.idl
IDL | 265 lines | 25 code | 19 blank | 221 comment | 0 complexity | 9c46f901bbd0bffff03250068a5d335a MD5 | raw file
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};