OpenShot Library | libopenshot-audio  0.1.9
juce_ZipFile.h
1 
2 /** @weakgroup juce_core-zip
3  * @{
4  */
5 /*
6  ==============================================================================
7 
8  This file is part of the JUCE library.
9  Copyright (c) 2017 - ROLI Ltd.
10 
11  JUCE is an open source library subject to commercial or open-source
12  licensing.
13 
14  The code included in this file is provided under the terms of the ISC license
15  http://www.isc.org/downloads/software-support-policy/isc-license. Permission
16  To use, copy, modify, and/or distribute this software for any purpose with or
17  without fee is hereby granted provided that the above copyright notice and
18  this permission notice appear in all copies.
19 
20  JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
21  EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
22  DISCLAIMED.
23 
24  ==============================================================================
25 */
26 
27 namespace juce
28 {
29 
30 //==============================================================================
31 /**
32  Decodes a ZIP file from a stream.
33 
34  This can enumerate the items in a ZIP file and can create suitable stream objects
35  to read each one.
36 
37  @tags{Core}
38 */
40 {
41 public:
42  /** Creates a ZipFile to read a specific file. */
43  explicit ZipFile (const File& file);
44 
45  //==============================================================================
46  /** Creates a ZipFile for a given stream.
47 
48  @param inputStream the stream to read from
49  @param deleteStreamWhenDestroyed if set to true, the object passed-in
50  will be deleted when this ZipFile object is deleted
51  */
52  ZipFile (InputStream* inputStream, bool deleteStreamWhenDestroyed);
53 
54  /** Creates a ZipFile for a given stream.
55  The stream will not be owned or deleted by this class - if you want the ZipFile to
56  manage the stream's lifetime, use the other constructor.
57  */
58  explicit ZipFile (InputStream& inputStream);
59 
60  /** Creates a ZipFile for an input source.
61 
62  The inputSource object will be owned by the zip file, which will delete
63  it later when not needed.
64  */
65  explicit ZipFile (InputSource* inputSource);
66 
67  /** Destructor. */
68  ~ZipFile();
69 
70  //==============================================================================
71  /**
72  Contains information about one of the entries in a ZipFile.
73 
74  @see ZipFile::getEntry
75  */
76  struct ZipEntry
77  {
78  /** The name of the file, which may also include a partial pathname. */
80 
81  /** The file's original size. */
83 
84  /** The last time the file was modified. */
86 
87  /** True if the zip entry is a symbolic link. */
89  };
90 
91  //==============================================================================
92  /** Returns the number of items in the zip file. */
93  int getNumEntries() const noexcept;
94 
95  /** Returns a structure that describes one of the entries in the zip file.
96  This may return a nullptr if the index is out of range.
97  @see ZipFile::ZipEntry
98  */
99  const ZipEntry* getEntry (int index) const noexcept;
100 
101  /** Returns the index of the first entry with a given filename.
102  This uses a case-sensitive comparison to look for a filename in the
103  list of entries. It might return -1 if no match is found.
104 
105  @see ZipFile::ZipEntry
106  */
107  int getIndexOfFileName (const String& fileName, bool ignoreCase = false) const noexcept;
108 
109  /** Returns a structure that describes one of the entries in the zip file.
110 
111  This uses a case-sensitive comparison to look for a filename in the
112  list of entries. It might return 0 if no match is found.
113 
114  @see ZipFile::ZipEntry
115  */
116  const ZipEntry* getEntry (const String& fileName, bool ignoreCase = false) const noexcept;
117 
118  /** Sorts the list of entries, based on the filename. */
119  void sortEntriesByFilename();
120 
121  //==============================================================================
122  /** Creates a stream that can read from one of the zip file's entries.
123 
124  The stream that is returned must be deleted by the caller (and
125  a nullptr might be returned if a stream can't be opened for some reason).
126 
127  The stream must not be used after the ZipFile object that created
128  has been deleted.
129 
130  Note that if the ZipFile was created with a user-supplied InputStream object,
131  then all the streams which are created by this method will by trying to share
132  the same source stream, so cannot be safely used on multiple threads! (But if
133  you create the ZipFile from a File or InputSource, then it is safe to do this).
134  */
135  InputStream* createStreamForEntry (int index);
136 
137  /** Creates a stream that can read from one of the zip file's entries.
138 
139  The stream that is returned must be deleted by the caller (and
140  a nullptr might be returned if a stream can't be opened for some reason).
141 
142  The stream must not be used after the ZipFile object that created
143  has been deleted.
144 
145  Note that if the ZipFile was created with a user-supplied InputStream object,
146  then all the streams which are created by this method will by trying to share
147  the same source stream, so cannot be safely used on multiple threads! (But if
148  you create the ZipFile from a File or InputSource, then it is safe to do this).
149  */
150  InputStream* createStreamForEntry (const ZipEntry& entry);
151 
152  //==============================================================================
153  /** Uncompresses all of the files in the zip file.
154 
155  This will expand all the entries into a target directory. The relative
156  paths of the entries are used.
157 
158  @param targetDirectory the root folder to uncompress to
159  @param shouldOverwriteFiles whether to overwrite existing files with similarly-named ones
160  @returns success if the file is successfully unzipped
161  */
162  Result uncompressTo (const File& targetDirectory,
163  bool shouldOverwriteFiles = true);
164 
165  /** Uncompresses one of the entries from the zip file.
166 
167  This will expand the entry and write it in a target directory. The entry's path is used to
168  determine which subfolder of the target should contain the new file.
169 
170  @param index the index of the entry to uncompress - this must be a valid index
171  between 0 and (getNumEntries() - 1).
172  @param targetDirectory the root folder to uncompress into
173  @param shouldOverwriteFiles whether to overwrite existing files with similarly-named ones
174  @returns success if all the files are successfully unzipped
175  */
176  Result uncompressEntry (int index,
177  const File& targetDirectory,
178  bool shouldOverwriteFiles = true);
179 
180 
181  //==============================================================================
182  /** Used to create a new zip file.
183 
184  Create a ZipFile::Builder object, and call its addFile() method to add some files,
185  then you can write it to a stream with write().
186  */
188  {
189  public:
190  /** Creates an empty builder object. */
191  Builder();
192 
193  /** Destructor. */
194  ~Builder();
195 
196  /** Adds a file to the list of items which will be added to the archive.
197  The file isn't read immediately: the files will be read later when the writeToStream()
198  method is called.
199 
200  The compressionLevel can be between 0 (no compression), and 9 (maximum compression).
201  If the storedPathName parameter is specified, you can customise the partial pathname that
202  will be stored for this file.
203  */
204  void addFile (const File& fileToAdd, int compressionLevel,
205  const String& storedPathName = String());
206 
207  /** Adds a stream to the list of items which will be added to the archive.
208 
209  @param streamToRead this stream isn't read immediately - a pointer to the stream is
210  stored, then used later when the writeToStream() method is called, and
211  deleted by the Builder object when no longer needed, so be very careful
212  about its lifetime and the lifetime of any objects on which it depends!
213  This must not be null.
214  @param compressionLevel this can be between 0 (no compression), and 9 (maximum compression).
215  @param storedPathName the partial pathname that will be stored for this file
216  @param fileModificationTime the timestamp that will be stored as the last modification time
217  of this entry
218  */
219  void addEntry (InputStream* streamToRead, int compressionLevel,
220  const String& storedPathName, Time fileModificationTime);
221 
222  /** Generates the zip file, writing it to the specified stream.
223  If the progress parameter is non-null, it will be updated with an approximate
224  progress status between 0 and 1.0
225  */
226  bool writeToStream (OutputStream& target, double* progress) const;
227 
228  //==============================================================================
229  private:
230  struct Item;
231  OwnedArray<Item> items;
232 
233  JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (Builder)
234  };
235 
236 private:
237  //==============================================================================
238  struct ZipInputStream;
239  struct ZipEntryHolder;
240 
242  CriticalSection lock;
243  InputStream* inputStream = nullptr;
244  std::unique_ptr<InputStream> streamToDelete;
245  std::unique_ptr<InputSource> inputSource;
246 
247  #if JUCE_DEBUG
248  struct OpenStreamCounter
249  {
250  OpenStreamCounter() = default;
251  ~OpenStreamCounter();
252 
253  int numOpenStreams = 0;
254  };
255 
256  OpenStreamCounter streamCounter;
257  #endif
258 
259  void init();
260 
261  JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (ZipFile)
262 };
263 
264 } // namespace juce
265 
266 /** @}*/
bool isSymbolicLink
True if the zip entry is a symbolic link.
Definition: juce_ZipFile.h:88
#define JUCE_API
This macro is added to all JUCE public class declarations.
Used to create a new zip file.
Definition: juce_ZipFile.h:187
Contains information about one of the entries in a ZipFile.
Definition: juce_ZipFile.h:76
The base class for streams that read data.
String filename
The name of the file, which may also include a partial pathname.
Definition: juce_ZipFile.h:79
int64 uncompressedSize
The file&#39;s original size.
Definition: juce_ZipFile.h:82
The JUCE String class!
Definition: juce_String.h:42
Time fileTime
The last time the file was modified.
Definition: juce_ZipFile.h:85
Represents the &#39;success&#39; or &#39;failure&#39; of an operation, and holds an associated error message to descr...
Definition: juce_Result.h:60
Represents a local file or directory.
Definition: juce_File.h:44
The base class for streams that write data to some kind of destination.
A re-entrant mutex.
Decodes a ZIP file from a stream.
Definition: juce_ZipFile.h:39
An array designed for holding objects.
A lightweight object that can create a stream to read some kind of resource.
Holds an absolute date and time.
Definition: juce_Time.h:40