/modules/libjar/zipwriter/public/nsIZipWriter.idl

http://github.com/zpao/v8monkey · IDL · 242 lines · 34 code · 15 blank · 193 comment · 0 complexity · 2618db422f8ef5295e8998ddeba41970 MD5 · raw file

  1. /* ***** BEGIN LICENSE BLOCK *****
  2. * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  3. *
  4. * The contents of this file are subject to the Mozilla Public License Version
  5. * 1.1 (the "License"); you may not use this file except in compliance with
  6. * the License. You may obtain a copy of the License at
  7. * http://www.mozilla.org/MPL/
  8. *
  9. * Software distributed under the License is distributed on an "AS IS" basis,
  10. * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  11. * for the specific language governing rights and limitations under the
  12. * License.
  13. *
  14. * The Original Code is Zip Writer Component.
  15. *
  16. * The Initial Developer of the Original Code is
  17. * Dave Townsend <dtownsend@oxymoronical.com>.
  18. *
  19. * Portions created by the Initial Developer are Copyright (C) 2007
  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 "nsISupports.idl"
  39. interface nsIChannel;
  40. interface nsIInputStream;
  41. interface nsIRequestObserver;
  42. interface nsIFile;
  43. interface nsIZipEntry;
  44. /**
  45. * nsIZipWriter
  46. *
  47. * An interface for a zip archiver that can be used from script.
  48. *
  49. * The interface supports both a synchronous method of archiving data and a
  50. * queueing system to allow operations to be prepared then run in sequence
  51. * with notification after completion.
  52. *
  53. * Operations added to the queue do not get performed until performQueue is
  54. * called at which point they will be performed in the order that they were
  55. * added to the queue.
  56. *
  57. * Operations performed on the queue will throw any errors out to the
  58. * observer.
  59. *
  60. * An attempt to perform a synchronous operation while the background queue
  61. * is in progress will throw NS_ERROR_IN_PROGRESS.
  62. *
  63. * Entry names should use /'s as path separators and should not start with
  64. * a /.
  65. *
  66. * It is not generally necessary to add directory entries in order to add file
  67. * entries within them, however it is possible that some zip programs may
  68. * experience problems what that.
  69. */
  70. [scriptable, uuid(6d4ef074-206c-4649-9884-57bc355864d6)]
  71. interface nsIZipWriter : nsISupports
  72. {
  73. /**
  74. * Some predefined compression levels
  75. */
  76. const PRUint32 COMPRESSION_NONE = 0;
  77. const PRUint32 COMPRESSION_FASTEST = 1;
  78. const PRUint32 COMPRESSION_DEFAULT = 6;
  79. const PRUint32 COMPRESSION_BEST = 9;
  80. /**
  81. * Gets or sets the comment associated with the open zip file.
  82. *
  83. * @throws NS_ERROR_NOT_INITIALIZED if no zip file has been opened
  84. */
  85. attribute ACString comment;
  86. /**
  87. * Indicates that operations on the background queue are being performed.
  88. */
  89. readonly attribute boolean inQueue;
  90. /**
  91. * The file that the zipwriter is writing to.
  92. */
  93. readonly attribute nsIFile file;
  94. /**
  95. * Opens a zip file.
  96. *
  97. * @param aFile the zip file to open
  98. * @param aIoFlags the open flags for the zip file from prio.h
  99. *
  100. * @throws NS_ERROR_ALREADY_INITIALIZED if a zip file is already open
  101. * @throws NS_ERROR_INVALID_ARG if aFile is null
  102. * @throws NS_ERROR_FILE_NOT_FOUND if aFile does not exist and flags did
  103. * not allow for creation
  104. * @throws NS_ERROR_FILE_CORRUPTED if the file does not contain zip markers
  105. * @throws <other-error> on failure to open zip file (most likely corrupt
  106. * or unsupported form)
  107. */
  108. void open(in nsIFile aFile, in PRInt32 aIoFlags);
  109. /**
  110. * Returns a nsIZipEntry describing a specified zip entry or null if there
  111. * is no such entry in the zip file
  112. *
  113. * @param aZipEntry the path of the entry
  114. */
  115. nsIZipEntry getEntry(in AUTF8String aZipEntry);
  116. /**
  117. * Checks whether the zipfile contains an entry specified by zipEntry.
  118. *
  119. * @param aZipEntry the path of the entry
  120. */
  121. boolean hasEntry(in AUTF8String aZipEntry);
  122. /**
  123. * Adds a new directory entry to the zip file. If aZipEntry does not end with
  124. * "/" then it will be added.
  125. *
  126. * @param aZipEntry the path of the directory entry
  127. * @param aModTime the modification time of the entry in microseconds
  128. * @param aQueue adds the operation to the background queue. Will be
  129. * performed when processQueue is called.
  130. *
  131. * @throws NS_ERROR_NOT_INITIALIZED if no zip file has been opened
  132. * @throws NS_ERROR_FILE_ALREADY_EXISTS if the path already exists in the
  133. * file
  134. * @throws NS_ERROR_IN_PROGRESS if another operation is currently in progress
  135. */
  136. void addEntryDirectory(in AUTF8String aZipEntry, in PRTime aModTime,
  137. in boolean aQueue);
  138. /**
  139. * Adds a new file or directory to the zip file. If the specified file is
  140. * a directory then this will be equivalent to a call to
  141. * addEntryDirectory(aZipEntry, aFile.lastModifiedTime, aQueue)
  142. *
  143. * @param aZipEntry the path of the file entry
  144. * @param aCompression the compression level, 0 is no compression, 9 is best
  145. * @param aFile the file to get the data and modification time from
  146. * @param aQueue adds the operation to the background queue. Will be
  147. * performed when processQueue is called.
  148. *
  149. * @throws NS_ERROR_NOT_INITIALIZED if no zip file has been opened
  150. * @throws NS_ERROR_FILE_ALREADY_EXISTS if the path already exists in the zip
  151. * @throws NS_ERROR_IN_PROGRESS if another operation is currently in progress
  152. * @throws NS_ERROR_FILE_NOT_FOUND if file does not exist
  153. */
  154. void addEntryFile(in AUTF8String aZipEntry,
  155. in PRInt32 aCompression, in nsIFile aFile,
  156. in boolean aQueue);
  157. /**
  158. * Adds data from a channel to the zip file. If the operation is performed
  159. * on the queue then the channel will be opened asynchronously, otherwise
  160. * the channel must support being opened synchronously.
  161. *
  162. * @param aZipEntry the path of the file entry
  163. * @param aModTime the modification time of the entry in microseconds
  164. * @param aCompression the compression level, 0 is no compression, 9 is best
  165. * @param aChannel the channel to get the data from
  166. * @param aQueue adds the operation to the background queue. Will be
  167. * performed when processQueue is called.
  168. *
  169. * @throws NS_ERROR_NOT_INITIALIZED if no zip file has been opened
  170. * @throws NS_ERROR_FILE_ALREADY_EXISTS if the path already exists in the zip
  171. * @throws NS_ERROR_IN_PROGRESS if another operation is currently in progress
  172. */
  173. void addEntryChannel(in AUTF8String aZipEntry, in PRTime aModTime,
  174. in PRInt32 aCompression, in nsIChannel aChannel,
  175. in boolean aQueue);
  176. /**
  177. * Adds data from an input stream to the zip file.
  178. *
  179. * @param aZipEntry the path of the file entry
  180. * @param aModTime the modification time of the entry in microseconds
  181. * @param aCompression the compression level, 0 is no compression, 9 is best
  182. * @param aStream the input stream to get the data from
  183. * @param aQueue adds the operation to the background queue. Will be
  184. * performed when processQueue is called.
  185. *
  186. * @throws NS_ERROR_NOT_INITIALIZED if no zip file has been opened
  187. * @throws NS_ERROR_FILE_ALREADY_EXISTS if the path already exists in the zip
  188. * @throws NS_ERROR_IN_PROGRESS if another operation is currently in progress
  189. */
  190. void addEntryStream(in AUTF8String aZipEntry, in PRTime aModTime,
  191. in PRInt32 aCompression, in nsIInputStream aStream,
  192. in boolean aQueue);
  193. /**
  194. * Removes an existing entry from the zip file.
  195. *
  196. * @param aZipEntry the path of the entry to be removed
  197. * @param aQueue adds the operation to the background queue. Will be
  198. * performed when processQueue is called.
  199. *
  200. * @throws NS_ERROR_NOT_INITIALIZED if no zip file has been opened
  201. * @throws NS_ERROR_IN_PROGRESS if another operation is currently in progress
  202. * @throws NS_ERROR_FILE_NOT_FOUND if no entry with the given path exists
  203. * @throws <other-error> on failure to update the zip file
  204. */
  205. void removeEntry(in AUTF8String aZipEntry, in boolean aQueue);
  206. /**
  207. * Processes all queued items until complete or some error occurs. The
  208. * observer will be notified when the first operation starts and when the
  209. * last operation completes. Any failures will be passed to the observer.
  210. * The zip writer will be busy until the queue is complete or some error
  211. * halted processing of the queue early. In the event of an early failure,
  212. * remaining items will stay in the queue and calling processQueue will
  213. * continue.
  214. *
  215. * @throws NS_ERROR_NOT_INITIALIZED if no zip file has been opened
  216. * @throws NS_ERROR_IN_PROGRESS if the queue is already in progress
  217. */
  218. void processQueue(in nsIRequestObserver aObserver, in nsISupports aContext);
  219. /**
  220. * Closes the zip file.
  221. *
  222. * @throws NS_ERROR_NOT_INITIALIZED if no zip file has been opened
  223. * @throws NS_ERROR_IN_PROGRESS if another operation is currently in progress
  224. * @throws <other-error> on failure to complete the zip file
  225. */
  226. void close();
  227. };