/embedding/components/webbrowserpersist/public/nsIWebBrowserPersist.idl

http://github.com/zpao/v8monkey · IDL · 295 lines · 61 code · 17 blank · 217 comment · 0 complexity · 01ac890d26537113ab91723fc06538cc MD5 · raw file

  1. /* -*- Mode: IDL; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*-
  2. *
  3. * ***** BEGIN LICENSE BLOCK *****
  4. * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  5. *
  6. * The contents of this file are subject to the Mozilla Public License Version
  7. * 1.1 (the "License"); you may not use this file except in compliance with
  8. * the License. You may obtain a copy of the License at
  9. * http://www.mozilla.org/MPL/
  10. *
  11. * Software distributed under the License is distributed on an "AS IS" basis,
  12. * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  13. * for the specific language governing rights and limitations under the
  14. * License.
  15. *
  16. * The Original Code is the Mozilla browser.
  17. *
  18. * The Initial Developer of the Original Code is
  19. * Netscape Communications, Inc.
  20. * Portions created by the Initial Developer are Copyright (C) 1999
  21. * the Initial Developer. All Rights Reserved.
  22. *
  23. * Contributor(s):
  24. * Adam Lock <adamlock@netscape.com>
  25. *
  26. * Alternatively, the contents of this file may be used under the terms of
  27. * either the GNU General Public License Version 2 or later (the "GPL"), or
  28. * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  29. * in which case the provisions of the GPL or the LGPL are applicable instead
  30. * of those above. If you wish to allow use of your version of this file only
  31. * under the terms of either the GPL or the LGPL, and not to allow others to
  32. * use your version of this file under the terms of the MPL, indicate your
  33. * decision by deleting the provisions above and replace them with the notice
  34. * and other provisions required by the GPL or the LGPL. If you do not delete
  35. * the provisions above, a recipient may use your version of this file under
  36. * the terms of any one of the MPL, the GPL or the LGPL.
  37. *
  38. * ***** END LICENSE BLOCK ***** */
  39. #include "nsICancelable.idl"
  40. interface nsIURI;
  41. interface nsIInputStream;
  42. interface nsIDOMDocument;
  43. interface nsIWebProgressListener;
  44. interface nsILocalFile;
  45. interface nsIChannel;
  46. /**
  47. * Interface for persisting DOM documents and URIs to local or remote storage.
  48. */
  49. [scriptable, uuid(dd4e0a6a-210f-419a-ad85-40e8543b9465)]
  50. interface nsIWebBrowserPersist : nsICancelable
  51. {
  52. /** No special persistence behaviour. */
  53. const unsigned long PERSIST_FLAGS_NONE = 0;
  54. /** Only use cached data (could result in failure if data is not cached). */
  55. const unsigned long PERSIST_FLAGS_FROM_CACHE = 1;
  56. /** Bypass the cached data. */
  57. const unsigned long PERSIST_FLAGS_BYPASS_CACHE = 2;
  58. /** Ignore any redirected data (usually adverts). */
  59. const unsigned long PERSIST_FLAGS_IGNORE_REDIRECTED_DATA = 4;
  60. /** Ignore IFRAME content (usually adverts). */
  61. const unsigned long PERSIST_FLAGS_IGNORE_IFRAMES = 8;
  62. /** Do not run the incoming data through a content converter e.g. to decompress it */
  63. const unsigned long PERSIST_FLAGS_NO_CONVERSION = 16;
  64. /** Replace existing files on the disk (use with due diligence!) */
  65. const unsigned long PERSIST_FLAGS_REPLACE_EXISTING_FILES = 32;
  66. /** Don't modify or add base tags */
  67. const unsigned long PERSIST_FLAGS_NO_BASE_TAG_MODIFICATIONS = 64;
  68. /** Make changes to original dom rather than cloning nodes */
  69. const unsigned long PERSIST_FLAGS_FIXUP_ORIGINAL_DOM = 128;
  70. /** Fix links relative to destination location (not origin) */
  71. const unsigned long PERSIST_FLAGS_FIXUP_LINKS_TO_DESTINATION = 256;
  72. /** Don't make any adjustments to links */
  73. const unsigned long PERSIST_FLAGS_DONT_FIXUP_LINKS = 512;
  74. /** Force serialization of output (one file at a time; not concurrent) */
  75. const unsigned long PERSIST_FLAGS_SERIALIZE_OUTPUT = 1024;
  76. /** Don't make any adjustments to filenames */
  77. const unsigned long PERSIST_FLAGS_DONT_CHANGE_FILENAMES = 2048;
  78. /** Fail on broken inline links */
  79. const unsigned long PERSIST_FLAGS_FAIL_ON_BROKEN_LINKS = 4096;
  80. /**
  81. * Automatically cleanup after a failed or cancelled operation, deleting all
  82. * created files and directories. This flag does nothing for failed upload
  83. * operations to remote servers.
  84. */
  85. const unsigned long PERSIST_FLAGS_CLEANUP_ON_FAILURE = 8192;
  86. /**
  87. * Let the WebBrowserPersist decide whether the incoming data is encoded
  88. * and whether it needs to go through a content converter e.g. to
  89. * decompress it.
  90. */
  91. const unsigned long PERSIST_FLAGS_AUTODETECT_APPLY_CONVERSION = 16384;
  92. /**
  93. * Append the downloaded data to the target file.
  94. * This can only be used when persisting to a local file.
  95. */
  96. const unsigned long PERSIST_FLAGS_APPEND_TO_FILE = 32768;
  97. /**
  98. * Force relevant cookies to be sent with this load even if normally they
  99. * wouldn't be.
  100. */
  101. const unsigned long PERSIST_FLAGS_FORCE_ALLOW_COOKIES = 65536;
  102. /**
  103. * Flags governing how data is fetched and saved from the network.
  104. * It is best to set this value explicitly unless you are prepared
  105. * to accept the default values.
  106. */
  107. attribute unsigned long persistFlags;
  108. /** Persister is ready to save data */
  109. const unsigned long PERSIST_STATE_READY = 1;
  110. /** Persister is saving data */
  111. const unsigned long PERSIST_STATE_SAVING = 2;
  112. /** Persister has finished saving data */
  113. const unsigned long PERSIST_STATE_FINISHED = 3;
  114. /**
  115. * Current state of the persister object.
  116. */
  117. readonly attribute unsigned long currentState;
  118. /**
  119. * Value indicating the success or failure of the persist
  120. * operation.
  121. *
  122. * @return NS_OK Operation was successful or is still ongoing.
  123. * @return NS_BINDING_ABORTED Operation cancelled.
  124. * @return NS_ERROR_FAILURE Non-specific failure.
  125. */
  126. readonly attribute unsigned long result;
  127. /**
  128. * Callback listener for progress notifications. The object that the
  129. * embbedder supplies may also implement nsIInterfaceRequestor and be
  130. * prepared to return nsIAuthPrompt or other interfaces that may be required
  131. * to download data.
  132. *
  133. * @see nsIAuthPrompt
  134. * @see nsIInterfaceRequestor
  135. */
  136. attribute nsIWebProgressListener progressListener;
  137. /**
  138. * Save the specified URI to file.
  139. *
  140. * @param aURI URI to save to file. Some implementations of this interface
  141. * may also support <CODE>nsnull</CODE> to imply the currently
  142. * loaded URI.
  143. * @param aCacheKey An object representing the URI in the cache or
  144. * <CODE>nsnull</CODE>. This can be a necko cache key,
  145. * an nsIWebPageDescriptor, or the currentDescriptor of an
  146. * nsIWebPageDescriptor.
  147. * @param aReferrer The referrer URI to pass with an HTTP request or
  148. * <CODE>nsnull</CODE>.
  149. * @param aPostData Post data to pass with an HTTP request or
  150. * <CODE>nsnull</CODE>.
  151. * @param aExtraHeaders Additional headers to supply with an HTTP request
  152. * or <CODE>nsnull</CODE>.
  153. * @param aFile Target file. This may be a nsILocalFile object or an
  154. * nsIURI object with a file scheme or a scheme that
  155. * supports uploading (e.g. ftp).
  156. *
  157. * @see nsILocalFile
  158. * @see nsIURI
  159. * @see nsIInputStream
  160. *
  161. * @return NS_OK Operation has been started.
  162. * @return NS_ERROR_INVALID_ARG One or more arguments was invalid.
  163. */
  164. void saveURI(in nsIURI aURI, in nsISupports aCacheKey,
  165. in nsIURI aReferrer, in nsIInputStream aPostData,
  166. in string aExtraHeaders, in nsISupports aFile);
  167. /**
  168. * Save a channel to a file. It must not be opened yet.
  169. * @see saveURI
  170. */
  171. void saveChannel(in nsIChannel aChannel, in nsISupports aFile);
  172. /** Output only the current selection as opposed to the whole document. */
  173. const unsigned long ENCODE_FLAGS_SELECTION_ONLY = 1;
  174. /**
  175. * For plaintext output. Convert html to plaintext that looks like the html.
  176. * Implies wrap (except inside &lt;pre&gt;), since html wraps.
  177. * HTML output: always do prettyprinting, ignoring existing formatting.
  178. */
  179. const unsigned long ENCODE_FLAGS_FORMATTED = 2;
  180. /**
  181. * Output without formatting or wrapping the content. This flag
  182. * may be used to preserve the original formatting as much as possible.
  183. */
  184. const unsigned long ENCODE_FLAGS_RAW = 4;
  185. /** Output only the body section, no HTML tags. */
  186. const unsigned long ENCODE_FLAGS_BODY_ONLY = 8;
  187. /** Wrap even if when not doing formatted output (e.g. for text fields). */
  188. const unsigned long ENCODE_FLAGS_PREFORMATTED = 16;
  189. /** Wrap documents at the specified column. */
  190. const unsigned long ENCODE_FLAGS_WRAP = 32;
  191. /**
  192. * For plaintext output. Output for format flowed (RFC 2646). This is used
  193. * when converting to text for mail sending. This differs just slightly
  194. * but in an important way from normal formatted, and that is that
  195. * lines are space stuffed. This can't (correctly) be done later.
  196. */
  197. const unsigned long ENCODE_FLAGS_FORMAT_FLOWED = 64;
  198. /** Convert links to absolute links where possible. */
  199. const unsigned long ENCODE_FLAGS_ABSOLUTE_LINKS = 128;
  200. /**
  201. * Attempt to encode entities standardized at W3C (HTML, MathML, etc).
  202. * This is a catch-all flag for documents with mixed contents. Beware of
  203. * interoperability issues. See below for other flags which might likely
  204. * do what you want.
  205. */
  206. const unsigned long ENCODE_FLAGS_ENCODE_W3C_ENTITIES = 256;
  207. /**
  208. * Output with carriage return line breaks. May also be combined with
  209. * ENCODE_FLAGS_LF_LINEBREAKS and if neither is specified, the platform
  210. * default format is used.
  211. */
  212. const unsigned long ENCODE_FLAGS_CR_LINEBREAKS = 512;
  213. /**
  214. * Output with linefeed line breaks. May also be combined with
  215. * ENCODE_FLAGS_CR_LINEBREAKS and if neither is specified, the platform
  216. * default format is used.
  217. */
  218. const unsigned long ENCODE_FLAGS_LF_LINEBREAKS = 1024;
  219. /** For plaintext output. Output the content of noscript elements. */
  220. const unsigned long ENCODE_FLAGS_NOSCRIPT_CONTENT = 2048;
  221. /** For plaintext output. Output the content of noframes elements. */
  222. const unsigned long ENCODE_FLAGS_NOFRAMES_CONTENT = 4096;
  223. /**
  224. * Encode basic entities, e.g. output &nbsp; instead of character code 0xa0.
  225. * The basic set is just &nbsp; &amp; &lt; &gt; &quot; for interoperability
  226. * with older products that don't support &alpha; and friends.
  227. */
  228. const unsigned long ENCODE_FLAGS_ENCODE_BASIC_ENTITIES = 8192;
  229. /**
  230. * Encode Latin1 entities. This includes the basic set and
  231. * accented letters between 128 and 255.
  232. */
  233. const unsigned long ENCODE_FLAGS_ENCODE_LATIN1_ENTITIES = 16384;
  234. /**
  235. * Encode HTML4 entities. This includes the basic set, accented
  236. * letters, greek letters and certain special markup symbols.
  237. */
  238. const unsigned long ENCODE_FLAGS_ENCODE_HTML_ENTITIES = 32768;
  239. /**
  240. * Save the specified DOM document to file and optionally all linked files
  241. * (e.g. images, CSS, JS & subframes). Do not call this method until the
  242. * document has finished loading!
  243. *
  244. * @param aDocument Document to save to file. Some implementations of
  245. * this interface may also support <CODE>nsnull</CODE>
  246. * to imply the currently loaded document.
  247. * @param aFile Target local file. This may be a nsILocalFile object or an
  248. * nsIURI object with a file scheme or a scheme that
  249. * supports uploading (e.g. ftp).
  250. * @param aDataPath Path to directory where URIs linked to the document
  251. * are saved or nsnull if no linked URIs should be saved.
  252. * This may be a nsILocalFile object or an nsIURI object
  253. * with a file scheme.
  254. * @param aOutputContentType The desired MIME type format to save the
  255. * document and all subdocuments into or nsnull to use
  256. * the default behaviour.
  257. * @param aEncodingFlags Flags to pass to the encoder.
  258. * @param aWrapColumn For text documents, indicates the desired width to
  259. * wrap text at. Parameter is ignored if wrapping is not
  260. * specified by the encoding flags.
  261. *
  262. * @see nsILocalFile
  263. * @see nsIURI
  264. *
  265. * @return NS_OK Operation has been started.
  266. * @return NS_ERROR_INVALID_ARG One or more arguments was invalid.
  267. */
  268. void saveDocument(in nsIDOMDocument aDocument,
  269. in nsISupports aFile, in nsISupports aDataPath,
  270. in string aOutputContentType, in unsigned long aEncodingFlags,
  271. in unsigned long aWrapColumn);
  272. /**
  273. * Cancels the current operation. The caller is responsible for cleaning up
  274. * partially written files or directories. This has the same effect as calling
  275. * cancel with an argument of NS_BINDING_ABORTED.
  276. */
  277. void cancelSave();
  278. };