PageRenderTime 30ms CodeModel.GetById 17ms RepoModel.GetById 1ms app.codeStats 0ms

/gecko_sdk/idl/nsIChannel.idl

http://firefox-mac-pdf.googlecode.com/
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. #include "nsIRequest.idl"
  38. interface nsIURI;
  39. interface nsIInterfaceRequestor;
  40. interface nsIInputStream;
  41. interface nsIStreamListener;
  42. /**
  43. * The nsIChannel interface allows clients to construct "GET" requests for
  44. * specific protocols, and manage them in a uniform way. Once a channel is
  45. * created (via nsIIOService::newChannel), parameters for that request may
  46. * be set by using the channel attributes, or by QI'ing to a subclass of
  47. * nsIChannel for protocol-specific parameters. Then, the URI can be fetched
  48. * by calling nsIChannel::open or nsIChannel::asyncOpen.
  49. *
  50. * After a request has been completed, the channel is still valid for accessing
  51. * protocol-specific results. For example, QI'ing to nsIHttpChannel allows
  52. * response headers to be retrieved for the corresponding http transaction.
  53. *
  54. * @status FROZEN
  55. */
  56. [scriptable, uuid(c63a055a-a676-4e71-bf3c-6cfa11082018)]
  57. interface nsIChannel : nsIRequest
  58. {
  59. /**
  60. * The original URI used to construct the channel. This is used in the case
  61. * of a redirect or URI "resolution" (e.g. resolving a resource: URI to a
  62. * file: URI) so that the original pre-redirect URI can still be obtained.
  63. *
  64. * NOTE: this is distinctly different from the http Referer (referring URI),
  65. * which is typically the page that contained the original URI (accessible
  66. * from nsIHttpChannel).
  67. */
  68. attribute nsIURI originalURI;
  69. /**
  70. * The URI corresponding to the channel. Its value is immutable.
  71. */
  72. readonly attribute nsIURI URI;
  73. /**
  74. * The owner, corresponding to the entity that is responsible for this
  75. * channel. Used by the security manager to grant or deny privileges to
  76. * mobile code loaded from this channel.
  77. *
  78. * NOTE: this is a strong reference to the owner, so if the owner is also
  79. * holding a strong reference to the channel, care must be taken to
  80. * explicitly drop its reference to the channel.
  81. */
  82. attribute nsISupports owner;
  83. /**
  84. * The notification callbacks for the channel. This is set by clients, who
  85. * wish to provide a means to receive progress, status and protocol-specific
  86. * notifications. If this value is NULL, the channel implementation may use
  87. * the notification callbacks from its load group. The channel may also
  88. * query the notification callbacks from its load group if its notification
  89. * callbacks do not supply the requested interface.
  90. *
  91. * Interfaces commonly requested include: nsIProgressEventSink, nsIPrompt,
  92. * and nsIAuthPrompt/nsIAuthPrompt2.
  93. *
  94. * When the channel is done, it must not continue holding references to
  95. * this object.
  96. *
  97. * NOTE: A channel implementation should take care when "caching" an
  98. * interface pointer queried from its notification callbacks. If the
  99. * notification callbacks are changed, then a cached interface pointer may
  100. * become invalid and may therefore need to be re-queried.
  101. */
  102. attribute nsIInterfaceRequestor notificationCallbacks;
  103. /**
  104. * Transport-level security information (if any) corresponding to the channel.
  105. */
  106. readonly attribute nsISupports securityInfo;
  107. /**
  108. * The MIME type of the channel's content if available.
  109. *
  110. * NOTE: the content type can often be wrongly specified (e.g., wrong file
  111. * extension, wrong MIME type, wrong document type stored on a server, etc.),
  112. * and the caller most likely wants to verify with the actual data.
  113. *
  114. * Setting contentType before the channel has been opened provides a hint
  115. * to the channel as to what the MIME type is. The channel may ignore this
  116. * hint in deciding on the actual MIME type that it will report.
  117. *
  118. * Setting contentType after onStartRequest has been fired or after open()
  119. * is called will override the type determined by the channel.
  120. *
  121. * Setting contentType between the time that asyncOpen() is called and the
  122. * time when onStartRequest is fired has undefined behavior at this time.
  123. *
  124. * The value of the contentType attribute is a lowercase string. A value
  125. * assigned to this attribute will be parsed and normalized as follows:
  126. * 1- any parameters (delimited with a ';') will be stripped.
  127. * 2- if a charset parameter is given, then its value will replace the
  128. * the contentCharset attribute of the channel.
  129. * 3- the stripped contentType will be lowercased.
  130. * Any implementation of nsIChannel must follow these rules.
  131. */
  132. attribute ACString contentType;
  133. /**
  134. * The character set of the channel's content if available and if applicable.
  135. * This attribute only applies to textual data.
  136. *
  137. * The value of the contentCharset attribute is a mixedcase string.
  138. */
  139. attribute ACString contentCharset;
  140. /**
  141. * The length of the data associated with the channel if available. A value
  142. * of -1 indicates that the content length is unknown.
  143. *
  144. * Callers should prefer getting the "content-length" property
  145. * as 64-bit value by QIing the channel to nsIPropertyBag2,
  146. * if that interface is exposed by the channel.
  147. */
  148. attribute long contentLength;
  149. /**
  150. * Synchronously open the channel.
  151. *
  152. * @return blocking input stream to the channel's data.
  153. *
  154. * NOTE: nsIChannel implementations are not required to implement this
  155. * method. Moreover, since this method may block the calling thread, it
  156. * should not be called on a thread that processes UI events.
  157. *
  158. * NOTE: Implementations should throw NS_ERROR_IN_PROGRESS if the channel
  159. * is reopened.
  160. */
  161. nsIInputStream open();
  162. /**
  163. * Asynchronously open this channel. Data is fed to the specified stream
  164. * listener as it becomes available. The stream listener's methods are
  165. * called on the thread that calls asyncOpen and are not called until
  166. * after asyncOpen returns. If asyncOpen returns successfully, the
  167. * channel promises to call at least onStartRequest and onStopRequest.
  168. *
  169. * If the nsIRequest object passed to the stream listener's methods is not
  170. * this channel, an appropriate onChannelRedirect notification needs to be
  171. * sent to the notification callbacks before onStartRequest is called.
  172. * Once onStartRequest is called, all following method calls on aListener
  173. * will get the request that was passed to onStartRequest.
  174. *
  175. * If the channel's and loadgroup's notification callbacks do not provide
  176. * an nsIChannelEventSink when onChannelRedirect would be called, that's
  177. * equivalent to having called onChannelRedirect.
  178. *
  179. * If asyncOpen returns successfully, the channel is responsible for
  180. * keeping itself alive until it has called onStopRequest on aListener or
  181. * called onChannelRedirect.
  182. *
  183. * Implementations are allowed to synchronously add themselves to the
  184. * associated load group (if any).
  185. *
  186. * NOTE: Implementations should throw NS_ERROR_ALREADY_OPENED if the
  187. * channel is reopened.
  188. *
  189. * @param aListener the nsIStreamListener implementation
  190. * @param aContext an opaque parameter forwarded to aListener's methods
  191. * @see nsIChannelEventSink for onChannelRedirect
  192. */
  193. void asyncOpen(in nsIStreamListener aListener, in nsISupports aContext);
  194. /**************************************************************************
  195. * Channel specific load flags:
  196. *
  197. * Bits 22-31 are reserved for future use by this interface or one of its
  198. * derivatives (e.g., see nsICachingChannel).
  199. */
  200. /**
  201. * Set (e.g., by the docshell) to indicate whether or not the channel
  202. * corresponds to a document URI.
  203. */
  204. const unsigned long LOAD_DOCUMENT_URI = 1 << 16;
  205. /**
  206. * If the end consumer for this load has been retargeted after discovering
  207. * its content, this flag will be set:
  208. */
  209. const unsigned long LOAD_RETARGETED_DOCUMENT_URI = 1 << 17;
  210. /**
  211. * This flag is set to indicate that this channel is replacing another
  212. * channel. This means that:
  213. *
  214. * 1) the stream listener this channel will be notifying was initially
  215. * passed to the asyncOpen method of some other channel
  216. *
  217. * and
  218. *
  219. * 2) this channel's URI is a better identifier of the resource being
  220. * accessed than this channel's originalURI.
  221. *
  222. * This flag can be set, for example, for redirects or for cases when a
  223. * single channel has multiple parts to it (and thus can follow
  224. * onStopRequest with another onStartRequest/onStopRequest pair, each pair
  225. * for a different request).
  226. */
  227. const unsigned long LOAD_REPLACE = 1 << 18;
  228. /**
  229. * Set (e.g., by the docshell) to indicate whether or not the channel
  230. * corresponds to an initial document URI load (e.g., link click).
  231. */
  232. const unsigned long LOAD_INITIAL_DOCUMENT_URI = 1 << 19;
  233. /**
  234. * Set (e.g., by the URILoader) to indicate whether or not the end consumer
  235. * for this load has been determined.
  236. */
  237. const unsigned long LOAD_TARGETED = 1 << 20;
  238. /**
  239. * If this flag is set, the channel should call the content sniffers as
  240. * described in nsNetCID.h about NS_CONTENT_SNIFFER_CATEGORY.
  241. *
  242. * Note: Channels may ignore this flag; however, new channel implementations
  243. * should only do so with good reason.
  244. */
  245. const unsigned long LOAD_CALL_CONTENT_SNIFFERS = 1 << 21;
  246. };