PageRenderTime 49ms CodeModel.GetById 29ms RepoModel.GetById 0ms app.codeStats 0ms

/gecko_sdk/idl/nsIRequest.idl

http://firefox-mac-pdf.googlecode.com/
IDL | 217 lines | 24 code | 21 blank | 172 comment | 0 complexity | ec964ddac1eb9a0b385a64d79b49ffc4 MD5 | raw file
  1. /* -*- Mode: C++; tab-width: 2; 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 "nsISupports.idl"
  38. interface nsILoadGroup;
  39. typedef unsigned long nsLoadFlags;
  40. /**
  41. * nsIRequest
  42. *
  43. * @status FROZEN
  44. */
  45. [scriptable, uuid(ef6bfbd2-fd46-48d8-96b7-9f8f0fd387fe)]
  46. interface nsIRequest : nsISupports
  47. {
  48. /**
  49. * The name of the request. Often this is the URI of the request.
  50. */
  51. readonly attribute AUTF8String name;
  52. /**
  53. * Indicates whether the request is pending. nsIRequest::isPending is
  54. * true when there is an outstanding asynchronous event that will make
  55. * the request no longer be pending. Requests do not necessarily start
  56. * out pending; in some cases, requests have to be explicitly initiated
  57. * (e.g. nsIChannel implementations are only pending once asyncOpen
  58. * returns successfully).
  59. *
  60. * Requests can become pending multiple times during their lifetime.
  61. *
  62. * @return TRUE if the request has yet to reach completion.
  63. * @return FALSE if the request has reached completion (e.g., after
  64. * OnStopRequest has fired).
  65. * @note Suspended requests are still considered pending.
  66. */
  67. boolean isPending();
  68. /**
  69. * The error status associated with the request.
  70. */
  71. readonly attribute nsresult status;
  72. /**
  73. * Cancels the current request. This will close any open input or
  74. * output streams and terminate any async requests. Users should
  75. * normally pass NS_BINDING_ABORTED, although other errors may also
  76. * be passed. The error passed in will become the value of the
  77. * status attribute.
  78. *
  79. * Implementations must not send any notifications (e.g. via
  80. * nsIRequestObserver) synchronously from this function. Similarly,
  81. * removal from the load group (if any) must also happen asynchronously.
  82. *
  83. * Requests that use nsIStreamListener must not call onDataAvailable
  84. * anymore after cancel has been called.
  85. *
  86. * @param aStatus the reason for canceling this request.
  87. *
  88. * NOTE: most nsIRequest implementations expect aStatus to be a
  89. * failure code; however, some implementations may allow aStatus to
  90. * be a success code such as NS_OK. In general, aStatus should be
  91. * a failure code.
  92. */
  93. void cancel(in nsresult aStatus);
  94. /**
  95. * Suspends the current request. This may have the effect of closing
  96. * any underlying transport (in order to free up resources), although
  97. * any open streams remain logically opened and will continue delivering
  98. * data when the transport is resumed.
  99. *
  100. * Calling cancel() on a suspended request must not send any
  101. * notifications (such as onstopRequest) until the request is resumed.
  102. *
  103. * NOTE: some implementations are unable to immediately suspend, and
  104. * may continue to deliver events already posted to an event queue. In
  105. * general, callers should be capable of handling events even after
  106. * suspending a request.
  107. */
  108. void suspend();
  109. /**
  110. * Resumes the current request. This may have the effect of re-opening
  111. * any underlying transport and will resume the delivery of data to
  112. * any open streams.
  113. */
  114. void resume();
  115. /**
  116. * The load group of this request. While pending, the request is a
  117. * member of the load group. It is the responsibility of the request
  118. * to implement this policy.
  119. */
  120. attribute nsILoadGroup loadGroup;
  121. /**
  122. * The load flags of this request. Bits 0-15 are reserved.
  123. *
  124. * When added to a load group, this request's load flags are merged with
  125. * the load flags of the load group.
  126. */
  127. attribute nsLoadFlags loadFlags;
  128. /**************************************************************************
  129. * Listed below are the various load flags which may be or'd together.
  130. */
  131. /**
  132. * No special load flags:
  133. */
  134. const unsigned long LOAD_NORMAL = 0;
  135. /**
  136. * Don't deliver status notifications to the nsIProgressEventSink, or keep
  137. * this load from completing the nsILoadGroup it may belong to.
  138. */
  139. const unsigned long LOAD_BACKGROUND = 1 << 0;
  140. /**************************************************************************
  141. * The following flags control the flow of data into the cache.
  142. */
  143. /**
  144. * This flag prevents caching of any kind. It does not, however, prevent
  145. * cached content from being used to satisfy this request.
  146. */
  147. const unsigned long INHIBIT_CACHING = 1 << 7;
  148. /**
  149. * This flag prevents caching on disk (or other persistent media), which
  150. * may be needed to preserve privacy. For HTTPS, this flag is set auto-
  151. * matically.
  152. */
  153. const unsigned long INHIBIT_PERSISTENT_CACHING = 1 << 8;
  154. /**************************************************************************
  155. * The following flags control what happens when the cache contains data
  156. * that could perhaps satisfy this request. They are listed in descending
  157. * order of precidence.
  158. */
  159. /**
  160. * Force an end-to-end download of content data from the origin server.
  161. * This flag is used for a shift-reload.
  162. */
  163. const unsigned long LOAD_BYPASS_CACHE = 1 << 9;
  164. /**
  165. * Load from the cache, bypassing protocol specific validation logic. This
  166. * flag is used when browsing via history. It is not recommended for normal
  167. * browsing as it may likely violate reasonable assumptions made by the
  168. * server and confuse users.
  169. */
  170. const unsigned long LOAD_FROM_CACHE = 1 << 10;
  171. /**
  172. * The following flags control the frequency of cached content validation
  173. * when neither LOAD_BYPASS_CACHE or LOAD_FROM_CACHE are set. By default,
  174. * cached content is automatically validated if necessary before reuse.
  175. *
  176. * VALIDATE_ALWAYS forces validation of any cached content independent of
  177. * its expiration time.
  178. *
  179. * VALIDATE_NEVER disables validation of expired content.
  180. *
  181. * VALIDATE_ONCE_PER_SESSION disables validation of expired content,
  182. * provided it has already been validated (at least once) since the start
  183. * of this session.
  184. *
  185. * NOTE TO IMPLEMENTORS:
  186. * These flags are intended for normal browsing, and they should therefore
  187. * not apply to content that must be validated before each use. Consider,
  188. * for example, a HTTP response with a "Cache-control: no-cache" header.
  189. * According to RFC2616, this response must be validated before it can
  190. * be taken from a cache. Breaking this requirement could result in
  191. * incorrect and potentially undesirable side-effects.
  192. */
  193. const unsigned long VALIDATE_ALWAYS = 1 << 11;
  194. const unsigned long VALIDATE_NEVER = 1 << 12;
  195. const unsigned long VALIDATE_ONCE_PER_SESSION = 1 << 13;
  196. };