zip.h@ 74312

Last change on this file since 74312 was 70423, checked in by vboxsync, 7 years ago
IPRT: Moved RTZipGZipCmd into the runtime, leaving a main wrapper behind. Want to use it too in VBoxControl for debugging purposes.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 16.0 KB

Line
1	/** @file
2	* IPRT - Compression.
3	*/
4
5	/*
6	* Copyright (C) 2006-2017 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
32	RT_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	*/
49	typedef DECLCALLBACK(int) FNRTZIPOUT(void pvUser, const void pvBuf, size_t cbBuf);
50	/** Pointer to FNRTZIPOUT() function. */
51	typedef 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	*/
62	typedef DECLCALLBACK(int) FNRTZIPIN(void pvUser, void pvBuf, size_t cbBuf, size_t *pcbBuf);
63	/** Pointer to FNRTZIPIN() function. */
64	typedef FNRTZIPIN *PFNRTZIPIN;
65
66	/**
67	* Compression type.
68	* (Be careful with these they are stored in files!)
69	*/
70	typedef 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	*/
97	typedef 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	*/
120	RTDECL(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	*/
130	RTDECL(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	*/
139	RTDECL(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	*/
147	RTDECL(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	*/
158	RTDECL(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	*/
171	RTDECL(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	*/
179	RTDECL(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	*/
196	RTDECL(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	*/
215	RTDECL(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	*/
232	RTDECL(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	*/
254	RTDECL(int) RTZipGzipCompressIoStream(RTVFSIOSTREAM hVfsIosDst, uint32_t fFlags, uint8_t uLevel, PRTVFSIOSTREAM phVfsIosGzip);
255
256	/**
257	* A mini GZIP program.
258	*
259	* @returns Program exit code.
260	*
261	* @param cArgs The number of arguments.
262	* @param papszArgs The argument vector. (Note that this may be
263	* reordered, so the memory must be writable.)
264	*/
265	RTDECL(RTEXITCODE) RTZipGzipCmd(unsigned cArgs, char **papszArgs);
266
267	/**
268	* Opens a TAR filesystem stream.
269	*
270	* This is used to extract, list or check a TAR archive.
271	*
272	* @returns IPRT status code.
273	*
274	* @param hVfsIosIn The input stream. The reference is not
275	* consumed, instead another one is retained.
276	* @param fFlags Flags, MBZ.
277	* @param phVfsFss Where to return the handle to the TAR
278	* filesystem stream.
279	*/
280	RTDECL(int) RTZipTarFsStreamFromIoStream(RTVFSIOSTREAM hVfsIosIn, uint32_t fFlags, PRTVFSFSSTREAM phVfsFss);
281
282	/** TAR format type. */
283	typedef enum RTZIPTARFORMAT
284	{
285	/** Customary invalid zero value. */
286	RTZIPTARFORMAT_INVALID = 0,
287	/** Default format (GNU). */
288	RTZIPTARFORMAT_DEFAULT,
289	/** The GNU format. */
290	RTZIPTARFORMAT_GNU,
291	/** USTAR format from POSIX.1-1988. */
292	RTZIPTARFORMAT_USTAR,
293	/** PAX format from POSIX.1-2001. */
294	RTZIPTARFORMAT_PAX,
295	/** End of valid formats. */
296	RTZIPTARFORMAT_END,
297	/** Make sure the type is at least 32 bits wide. */
298	RTZIPTARFORMAT_32BIT_HACK = 0x7fffffff
299	} RTZIPTARFORMAT;
300
301	/**
302	* Opens a TAR filesystem stream for the purpose of create a new TAR archive.
303	*
304	* @returns IPRT status code.
305	*
306	* @param hVfsIosOut The output stream, i.e. where the tar stuff is
307	* written. The reference is not consumed, instead
308	* another one is retained.
309	* @param enmFormat The desired output format.
310	* @param fFlags RTZIPTAR_C_XXX.
311	* @param phVfsFss Where to return the handle to the TAR
312	* filesystem stream.
313	*/
314	RTDECL(int) RTZipTarFsStreamToIoStream(RTVFSIOSTREAM hVfsIosOut, RTZIPTARFORMAT enmFormat,
315	uint32_t fFlags, PRTVFSFSSTREAM phVfsFss);
316
317	/** @name RTZIPTAR_C_XXX - TAR creation flags (RTZipTarFsStreamToIoStream).
318	* @{ */
319	/** Check for sparse files.
320	* @note Only supported when adding file objects. The files will be read
321	* twice. */
322	#define RTZIPTAR_C_SPARSE RT_BIT_32(0)
323	/** Valid bits. */
324	#define RTZIPTAR_C_VALID_MASK UINT32_C(0x00000001)
325	/** @} */
326
327	/**
328	* Set the owner to store the archive entries with.
329	*
330	* @returns IPRT status code.
331	* @param hVfsFss The handle to a TAR creator.
332	* @param uid The UID value to set. Passing NIL_RTUID makes
333	* it use the value found in RTFSOBJINFO.
334	* @param pszOwner The owner name to store. Passing NULL makes it
335	* use the value found in RTFSOBJINFO.
336	*/
337	RTDECL(int) RTZipTarFsStreamSetOwner(RTVFSFSSTREAM hVfsFss, RTUID uid, const char *pszOwner);
338
339	/**
340	* Set the group to store the archive entries with.
341	*
342	* @returns IPRT status code.
343	* @param hVfsFss The handle to a TAR creator.
344	* @param gid The GID value to set. Passing NIL_RTUID makes
345	* it use the value found in RTFSOBJINFO.
346	* @param pszGroup The group name to store. Passing NULL makes it
347	* use the value found in RTFSOBJINFO.
348	*/
349	RTDECL(int) RTZipTarFsStreamSetGroup(RTVFSFSSTREAM hVfsFss, RTGID gid, const char *pszGroup);
350
351	/**
352	* Set path prefix to store the archive entries with.
353	*
354	* @returns IPRT status code.
355	* @param hVfsFss The handle to a TAR creator.
356	* @param pszPrefix The path prefix to join the names with. Pass
357	* NULL for no prefix.
358	*/
359	RTDECL(int) RTZipTarFsStreamSetPrefix(RTVFSFSSTREAM hVfsFss, const char *pszPrefix);
360
361	/**
362	* Set the AND and OR masks to apply to file (non-dir) modes in the archive.
363	*
364	* @returns IPRT status code.
365	* @param hVfsFss The handle to a TAR creator.
366	* @param fAndMode The bits to keep
367	* @param fOrMode The bits to set.
368	*/
369	RTDECL(int) RTZipTarFsStreamSetFileMode(RTVFSFSSTREAM hVfsFss, RTFMODE fAndMode, RTFMODE fOrMode);
370
371	/**
372	* Set the AND and OR masks to apply to directory modes in the archive.
373	*
374	* @returns IPRT status code.
375	* @param hVfsFss The handle to a TAR creator.
376	* @param fAndMode The bits to keep
377	* @param fOrMode The bits to set.
378	*/
379	RTDECL(int) RTZipTarFsStreamSetDirMode(RTVFSFSSTREAM hVfsFss, RTFMODE fAndMode, RTFMODE fOrMode);
380
381	/**
382	* Set the modification time to store the archive entires with.
383	*
384	* @returns IPRT status code.
385	* @param hVfsFss The handle to a TAR creator.
386	* @param pModificationTime The modification time to use. Pass NULL to use
387	* the value found in RTFSOBJINFO.
388	*/
389	RTDECL(int) RTZipTarFsStreamSetMTime(RTVFSFSSTREAM hVfsFss, PCRTTIMESPEC pModificationTime);
390
391
392	/**
393	* A mini TAR program.
394	*
395	* @returns Program exit code.
396	*
397	* @param cArgs The number of arguments.
398	* @param papszArgs The argument vector. (Note that this may be
399	* reordered, so the memory must be writable.)
400	*/
401	RTDECL(RTEXITCODE) RTZipTarCmd(unsigned cArgs, char **papszArgs);
402
403	/**
404	* Opens a ZIP filesystem stream.
405	*
406	* This is used to extract, list or check a ZIP archive.
407	*
408	* @returns IPRT status code.
409	*
410	* @param hVfsIosIn The compressed input stream. The reference is
411	* not consumed, instead another one is retained.
412	* @param fFlags Flags, MBZ.
413	* @param phVfsFss Where to return the handle to the TAR
414	* filesystem stream.
415	*/
416	RTDECL(int) RTZipPkzipFsStreamFromIoStream(RTVFSIOSTREAM hVfsIosIn, uint32_t fFlags, PRTVFSFSSTREAM phVfsFss);
417
418	/**
419	* A mini UNZIP program.
420	*
421	* @returns Program exit code.
422	* @
423	* @param cArgs The number of arguments.
424	* @param papszArgs The argument vector. (Note that this may be
425	* reordered, so the memory must be writable.)
426	*/
427	RTDECL(RTEXITCODE) RTZipUnzipCmd(unsigned cArgs, char **papszArgs);
428
429	/**
430	* Helper for decompressing files of a ZIP file located in memory.
431	*
432	* @returns IPRT status code.
433	*
434	* @param ppvDst Where to store the pointer to the allocated
435	* buffer. To be freed with RTMemFree().
436	* @param pcbDst Where to store the pointer to the size of the
437	* allocated buffer.
438	* @param pvSrc Pointer to the buffer containing the .zip file.
439	* @param cbSrc Size of the buffer containing the .zip file.
440	* @param pszObject Name of the object to extract.
441	*/
442	RTDECL(int) RTZipPkzipMemDecompress(void *ppvDst, size_t pcbDst, const void pvSrc, size_t cbSrc, const char pszObject);
443
444	/**
445	* Opens a XAR filesystem stream.
446	*
447	* This is used to extract, list or check a XAR archive.
448	*
449	* @returns IPRT status code.
450	*
451	* @param hVfsIosIn The compressed input stream. The reference is
452	* not consumed, instead another one is retained.
453	* @param fFlags Flags, MBZ.
454	* @param phVfsFss Where to return the handle to the XAR filesystem
455	* stream.
456	*/
457	RTDECL(int) RTZipXarFsStreamFromIoStream(RTVFSIOSTREAM hVfsIosIn, uint32_t fFlags, PRTVFSFSSTREAM phVfsFss);
458
459	/** @} */
460
461	RT_C_DECLS_END
462
463	#endif
464

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

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

Download in other formats: