zip.h@ 93176

Last change on this file since 93176 was 93115, checked in by vboxsync, 3 years ago
scm --update-copyright-year
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 18.7 KB

Line
1	/** @file
2	* IPRT - Compression.
3	*/
4
5	/*
6	* Copyright (C) 2006-2022 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
35	RT_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	*/
52	typedef DECLCALLBACKTYPE(int, FNRTZIPOUT,(void pvUser, const void pvBuf, size_t cbBuf));
53	/** Pointer to FNRTZIPOUT() function. */
54	typedef 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	*/
65	typedef DECLCALLBACKTYPE(int, FNRTZIPIN,(void pvUser, void pvBuf, size_t cbBuf, size_t *pcbBuf));
66	/** Pointer to FNRTZIPIN() function. */
67	typedef FNRTZIPIN *PFNRTZIPIN;
68
69	/**
70	* Compression type.
71	* (Be careful with these they are stored in files!)
72	*/
73	typedef 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	*/
100	typedef 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	*/
123	RTDECL(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	*/
133	RTDECL(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	*/
142	RTDECL(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	*/
150	RTDECL(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	*/
161	RTDECL(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	*/
174	RTDECL(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	*/
182	RTDECL(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	*/
199	RTDECL(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	*/
218	RTDECL(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	*/
235	RTDECL(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	*/
257	RTDECL(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	*/
268	RTDECL(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	*/
283	RTDECL(int) RTZipTarFsStreamFromIoStream(RTVFSIOSTREAM hVfsIosIn, uint32_t fFlags, PRTVFSFSSTREAM phVfsFss);
284
285	/** TAR format type. */
286	typedef 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, except RTZIPTAR_C_UPDATE.
314	* @param phVfsFss Where to return the handle to the TAR
315	* filesystem stream.
316	*/
317	RTDECL(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	/** Set if opening for updating. */
327	#define RTZIPTAR_C_UPDATE RT_BIT_32(1)
328	/** Valid bits. */
329	#define RTZIPTAR_C_VALID_MASK UINT32_C(0x00000003)
330	/** @} */
331
332	/**
333	* Opens a TAR filesystem stream for the purpose of create a new TAR archive or
334	* updating an existing one.
335	*
336	* @returns IPRT status code.
337	*
338	* @param hVfsFile The TAR file handle, i.e. where the tar stuff is
339	* written and optionally read/update. The
340	* reference is not consumed, instead another one
341	* is retained.
342	* @param enmFormat The desired output format.
343	* @param fFlags RTZIPTAR_C_XXX.
344	* @param phVfsFss Where to return the handle to the TAR
345	* filesystem stream.
346	*/
347	RTDECL(int) RTZipTarFsStreamForFile(RTVFSFILE hVfsFile, RTZIPTARFORMAT enmFormat, uint32_t fFlags, PRTVFSFSSTREAM phVfsFss);
348
349	/**
350	* Set the owner to store the archive entries with.
351	*
352	* @returns IPRT status code.
353	* @param hVfsFss The handle to a TAR creator.
354	* @param uid The UID value to set. Passing NIL_RTUID makes
355	* it use the value found in RTFSOBJINFO.
356	* @param pszOwner The owner name to store. Passing NULL makes it
357	* use the value found in RTFSOBJINFO.
358	*/
359	RTDECL(int) RTZipTarFsStreamSetOwner(RTVFSFSSTREAM hVfsFss, RTUID uid, const char *pszOwner);
360
361	/**
362	* Set the group to store the archive entries with.
363	*
364	* @returns IPRT status code.
365	* @param hVfsFss The handle to a TAR creator.
366	* @param gid The GID value to set. Passing NIL_RTUID makes
367	* it use the value found in RTFSOBJINFO.
368	* @param pszGroup The group name to store. Passing NULL makes it
369	* use the value found in RTFSOBJINFO.
370	*/
371	RTDECL(int) RTZipTarFsStreamSetGroup(RTVFSFSSTREAM hVfsFss, RTGID gid, const char *pszGroup);
372
373	/**
374	* Set path prefix to store the archive entries with.
375	*
376	* @returns IPRT status code.
377	* @param hVfsFss The handle to a TAR creator.
378	* @param pszPrefix The path prefix to join the names with. Pass
379	* NULL for no prefix.
380	*/
381	RTDECL(int) RTZipTarFsStreamSetPrefix(RTVFSFSSTREAM hVfsFss, const char *pszPrefix);
382
383	/**
384	* Set the AND and OR masks to apply to file (non-dir) modes in the archive.
385	*
386	* @returns IPRT status code.
387	* @param hVfsFss The handle to a TAR creator.
388	* @param fAndMode The bits to keep
389	* @param fOrMode The bits to set.
390	*/
391	RTDECL(int) RTZipTarFsStreamSetFileMode(RTVFSFSSTREAM hVfsFss, RTFMODE fAndMode, RTFMODE fOrMode);
392
393	/**
394	* Set the AND and OR masks to apply to directory modes in the archive.
395	*
396	* @returns IPRT status code.
397	* @param hVfsFss The handle to a TAR creator.
398	* @param fAndMode The bits to keep
399	* @param fOrMode The bits to set.
400	*/
401	RTDECL(int) RTZipTarFsStreamSetDirMode(RTVFSFSSTREAM hVfsFss, RTFMODE fAndMode, RTFMODE fOrMode);
402
403	/**
404	* Set the modification time to store the archive entires with.
405	*
406	* @returns IPRT status code.
407	* @param hVfsFss The handle to a TAR creator.
408	* @param pModificationTime The modification time to use. Pass NULL to use
409	* the value found in RTFSOBJINFO.
410	*/
411	RTDECL(int) RTZipTarFsStreamSetMTime(RTVFSFSSTREAM hVfsFss, PCRTTIMESPEC pModificationTime);
412
413	/**
414	* Truncates a TAR creator stream in update mode.
415	*
416	* Use RTVfsFsStrmNext to examine the TAR stream and locate the cut-off point.
417	*
418	* After performing this call, the stream will be in write mode and
419	* RTVfsFsStrmNext will stop working (VERR_WRONG_ORDER). The RTVfsFsStrmAdd()
420	* and RTVfsFsStrmPushFile() can be used to add new object to the TAR file,
421	* starting at the trunction point. RTVfsFsStrmEnd() is used to finish the TAR
422	* file (this performs the actual file trunction).
423	*
424	* @returns IPRT status code.
425	* @param hVfsFss The handle to a TAR creator in update mode.
426	* @param hVfsObj Object returned by RTVfsFsStrmNext that the
427	* trunction is relative to. This doesn't have to
428	* be the current stream object, it can be an
429	* earlier one too.
430	* @param fAfter If set, @a hVfsObj will remain in the update TAR
431	* file. If clear, @a hVfsObj will not be
432	* included.
433	*/
434	RTDECL(int) RTZipTarFsStreamTruncate(RTVFSFSSTREAM hVfsFss, RTVFSOBJ hVfsObj, bool fAfter);
435
436	/**
437	* A mini TAR program.
438	*
439	* @returns Program exit code.
440	*
441	* @param cArgs The number of arguments.
442	* @param papszArgs The argument vector. (Note that this may be
443	* reordered, so the memory must be writable.)
444	*/
445	RTDECL(RTEXITCODE) RTZipTarCmd(unsigned cArgs, char **papszArgs);
446
447	/**
448	* Opens a ZIP filesystem stream.
449	*
450	* This is used to extract, list or check a ZIP 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 TAR
458	* filesystem stream.
459	*/
460	RTDECL(int) RTZipPkzipFsStreamFromIoStream(RTVFSIOSTREAM hVfsIosIn, uint32_t fFlags, PRTVFSFSSTREAM phVfsFss);
461
462	/**
463	* A mini UNZIP program.
464	*
465	* @returns Program exit code.
466	* @
467	* @param cArgs The number of arguments.
468	* @param papszArgs The argument vector. (Note that this may be
469	* reordered, so the memory must be writable.)
470	*/
471	RTDECL(RTEXITCODE) RTZipUnzipCmd(unsigned cArgs, char **papszArgs);
472
473	/**
474	* Helper for decompressing files of a ZIP file located in memory.
475	*
476	* @returns IPRT status code.
477	*
478	* @param ppvDst Where to store the pointer to the allocated
479	* buffer. To be freed with RTMemFree().
480	* @param pcbDst Where to store the pointer to the size of the
481	* allocated buffer.
482	* @param pvSrc Pointer to the buffer containing the .zip file.
483	* @param cbSrc Size of the buffer containing the .zip file.
484	* @param pszObject Name of the object to extract.
485	*/
486	RTDECL(int) RTZipPkzipMemDecompress(void *ppvDst, size_t pcbDst, const void pvSrc, size_t cbSrc, const char pszObject);
487
488	/**
489	* Opens a XAR filesystem stream.
490	*
491	* This is used to extract, list or check a XAR archive.
492	*
493	* @returns IPRT status code.
494	*
495	* @param hVfsIosIn The compressed input stream. The reference is
496	* not consumed, instead another one is retained.
497	* @param fFlags Flags, MBZ.
498	* @param phVfsFss Where to return the handle to the XAR filesystem
499	* stream.
500	*/
501	RTDECL(int) RTZipXarFsStreamFromIoStream(RTVFSIOSTREAM hVfsIosIn, uint32_t fFlags, PRTVFSFSSTREAM phVfsFss);
502
503	/**
504	* Opens a CPIO filesystem stream.
505	*
506	* This is used to extract, list or check a CPIO archive.
507	*
508	* @returns IPRT status code.
509	*
510	* @param hVfsIosIn The input stream. The reference is not
511	* consumed, instead another one is retained.
512	* @param fFlags Flags, MBZ.
513	* @param phVfsFss Where to return the handle to the CPIO
514	* filesystem stream.
515	*/
516	RTDECL(int) RTZipCpioFsStreamFromIoStream(RTVFSIOSTREAM hVfsIosIn, uint32_t fFlags, PRTVFSFSSTREAM phVfsFss);
517
518	/** @} */
519
520	RT_C_DECLS_END
521
522	#endif /* !IPRT_INCLUDED_zip_h */
523

Note: See TracBrowser for help on using the repository browser.

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

Download in other formats: