VirtualBox

source: vbox/trunk/include/iprt/zip.h@ 68716

Last change on this file since 68716 was 67253, checked in by vboxsync, 8 years ago

IPRT/tarvfswriter.cpp: Added RTZipTarFsStreamSetOwner, RTZipTarFsStreamSetGroup, RTZipTarFsStreamSetPrefix, RTZipTarFsStreamSetFileMode, RTZipTarFsStreamSetDirMode, and RTZipTarFsStreamSetModTime for overriding attributes in the output archive.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 15.7 KB
Line 
1/** @file
2 * IPRT - Compression.
3 */
4
5/*
6 * Copyright (C) 2006-2016 Oracle Corporation
7 *
8 * This file is part of VirtualBox Open Source Edition (OSE), as
9 * available from http://www.virtualbox.org. This file is free software;
10 * you can redistribute it and/or modify it under the terms of the GNU
11 * General Public License (GPL) as published by the Free Software
12 * Foundation, in version 2 as it comes in the "COPYING" file of the
13 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15 *
16 * The contents of this file may alternatively be used under the terms
17 * of the Common Development and Distribution License Version 1.0
18 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19 * VirtualBox OSE distribution, in which case the provisions of the
20 * CDDL are applicable instead of those of the GPL.
21 *
22 * You may elect to license modified versions of this file under the
23 * terms and conditions of either the GPL or the CDDL or both.
24 */
25
26#ifndef ___iprt_zip_h
27#define ___iprt_zip_h
28
29#include <iprt/cdefs.h>
30#include <iprt/types.h>
31
32RT_C_DECLS_BEGIN
33
34/** @defgroup grp_rt_zip RTZip - Compression
35 * @ingroup grp_rt
36 * @{
37 */
38
39
40
41/**
42 * Callback function for consuming compressed data during compression.
43 *
44 * @returns iprt status code.
45 * @param pvUser User argument.
46 * @param pvBuf Compressed data.
47 * @param cbBuf Size of the compressed data.
48 */
49typedef DECLCALLBACK(int) FNRTZIPOUT(void *pvUser, const void *pvBuf, size_t cbBuf);
50/** Pointer to FNRTZIPOUT() function. */
51typedef FNRTZIPOUT *PFNRTZIPOUT;
52
53/**
54 * Callback function for supplying compressed data during decompression.
55 *
56 * @returns iprt status code.
57 * @param pvUser User argument.
58 * @param pvBuf Where to store the compressed data.
59 * @param cbBuf Size of the buffer.
60 * @param pcbBuf Number of bytes actually stored in the buffer.
61 */
62typedef DECLCALLBACK(int) FNRTZIPIN(void *pvUser, void *pvBuf, size_t cbBuf, size_t *pcbBuf);
63/** Pointer to FNRTZIPIN() function. */
64typedef FNRTZIPIN *PFNRTZIPIN;
65
66/**
67 * Compression type.
68 * (Be careful with these they are stored in files!)
69 */
70typedef enum RTZIPTYPE
71{
72 /** Invalid. */
73 RTZIPTYPE_INVALID = 0,
74 /** Choose best fitting one. */
75 RTZIPTYPE_AUTO,
76 /** Store the data. */
77 RTZIPTYPE_STORE,
78 /** Zlib compression the data. */
79 RTZIPTYPE_ZLIB,
80 /** BZlib compress. */
81 RTZIPTYPE_BZLIB,
82 /** libLZF compress. */
83 RTZIPTYPE_LZF,
84 /** Lempel-Ziv-Jeff-Bonwick compression. */
85 RTZIPTYPE_LZJB,
86 /** Lempel-Ziv-Oberhumer compression. */
87 RTZIPTYPE_LZO,
88 /* Zlib compression the data without zlib header. */
89 RTZIPTYPE_ZLIB_NO_HEADER,
90 /** End of valid the valid compression types. */
91 RTZIPTYPE_END
92} RTZIPTYPE;
93
94/**
95 * Compression level.
96 */
97typedef enum RTZIPLEVEL
98{
99 /** Store, don't compress. */
100 RTZIPLEVEL_STORE = 0,
101 /** Fast compression. */
102 RTZIPLEVEL_FAST,
103 /** Default compression. */
104 RTZIPLEVEL_DEFAULT,
105 /** Maximal compression. */
106 RTZIPLEVEL_MAX
107} RTZIPLEVEL;
108
109
110/**
111 * Create a stream compressor instance.
112 *
113 * @returns iprt status code.
114 * @param ppZip Where to store the instance handle.
115 * @param pvUser User argument which will be passed on to pfnOut and pfnIn.
116 * @param pfnOut Callback for consuming output of compression.
117 * @param enmType Type of compressor to create.
118 * @param enmLevel Compression level.
119 */
120RTDECL(int) RTZipCompCreate(PRTZIPCOMP *ppZip, void *pvUser, PFNRTZIPOUT pfnOut, RTZIPTYPE enmType, RTZIPLEVEL enmLevel);
121
122/**
123 * Compresses a chunk of memory.
124 *
125 * @returns iprt status code.
126 * @param pZip The compressor instance.
127 * @param pvBuf Pointer to buffer containing the bits to compress.
128 * @param cbBuf Number of bytes to compress.
129 */
130RTDECL(int) RTZipCompress(PRTZIPCOMP pZip, const void *pvBuf, size_t cbBuf);
131
132/**
133 * Finishes the compression.
134 * This will flush all data and terminate the compression data stream.
135 *
136 * @returns iprt status code.
137 * @param pZip The stream compressor instance.
138 */
139RTDECL(int) RTZipCompFinish(PRTZIPCOMP pZip);
140
141/**
142 * Destroys the stream compressor instance.
143 *
144 * @returns iprt status code.
145 * @param pZip The compressor instance.
146 */
147RTDECL(int) RTZipCompDestroy(PRTZIPCOMP pZip);
148
149
150/**
151 * Create a stream decompressor instance.
152 *
153 * @returns iprt status code.
154 * @param ppZip Where to store the instance handle.
155 * @param pvUser User argument which will be passed on to pfnOut and pfnIn.
156 * @param pfnIn Callback for producing input for decompression.
157 */
158RTDECL(int) RTZipDecompCreate(PRTZIPDECOMP *ppZip, void *pvUser, PFNRTZIPIN pfnIn);
159
160/**
161 * Decompresses a chunk of memory.
162 *
163 * @returns iprt status code.
164 * @param pZip The stream decompressor instance.
165 * @param pvBuf Where to store the decompressed data.
166 * @param cbBuf Number of bytes to produce. If pcbWritten is set
167 * any number of bytes up to cbBuf might be returned.
168 * @param pcbWritten Number of bytes actually written to the buffer. If NULL
169 * cbBuf number of bytes must be written.
170 */
171RTDECL(int) RTZipDecompress(PRTZIPDECOMP pZip, void *pvBuf, size_t cbBuf, size_t *pcbWritten);
172
173/**
174 * Destroys the stream decompressor instance.
175 *
176 * @returns iprt status code.
177 * @param pZip The decompressor instance.
178 */
179RTDECL(int) RTZipDecompDestroy(PRTZIPDECOMP pZip);
180
181
182/**
183 * Compress a chunk of memory into a block.
184 *
185 * @returns IPRT status code.
186 *
187 * @param enmType The compression type.
188 * @param enmLevel The compression level.
189 * @param fFlags Flags reserved for future extensions, MBZ.
190 * @param pvSrc Pointer to the input block.
191 * @param cbSrc Size of the input block.
192 * @param pvDst Pointer to the output buffer.
193 * @param cbDst The size of the output buffer.
194 * @param pcbDstActual Where to return the compressed size.
195 */
196RTDECL(int) RTZipBlockCompress(RTZIPTYPE enmType, RTZIPLEVEL enmLevel, uint32_t fFlags,
197 void const *pvSrc, size_t cbSrc,
198 void *pvDst, size_t cbDst, size_t *pcbDstActual) RT_NO_THROW_PROTO;
199
200
201/**
202 * Decompress a block.
203 *
204 * @returns IPRT status code.
205 *
206 * @param enmType The compression type.
207 * @param fFlags Flags reserved for future extensions, MBZ.
208 * @param pvSrc Pointer to the input block.
209 * @param cbSrc Size of the input block.
210 * @param pcbSrcActual Where to return the compressed size.
211 * @param pvDst Pointer to the output buffer.
212 * @param cbDst The size of the output buffer.
213 * @param pcbDstActual Where to return the decompressed size.
214 */
215RTDECL(int) RTZipBlockDecompress(RTZIPTYPE enmType, uint32_t fFlags,
216 void const *pvSrc, size_t cbSrc, size_t *pcbSrcActual,
217 void *pvDst, size_t cbDst, size_t *pcbDstActual) RT_NO_THROW_PROTO;
218
219
220/**
221 * Opens a gzip decompression I/O stream.
222 *
223 * @returns IPRT status code.
224 *
225 * @param hVfsIosIn The compressed input stream (must be readable).
226 * The reference is not consumed, instead another
227 * one is retained.
228 * @param fFlags Flags, MBZ.
229 * @param phVfsIosGunzip Where to return the handle to the gunzipped I/O
230 * stream (read).
231 */
232RTDECL(int) RTZipGzipDecompressIoStream(RTVFSIOSTREAM hVfsIosIn, uint32_t fFlags, PRTVFSIOSTREAM phVfsIosGunzip);
233
234/** @name RTZipGzipDecompressIoStream flags.
235 * @{ */
236/** Allow the smaller ZLIB header as well as the regular GZIP header. */
237#define RTZIPGZIPDECOMP_F_ALLOW_ZLIB_HDR RT_BIT(0)
238/** @} */
239
240
241/**
242 * Opens a gzip decompression I/O stream.
243 *
244 * @returns IPRT status code.
245 *
246 * @param hVfsIosDst The compressed output stream (must be writable).
247 * The reference is not consumed, instead another
248 * one is retained.
249 * @param fFlags Flags, MBZ.
250 * @param uLevel The gzip compression level, 1 thru 9.
251 * @param phVfsIosGzip Where to return the gzip input I/O stream handle
252 * (you write to this).
253 */
254RTDECL(int) RTZipGzipCompressIoStream(RTVFSIOSTREAM hVfsIosDst, uint32_t fFlags, uint8_t uLevel, PRTVFSIOSTREAM phVfsIosGzip);
255
256/**
257 * Opens a TAR filesystem stream.
258 *
259 * This is used to extract, list or check a TAR archive.
260 *
261 * @returns IPRT status code.
262 *
263 * @param hVfsIosIn The input stream. The reference is not
264 * consumed, instead another one is retained.
265 * @param fFlags Flags, MBZ.
266 * @param phVfsFss Where to return the handle to the TAR
267 * filesystem stream.
268 */
269RTDECL(int) RTZipTarFsStreamFromIoStream(RTVFSIOSTREAM hVfsIosIn, uint32_t fFlags, PRTVFSFSSTREAM phVfsFss);
270
271/** TAR format type. */
272typedef enum RTZIPTARFORMAT
273{
274 /** Customary invalid zero value. */
275 RTZIPTARFORMAT_INVALID = 0,
276 /** Default format (GNU). */
277 RTZIPTARFORMAT_DEFAULT,
278 /** The GNU format. */
279 RTZIPTARFORMAT_GNU,
280 /** USTAR format from POSIX.1-1988. */
281 RTZIPTARFORMAT_USTAR,
282 /** PAX format from POSIX.1-2001. */
283 RTZIPTARFORMAT_PAX,
284 /** End of valid formats. */
285 RTZIPTARFORMAT_END,
286 /** Make sure the type is at least 32 bits wide. */
287 RTZIPTARFORMAT_32BIT_HACK = 0x7fffffff
288} RTZIPTARFORMAT;
289
290/**
291 * Opens a TAR filesystem stream for the purpose of create a new TAR archive.
292 *
293 * @returns IPRT status code.
294 *
295 * @param hVfsIosOut The output stream, i.e. where the tar stuff is
296 * written. The reference is not consumed, instead
297 * another one is retained.
298 * @param enmFormat The desired output format.
299 * @param fFlags RTZIPTAR_C_XXX.
300 * @param phVfsFss Where to return the handle to the TAR
301 * filesystem stream.
302 */
303RTDECL(int) RTZipTarFsStreamToIoStream(RTVFSIOSTREAM hVfsIosOut, RTZIPTARFORMAT enmFormat,
304 uint32_t fFlags, PRTVFSFSSTREAM phVfsFss);
305
306/** @name RTZIPTAR_C_XXX - TAR creation flags (RTZipTarFsStreamToIoStream).
307 * @{ */
308/** Check for sparse files.
309 * @note Only supported when adding file objects. The files will be read
310 * twice. */
311#define RTZIPTAR_C_SPARSE RT_BIT_32(0)
312/** Valid bits. */
313#define RTZIPTAR_C_VALID_MASK UINT32_C(0x00000001)
314/** @} */
315
316/**
317 * Set the owner to store the archive entries with.
318 *
319 * @returns IPRT status code.
320 * @param hVfsFss The handle to a TAR creator.
321 * @param uid The UID value to set. Passing NIL_RTUID makes
322 * it use the value found in RTFSOBJINFO.
323 * @param pszOwner The owner name to store. Passing NULL makes it
324 * use the value found in RTFSOBJINFO.
325 */
326RTDECL(int) RTZipTarFsStreamSetOwner(RTVFSFSSTREAM hVfsFss, RTUID uid, const char *pszOwner);
327
328/**
329 * Set the group to store the archive entries with.
330 *
331 * @returns IPRT status code.
332 * @param hVfsFss The handle to a TAR creator.
333 * @param gid The GID value to set. Passing NIL_RTUID makes
334 * it use the value found in RTFSOBJINFO.
335 * @param pszGroup The group name to store. Passing NULL makes it
336 * use the value found in RTFSOBJINFO.
337 */
338RTDECL(int) RTZipTarFsStreamSetGroup(RTVFSFSSTREAM hVfsFss, RTGID gid, const char *pszGroup);
339
340/**
341 * Set path prefix to store the archive entries with.
342 *
343 * @returns IPRT status code.
344 * @param hVfsFss The handle to a TAR creator.
345 * @param pszPrefix The path prefix to join the names with. Pass
346 * NULL for no prefix.
347 */
348RTDECL(int) RTZipTarFsStreamSetPrefix(RTVFSFSSTREAM hVfsFss, const char *pszPrefix);
349
350/**
351 * Set the AND and OR masks to apply to file (non-dir) modes in the archive.
352 *
353 * @returns IPRT status code.
354 * @param hVfsFss The handle to a TAR creator.
355 * @param fAndMode The bits to keep
356 * @param fOrMode The bits to set.
357 */
358RTDECL(int) RTZipTarFsStreamSetFileMode(RTVFSFSSTREAM hVfsFss, RTFMODE fAndMode, RTFMODE fOrMode);
359
360/**
361 * Set the AND and OR masks to apply to directory modes in the archive.
362 *
363 * @returns IPRT status code.
364 * @param hVfsFss The handle to a TAR creator.
365 * @param fAndMode The bits to keep
366 * @param fOrMode The bits to set.
367 */
368RTDECL(int) RTZipTarFsStreamSetDirMode(RTVFSFSSTREAM hVfsFss, RTFMODE fAndMode, RTFMODE fOrMode);
369
370/**
371 * Set the modification time to store the archive entires with.
372 *
373 * @returns IPRT status code.
374 * @param hVfsFss The handle to a TAR creator.
375 * @param pModificationTime The modification time to use. Pass NULL to use
376 * the value found in RTFSOBJINFO.
377 */
378RTDECL(int) RTZipTarFsStreamSetMTime(RTVFSFSSTREAM hVfsFss, PCRTTIMESPEC pModificationTime);
379
380
381/**
382 * A mini TAR program.
383 *
384 * @returns Program exit code.
385 *
386 * @param cArgs The number of arguments.
387 * @param papszArgs The argument vector. (Note that this may be
388 * reordered, so the memory must be writable.)
389 */
390RTDECL(RTEXITCODE) RTZipTarCmd(unsigned cArgs, char **papszArgs);
391
392/**
393 * Opens a ZIP filesystem stream.
394 *
395 * This is used to extract, list or check a ZIP archive.
396 *
397 * @returns IPRT status code.
398 *
399 * @param hVfsIosIn The compressed input stream. The reference is
400 * not consumed, instead another one is retained.
401 * @param fFlags Flags, MBZ.
402 * @param phVfsFss Where to return the handle to the TAR
403 * filesystem stream.
404 */
405RTDECL(int) RTZipPkzipFsStreamFromIoStream(RTVFSIOSTREAM hVfsIosIn, uint32_t fFlags, PRTVFSFSSTREAM phVfsFss);
406
407/**
408 * A mini UNZIP program.
409 *
410 * @returns Program exit code.
411 * @
412 * @param cArgs The number of arguments.
413 * @param papszArgs The argument vector. (Note that this may be
414 * reordered, so the memory must be writable.)
415 */
416RTDECL(RTEXITCODE) RTZipUnzipCmd(unsigned cArgs, char **papszArgs);
417
418/**
419 * Helper for decompressing files of a ZIP file located in memory.
420 *
421 * @returns IPRT status code.
422 *
423 * @param ppvDst Where to store the pointer to the allocated
424 * buffer. To be freed with RTMemFree().
425 * @param pcbDst Where to store the pointer to the size of the
426 * allocated buffer.
427 * @param pvSrc Pointer to the buffer containing the .zip file.
428 * @param cbSrc Size of the buffer containing the .zip file.
429 * @param pszObject Name of the object to extract.
430 */
431RTDECL(int) RTZipPkzipMemDecompress(void **ppvDst, size_t *pcbDst, const void *pvSrc, size_t cbSrc, const char *pszObject);
432
433/**
434 * Opens a XAR filesystem stream.
435 *
436 * This is used to extract, list or check a XAR archive.
437 *
438 * @returns IPRT status code.
439 *
440 * @param hVfsIosIn The compressed input stream. The reference is
441 * not consumed, instead another one is retained.
442 * @param fFlags Flags, MBZ.
443 * @param phVfsFss Where to return the handle to the XAR filesystem
444 * stream.
445 */
446RTDECL(int) RTZipXarFsStreamFromIoStream(RTVFSIOSTREAM hVfsIosIn, uint32_t fFlags, PRTVFSFSSTREAM phVfsFss);
447
448/** @} */
449
450RT_C_DECLS_END
451
452#endif
453
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette