OpenShot Library | OpenShotAudio  0.2.1
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  /** Platform specific data. Depending on how the zip file was created this
91  may contain macOS and Linux file types, permissions and
92  setuid/setgid/sticky bits.
93  */
95  };
96 
97  //==============================================================================
98  /** Returns the number of items in the zip file. */
99  int getNumEntries() const noexcept;
100 
101  /** Returns a structure that describes one of the entries in the zip file.
102  This may return a nullptr if the index is out of range.
103  @see ZipFile::ZipEntry
104  */
105  const ZipEntry* getEntry (int index) const noexcept;
106 
107  /** Returns the index of the first entry with a given filename.
108  This uses a case-sensitive comparison to look for a filename in the
109  list of entries. It might return -1 if no match is found.
110 
111  @see ZipFile::ZipEntry
112  */
113  int getIndexOfFileName (const String& fileName, bool ignoreCase = false) const noexcept;
114 
115  /** Returns a structure that describes one of the entries in the zip file.
116 
117  This uses a case-sensitive comparison to look for a filename in the
118  list of entries. It might return 0 if no match is found.
119 
120  @see ZipFile::ZipEntry
121  */
122  const ZipEntry* getEntry (const String& fileName, bool ignoreCase = false) const noexcept;
123 
124  /** Sorts the list of entries, based on the filename. */
125  void sortEntriesByFilename();
126 
127  //==============================================================================
128  /** Creates a stream that can read from one of the zip file's entries.
129 
130  The stream that is returned must be deleted by the caller (and
131  a nullptr might be returned if a stream can't be opened for some reason).
132 
133  The stream must not be used after the ZipFile object that created
134  has been deleted.
135 
136  Note that if the ZipFile was created with a user-supplied InputStream object,
137  then all the streams which are created by this method will by trying to share
138  the same source stream, so cannot be safely used on multiple threads! (But if
139  you create the ZipFile from a File or InputSource, then it is safe to do this).
140  */
141  InputStream* createStreamForEntry (int index);
142 
143  /** Creates a stream that can read from one of the zip file's entries.
144 
145  The stream that is returned must be deleted by the caller (and
146  a nullptr might be returned if a stream can't be opened for some reason).
147 
148  The stream must not be used after the ZipFile object that created
149  has been deleted.
150 
151  Note that if the ZipFile was created with a user-supplied InputStream object,
152  then all the streams which are created by this method will by trying to share
153  the same source stream, so cannot be safely used on multiple threads! (But if
154  you create the ZipFile from a File or InputSource, then it is safe to do this).
155  */
156  InputStream* createStreamForEntry (const ZipEntry& entry);
157 
158  //==============================================================================
159  /** Uncompresses all of the files in the zip file.
160 
161  This will expand all the entries into a target directory. The relative
162  paths of the entries are used.
163 
164  @param targetDirectory the root folder to uncompress to
165  @param shouldOverwriteFiles whether to overwrite existing files with similarly-named ones
166  @returns success if the file is successfully unzipped
167  */
168  Result uncompressTo (const File& targetDirectory,
169  bool shouldOverwriteFiles = true);
170 
171  /** Uncompresses one of the entries from the zip file.
172 
173  This will expand the entry and write it in a target directory. The entry's path is used to
174  determine which subfolder of the target should contain the new file.
175 
176  @param index the index of the entry to uncompress - this must be a valid index
177  between 0 and (getNumEntries() - 1).
178  @param targetDirectory the root folder to uncompress into
179  @param shouldOverwriteFiles whether to overwrite existing files with similarly-named ones
180  @returns success if all the files are successfully unzipped
181  */
182  Result uncompressEntry (int index,
183  const File& targetDirectory,
184  bool shouldOverwriteFiles = true);
185 
186 
187  //==============================================================================
188  /** Used to create a new zip file.
189 
190  Create a ZipFile::Builder object, and call its addFile() method to add some files,
191  then you can write it to a stream with write().
192  */
194  {
195  public:
196  /** Creates an empty builder object. */
197  Builder();
198 
199  /** Destructor. */
200  ~Builder();
201 
202  /** Adds a file to the list of items which will be added to the archive.
203  The file isn't read immediately: the files will be read later when the writeToStream()
204  method is called.
205 
206  The compressionLevel can be between 0 (no compression), and 9 (maximum compression).
207  If the storedPathName parameter is specified, you can customise the partial pathname that
208  will be stored for this file.
209  */
210  void addFile (const File& fileToAdd, int compressionLevel,
211  const String& storedPathName = String());
212 
213  /** Adds a stream to the list of items which will be added to the archive.
214 
215  @param streamToRead this stream isn't read immediately - a pointer to the stream is
216  stored, then used later when the writeToStream() method is called, and
217  deleted by the Builder object when no longer needed, so be very careful
218  about its lifetime and the lifetime of any objects on which it depends!
219  This must not be null.
220  @param compressionLevel this can be between 0 (no compression), and 9 (maximum compression).
221  @param storedPathName the partial pathname that will be stored for this file
222  @param fileModificationTime the timestamp that will be stored as the last modification time
223  of this entry
224  */
225  void addEntry (InputStream* streamToRead, int compressionLevel,
226  const String& storedPathName, Time fileModificationTime);
227 
228  /** Generates the zip file, writing it to the specified stream.
229  If the progress parameter is non-null, it will be updated with an approximate
230  progress status between 0 and 1.0
231  */
232  bool writeToStream (OutputStream& target, double* progress) const;
233 
234  //==============================================================================
235  private:
236  struct Item;
237  OwnedArray<Item> items;
238 
239  JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (Builder)
240  };
241 
242 private:
243  //==============================================================================
244  struct ZipInputStream;
245  struct ZipEntryHolder;
246 
248  CriticalSection lock;
249  InputStream* inputStream = nullptr;
250  std::unique_ptr<InputStream> streamToDelete;
251  std::unique_ptr<InputSource> inputSource;
252 
253  #if JUCE_DEBUG
254  struct OpenStreamCounter
255  {
256  OpenStreamCounter() = default;
257  ~OpenStreamCounter();
258 
259  int numOpenStreams = 0;
260  };
261 
262  OpenStreamCounter streamCounter;
263  #endif
264 
265  void init();
266 
267  JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (ZipFile)
268 };
269 
270 } // namespace juce
271 
272 /** @}*/
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:193
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.
uint32 externalFileAttributes
Platform specific data.
Definition: juce_ZipFile.h:94
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