VirtualBox

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

Last change on this file since 77807 was 76585, checked in by vboxsync, 6 years ago

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

© 2024 Oracle
Contact – Privacy/Do Not Sell My Info – Terms of Use