OpenShot Library | OpenShotAudio 0.2.2
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
27namespace 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{
41public:
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
242private:
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/** @}*/
A re-entrant mutex.
Represents a local file or directory.
Definition: juce_File.h:45
A lightweight object that can create a stream to read some kind of resource.
The base class for streams that read data.
The base class for streams that write data to some kind of destination.
An array designed for holding objects.
Represents the 'success' or 'failure' of an operation, and holds an associated error message to descr...
Definition: juce_Result.h:61
The JUCE String class!
Definition: juce_String.h:43
Holds an absolute date and time.
Definition: juce_Time.h:41
Used to create a new zip file.
Definition: juce_ZipFile.h:194
Decodes a ZIP file from a stream.
Definition: juce_ZipFile.h:40
#define JUCE_API
This macro is added to all JUCE public class declarations.
String filename
The name of the file, which may also include a partial pathname.
Definition: juce_ZipFile.h:79
int64 uncompressedSize
The file's original size.
Definition: juce_ZipFile.h:82
uint32 externalFileAttributes
Platform specific data.
Definition: juce_ZipFile.h:94
bool isSymbolicLink
True if the zip entry is a symbolic link.
Definition: juce_ZipFile.h:88
Time fileTime
The last time the file was modified.
Definition: juce_ZipFile.h:85
Contains information about one of the entries in a ZipFile.
Definition: juce_ZipFile.h:77