NCBI C++ ToolKit
archive_zip.hpp
Go to the documentation of this file.

Go to the SVN repository for this file.

1 #ifndef UTIL_COMPRESS__ARCHIVE_ZIP__HPP
2 #define UTIL_COMPRESS__ARCHIVE_ZIP__HPP
3 
4 /* $Id: archive_zip.hpp 94317 2021-07-20 16:45:02Z ivanov $
5  * ===========================================================================
6  *
7  * PUBLIC DOMAIN NOTICE
8  * National Center for Biotechnology Information
9  *
10  * This software/database is a "United States Government Work" under the
11  * terms of the United States Copyright Act. It was written as part of
12  * the author's official duties as a United States Government employee and
13  * thus cannot be copyrighted. This software/database is freely available
14  * to the public for use. The National Library of Medicine and the U.S.
15  * Government have not placed any restriction on its use or reproduction.
16  *
17  * Although all reasonable efforts have been taken to ensure the accuracy
18  * and reliability of the software and data, the NLM and the U.S.
19  * Government do not and cannot warrant the performance or results that
20  * may be obtained by using this software or data. The NLM and the U.S.
21  * Government disclaim all warranties, express or implied, including
22  * warranties of performance, merchantability or fitness for any particular
23  * purpose.
24  *
25  * Please cite the author in any work or product based on this material.
26  *
27  * ===========================================================================
28  *
29  * Authors: Vladimir Ivanov
30  *
31  * File Description:
32  * Compression archive API - ZIP file support.
33  *
34  * Implementation based on this fork of 'miniz' library:
35  * https://github.com/uroni/miniz
36  * It have support for ZIP64 format, can handle archive files > 4GB in size,
37  * and the number of files in the archive is not limited to 65535.
38  *
39  */
40 
41 /// @file archive_.hpp
42 /// Archive API.
43 
45 
46 
47 /** @addtogroup Compression
48  *
49  * @{
50  */
51 
52 
54 
55 
56 // Forward declaration of ZIP archive handle.
57 struct SZipHandle;
58 
59 
60 /////////////////////////////////////////////////////////////////////////////
61 ///
62 /// CArchiveZip -- implementation of IArchive interface for ZIP-archives
63 ///
64 /// Throws exceptions on errors.
65 
67 {
68 public:
69  /// Constructor
70  CArchiveZip(void) : m_Handle(NULL) {}
71  /// Destructor
72  virtual ~CArchiveZip(void);
73 
74  /// Create new archive file.
75  ///
76  /// @param filename
77  /// File name of the archive to create.
78  /// @note
79  /// File can be overwritten if exists.
80  /// @sa
81  /// CreateMemory, AddEntryFromFile, AddEntryFromMemory
82  virtual void CreateFile(const string& filename);
83 
84  /// Create new archive file on top of a FILE stream.
85  ///
86  /// @param filestream
87  /// File stream that can be used for archive operations.
88  /// @note
89  /// File stream should be opened with necessary flags to allow read/write,
90  /// depending on performing archive operations.
91  /// @note
92  /// The file stream will not be closed after closing archive with Close() .
93  /// @sa
94  /// CreateFile, CreateMemory, AddEntryFromFile, AddEntryFromMemory
95  virtual void CreateFileStream(FILE* filestream);
96 
97  /// Create new archive located in memory.
98  ///
99  /// @param initial_allocation_size
100  /// Estimated size of the archive, if known.
101  /// Bigger size allow to avoid extra memory reallocations.
102  /// @sa
103  /// FinalizeMemory, AddEntryFromFile, AddEntryFromMemory
104  virtual void CreateMemory(size_t initial_allocation_size = 0);
105 
106  /// Open archive file for reading.
107  ///
108  /// @param filename
109  /// File name of the existing archive to open.
110  /// @sa
111  /// CreateFile, OpenMemory, ExtractEntryToFileSystem, ExtractEntryToMemory
112  virtual void OpenFile(const string& filename);
113 
114  /// Open archive from a FILE stream, beginning at the current file position.
115  ///
116  /// @param filestream
117  /// File stream that can be used for archive operations.
118  /// @param archive_size
119  /// The archive is assumed to be 'archive_size' bytes long. If it is 0,
120  /// then the entire rest of the file is assumed to contain the archive.
121  /// @note
122  /// File stream should be opened with necessary flags to allow read/write,
123  /// depending on performing archive operations.
124  /// @note
125  /// The file stream will not be closed after closing archive with Close() .
126  /// @sa
127  /// CreateFileStream, CreateFile, OpenFile, AddEntryFromFile, AddEntryFromMemory
128  virtual void OpenFileStream(FILE* filestream, Uint8 archive_size = 0);
129 
130  /// Open archive located in memory for reading.
131  /// @param buf
132  /// Pointer to an archive located in memory. Used only to open already
133  /// existed archive for reading.
134  /// @param size
135  /// Size of the archive.
136  /// @sa
137  /// CreateMemory, OpenFile, ExtractEntryToFileSystem, ExtractEntryToMemory
138  virtual void OpenMemory(const void* buf, size_t size);
139 
140  /// Close the archive.
141  ///
142  /// For file-based archives it flushes all pending output.
143  /// All added entries will appears in the archive only after this call.
144  /// This method will be automatically called from destructor
145  /// if you forgot to call it directly. But note, that if the archive
146  /// is created in memory, it will be lost. You should call
147  /// FinalizeMemory() to get data before closing archive.
148  /// @sa
149  /// FinalizeMemory, OpenFile, OpenMemory
150  virtual void Close(void);
151 
152  /// Finalize the archive created in memory.
153  ///
154  /// Return pointer to buffer with created archive and its size.
155  /// The only valid operation after this call is Close().
156  /// @param buf
157  /// Pointer to an archive located in memory.
158  /// @param size
159  /// Size of the newly created archive.
160  /// @note
161  /// Do not forget to deallocate memory buffer after usage.
162  /// @sa
163  /// CreateMemory, Close
164  virtual void FinalizeMemory(void** buf, size_t* size);
165 
166  /// Returns the total number of entries in the archive.
167  virtual size_t GetNumEntries(void);
168 
169  /// Get detailed information about an archive entry by index.
170  ///
171  /// @param index
172  /// Zero-based index of entry in the archive.
173  /// @param info
174  /// Pointer to entry information structure that will be filled with
175  /// information about entry with specified index.
176  /// @note
177  /// Note that the archive can contain multiple versions of the same entry
178  /// (in case if an update was done on it), all of which but the last one
179  /// are to be ignored.
180  /// @sa
181  /// CArchiveEntryInfo
182  virtual void GetEntryInfo(size_t index, CArchiveEntryInfo* info);
183 
184  /// Check that current archive format have support for specific feature.
185  /// @sa CArchive
186  virtual bool HaveSupport_Type(CDirEntry::EType type);
187  virtual bool HaveSupport_AbsolutePath(void) { return false; };
188  virtual bool HaveSupport_FileStream(void) { return true; };
189 
190  /// Extracts an archive entry to file system.
191  ///
192  /// @param info
193  /// Entry to extract.
194  /// @param dst_path
195  /// Destination path for extracted entry.
196  /// @note
197  /// This method do not set last accessed and modified times.
198  /// See CArchive.
199  /// @sa
200  /// ExtractEntryToMemory, ExtractEntryToCallback, CArchiveEntryInfo::GetSize
201  virtual void ExtractEntryToFileSystem(const CArchiveEntryInfo& info,
202  const string& dst_path);
203 
204  /// Extracts an archive file to a memory buffer.
205  ///
206  /// Do nothing for entries of other types.
207  /// @param info
208  /// Entry to extract.
209  /// @param buf
210  /// Memory buffer for extracted data.
211  /// @param size
212  /// Size of memory buffer.
213  /// Note, that the buffer size should be big enough to fit whole extracted file.
214  /// @sa
215  /// ExtractEntryToFileSystem, ExtractEntryToCallback, CArchiveEntryInfo::GetSize
216  virtual void ExtractEntryToMemory(const CArchiveEntryInfo& info,
217  void* buf, size_t size);
218 
219  /// Extracts an archive file using user-defined callback to process extracted data.
220  ///
221  /// Do nothing for entries of other types.
222  /// @param info
223  /// Entry to extract.
224  /// @param callback
225  /// User callback for processing extracted data on the fly.
226  /// @sa
227  /// ExtractEntryToFileSystem, ExtractEntryToMemory, CArchiveEntryInfo::GetSize
228  virtual void ExtractEntryToCallback(const CArchiveEntryInfo& info,
229  Callback_Write callback);
230 
231  /// Verify entry integrity.
232  ///
233  /// @param info
234  /// Entry to verify.
235  virtual void TestEntry(const CArchiveEntryInfo& info);
236 
237  /// Don't need to be implemented for ZIP format.
238  virtual void SkipEntry(const CArchiveEntryInfo& /*info*/) {};
239 
240  /// Add single entry to newly created archive from file system.
241  ///
242  /// @param info
243  /// Entry information to add. It should have name and type of adding entry at least.
244  /// If added entry is a directory, just add an information about it to archive.
245  /// CArchive process all directories recursively.
246  /// @param src_path
247  /// Path to file system object to add.
248  /// @param level
249  /// Compression level used to compress file .
250  /// @sa
251  /// CreateFile, CreateMemory, AddEntryFromMemory
252  virtual void AddEntryFromFileSystem(const CArchiveEntryInfo& info,
253  const string& src_path, ELevel level);
254 
255  /// Add entry to newly created archive from memory buffer.
256  ///
257  /// @param info
258  /// Entry information to add. It should have name and type of adding entry at least.
259  /// @param buf
260  /// Memory buffer with data to add.
261  /// @param size
262  /// Size of data in memory buffer.
263  /// @param level
264  /// Compression level for added data.
265  /// @sa
266  /// CreateFile, CreateMemory, AddEntryFromFileSystem
267  virtual void AddEntryFromMemory(const CArchiveEntryInfo& info,
268  void* buf, size_t size, ELevel level);
269 
270 protected:
271  SZipHandle* m_Handle; ///< Archive handle
272 };
273 
274 
276 
277 
278 /* @} */
279 
280 #endif /* UTIL_COMPRESS__ARCHIVE_ZIP__HPP */
Archive API.
CArchiveEntryInfo class.
Definition: archive_.hpp:112
CArchiveZip – implementation of IArchive interface for ZIP-archives.
Definition: archive_zip.hpp:67
IArchive – abstract interface class for archive formats.
Definition: archive_.hpp:186
#define NULL
Definition: ncbistd.hpp:225
virtual void Close(void)=0
Close the archive.
SZipHandle * m_Handle
Archive handle.
virtual void ExtractEntryToFileSystem(const CArchiveEntryInfo &info, const string &dst_path)=0
Extracts an archive entry to file system.
virtual void TestEntry(const CArchiveEntryInfo &info)=0
Verify entry integrity.
virtual bool HaveSupport_FileStream(void)
CArchiveZip(void)
Constructor.
Definition: archive_zip.hpp:70
virtual void OpenFileStream(FILE *filestream, Uint8 archive_size=0)=0
Open archive from a FILE stream, beginning at the current file position.
virtual void AddEntryFromFileSystem(const CArchiveEntryInfo &info, const string &src_path, ELevel level)=0
Add single entry to newly created archive from file system.
virtual void SkipEntry(const CArchiveEntryInfo &)
Don't need to be implemented for ZIP format.
virtual void GetEntryInfo(size_t index, CArchiveEntryInfo *info)=0
Get detailed information about an archive entry by index.
virtual void ExtractEntryToCallback(const CArchiveEntryInfo &info, Callback_Write callback)=0
Extracts an archive file using user-defined callback to process extracted data.
virtual void CreateMemory(size_t initial_allocation_size=0)=0
Create new archive located in memory.
virtual bool HaveSupport_AbsolutePath(void)
virtual void CreateFile(const string &filename)=0
Create new archive file.
virtual size_t GetNumEntries(void)=0
Returns the total number of entries in the archive.
virtual void OpenMemory(const void *buf, size_t size)=0
Open archive located in memory for reading.
virtual void AddEntryFromMemory(const CArchiveEntryInfo &info, void *buf, size_t size, ELevel level)=0
Add entry to newly created archive from memory buffer.
virtual void OpenFile(const string &filename)=0
Open archive file for reading.
virtual void FinalizeMemory(void **buf, size_t *size)=0
Finalize the archive created in memory.
virtual bool HaveSupport_Type(CDirEntry::EType type)=0
Check that current archive format have support for specific feature.
virtual void ExtractEntryToMemory(const CArchiveEntryInfo &info, void *buf, size_t size)=0
Extracts an archive file to a memory buffer.
virtual void CreateFileStream(FILE *filestream)=0
Create new archive file on top of a FILE stream.
EType
Directory entry type.
Definition: ncbifile.hpp:782
uint64_t Uint8
8-byte (64-bit) unsigned integer
Definition: ncbitype.h:105
#define END_NCBI_SCOPE
End previously defined NCBI scope.
Definition: ncbistl.hpp:103
#define BEGIN_NCBI_SCOPE
Define ncbi namespace.
Definition: ncbistl.hpp:100
char * buf
static MDB_envinfo info
Definition: mdb_load.c:37
const struct ncbi::grid::netcache::search::fields::SIZE size
NCBI_XUTIL_EXPORT
Parameter to control printing diagnostic message about conversion of static array data from a differe...
Definition: static_set.hpp:72
ZIP archive handle type definition.
Definition: archive_zip.cpp:79
Definition: type.c:6
Modified on Sat May 25 14:18:44 2024 by modify_doxy.py rev. 669887