manifest.h@ 47241

Last change on this file since 47241 was 46980, checked in by vboxsync, 11 years ago
Deprecated the old manifest API. r=bird: IPRT does NOT use ugly C++ references, it pointers directly - no cloak and dagger pointers thank you. Please don't reformat if expressions into unreadability. RTDIGESTTYPE_UNKNOWN should be RTDIGESTTYPE_INVALID and there is actually no need to set output variables on failure, just check the status code.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 21.3 KB

Line
1	/** @file
2	* IPRT - Manifest file handling.
3	*/
4
5	/*
6	* Copyright (C) 2009-2012 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_manifest_h
27	#define ___iprt_manifest_h
28
29	#include <iprt/cdefs.h>
30	#include <iprt/types.h>
31
32	RT_C_DECLS_BEGIN
33
34	/** @defgroup grp_rt_manifest RTManifest - Manifest file creation and checking
35	* @ingroup grp_rt
36	* @{
37	*/
38
39	/** @name Manifest attribute types.
40	* The types can be ORed together to form a set.
41	* @{ */
42	/** For use with other attributes. Representation unknown. */
43	#define RTMANIFEST_ATTR_UNKNOWN 0
44	/** The size of the content. Represented as a decimal number. */
45	#define RTMANIFEST_ATTR_SIZE RT_BIT_32(0)
46	/** The MD5 of the content. Represented as a hex string. */
47	#define RTMANIFEST_ATTR_MD5 RT_BIT_32(1)
48	/** The SHA-1 of the content. Represented as a hex string. */
49	#define RTMANIFEST_ATTR_SHA1 RT_BIT_32(2)
50	/** The SHA-256 of the content. Represented as a hex string. */
51	#define RTMANIFEST_ATTR_SHA256 RT_BIT_32(3)
52	/** The SHA-512 of the content. Represented as a hex string. */
53	#define RTMANIFEST_ATTR_SHA512 RT_BIT_32(4)
54	/** The end of the valid values. */
55	#define RTMANIFEST_ATTR_END RT_BIT_32(5)
56	/** Wildcard for use in queries. */
57	#define RTMANIFEST_ATTR_ANY UINT32_C(0xffffffff)
58	/** @} */
59
60	/** @name Digest types. */
61	typedef enum RTDIGESTTYPE
62	{
63	/** Invalid digest value. */
64	RTDIGESTTYPE_INVALID = 0,
65	/** CRC32 checksum. */
66	RTDIGESTTYPE_CRC32,
67	/** CRC64 checksum. */
68	RTDIGESTTYPE_CRC64,
69	/** MD5 checksum (unsafe!). */
70	RTDIGESTTYPE_MD5,
71	/** SHA1 checksum (unsafe!). */
72	RTDIGESTTYPE_SHA1,
73	/** SHA256 checksum. */
74	RTDIGESTTYPE_SHA256,
75	/** SHA512 checksum. */
76	RTDIGESTTYPE_SHA512,
77	/** Usual 32-bit type blowup. */
78	RTDIGESTTYPE_32BIT_HACK = 0x7fffffff
79	} RTDIGESTTYPE;
80	/** @} */
81
82
83	/**
84	* Creates an empty manifest.
85	*
86	* @returns IPRT status code.
87	* @param fFlags Flags, MBZ.
88	* @param phManifest Where to return the handle to the manifest.
89	*/
90	RTDECL(int) RTManifestCreate(uint32_t fFlags, PRTMANIFEST phManifest);
91
92	/**
93	* Retains a reference to the manifest handle.
94	*
95	* @returns The new reference count, UINT32_MAX if the handle is invalid.
96	* @param hManifest The handle to retain.
97	*/
98	RTDECL(uint32_t) RTManifestRetain(RTMANIFEST hManifest);
99
100	/**
101	* Releases a reference to the manifest handle.
102	*
103	* @returns The new reference count, 0 if free. UINT32_MAX is returned if the
104	* handle is invalid.
105	* @param hManifest The handle to release.
106	* NIL is quietly ignored (returns 0).
107	*/
108	RTDECL(uint32_t) RTManifestRelease(RTMANIFEST hManifest);
109
110	/**
111	* Creates a duplicate of the specified manifest.
112	*
113	* @returns IPRT status code
114	* @param hManifestSrc The manifest to clone.
115	* @param phManifestDst Where to store the handle to the duplicate.
116	*/
117	RTDECL(int) RTManifestDup(RTMANIFEST hManifestSrc, PRTMANIFEST phManifestDst);
118
119	/**
120	* Compares two manifests for equality.
121	*
122	* @returns IPRT status code.
123	* @retval VINF_SUCCESS if equal.
124	* @retval VERR_NOT_EQUAL if not equal.
125	*
126	* @param hManifest1 The first manifest.
127	* @param hManifest2 The second manifest.
128	* @param papszIgnoreEntries Entries to ignore. Ends with a NULL entry.
129	* @param papszIgnoreAttrs Attributes to ignore. Ends with a NULL entry.
130	* @param fFlags A combination of RTMANIFEST_EQUALS_XXX values.
131	* @param pszError Where to store the name of the mismatching
132	* entry, or as much of the name as there is room
133	* for. This is always set. Optional.
134	* @param cbError The size of the buffer pointed to by @a
135	* pszError.
136	*/
137	RTDECL(int) RTManifestEqualsEx(RTMANIFEST hManifest1, RTMANIFEST hManifest2, const char * const *papszIgnoreEntries,
138	const char * const papszIgnoreAttr, uint32_t fFlags, char pszError, size_t cbError);
139
140	/** @defgroup RTMANIFEST_EQUALS_XXX RTManifestEqualsEx flags
141	* @{ */
142	/** Ignore missing attributes if there is one or more to compare. */
143	#define RTMANIFEST_EQUALS_IGN_MISSING_ATTRS RT_BIT_32(0)
144	/** Ignore attributes missing in the 1st manifest.
145	* @todo implement this */
146	#define RTMANIFEST_EQUALS_IGN_MISSING_ATTRS_1ST RT_BIT_32(1)
147	/** Mask of valid flags. */
148	#define RTMANIFEST_EQUALS_VALID_MASK UINT32_C(0x00000003)
149	/** @} */
150
151	/**
152	* Compares two manifests for equality.
153	*
154	* @returns IPRT status code.
155	* @retval VINF_SUCCESS if equal.
156	* @retval VERR_NOT_EQUAL if not equal.
157	*
158	* @param hManifest1 The first manifest.
159	* @param hManifest2 The second manifest.
160	*/
161	RTDECL(int) RTManifestEquals(RTMANIFEST hManifest1, RTMANIFEST hManifest2);
162
163	/**
164	* Sets a manifest attribute.
165	*
166	* @returns IPRT status code.
167	* @param hManifest The manifest handle.
168	* @param pszAttr The attribute name. If this already exists,
169	* its value will be replaced.
170	* @param pszValue The value string.
171	* @param fType The attribute type, pass
172	* RTMANIFEST_ATTR_UNKNOWN if not known.
173	*/
174	RTDECL(int) RTManifestSetAttr(RTMANIFEST hManifest, const char pszAttr, const char pszValue, uint32_t fType);
175
176	/**
177	* Unsets (removes) a manifest attribute if it exists.
178	*
179	* @returns IPRT status code.
180	* @retval VWRN_NOT_FOUND if not found.
181	*
182	* @param hManifest The manifest handle.
183	* @param pszAttr The attribute name.
184	*/
185	RTDECL(int) RTManifestUnsetAttr(RTMANIFEST hManifest, const char *pszAttr);
186
187	/**
188	* Query a manifest entry attribute.
189	*
190	* @returns IPRT status code.
191	* @retval VERR_BUFFER_OVERFLOW if the value buffer is too small. The @a
192	* pszValue buffer will not be modified.
193	* @retval VERR_MANIFEST_ATTR_NOT_FOUND
194	* @retval VERR_MANIFEST_ATTR_TYPE_NOT_FOUND
195	* @retval VERR_MANIFEST_ATTR_TYPE_MISMATCH
196	*
197	* @param hManifest The manifest handle.
198	* @param pszEntry The entry name.
199	* @param pszAttr The attribute name. If NULL, it will be
200	* selected by @a fType alone.
201	* @param fType The attribute types the entry should match. Pass
202	* Pass RTMANIFEST_ATTR_ANY match any. If more
203	* than one is given, the first matching one is
204	* returned.
205	* @param pszValue Where to return value.
206	* @param cbValue The size of the buffer @a pszValue points to.
207	* @param pfType Where to return the attribute type value.
208	*/
209	RTDECL(int) RTManifestQueryAttr(RTMANIFEST hManifest, const char *pszAttr, uint32_t fType,
210	char pszValue, size_t cbValue, uint32_t pfType);
211
212	/**
213	* Sets an attribute of a manifest entry.
214	*
215	* @returns IPRT status code.
216	* @param hManifest The manifest handle.
217	* @param pszEntry The entry name. This will automatically be
218	* added if there was no previous call to
219	* RTManifestEntryAdd for this name. See
220	* RTManifestEntryAdd for the entry name rules.
221	* @param pszAttr The attribute name. If this already exists,
222	* its value will be replaced.
223	* @param pszValue The value string.
224	* @param fType The attribute type, pass
225	* RTMANIFEST_ATTR_UNKNOWN if not known.
226	*/
227	RTDECL(int) RTManifestEntrySetAttr(RTMANIFEST hManifest, const char pszEntry, const char pszAttr,
228	const char *pszValue, uint32_t fType);
229
230	/**
231	* Unsets (removes) an attribute of a manifest entry if they both exist.
232	*
233	* @returns IPRT status code.
234	* @retval VWRN_NOT_FOUND if not found.
235	*
236	* @param hManifest The manifest handle.
237	* @param pszEntry The entry name.
238	* @param pszAttr The attribute name.
239	*/
240	RTDECL(int) RTManifestEntryUnsetAttr(RTMANIFEST hManifest, const char pszEntry, const char pszAttr);
241
242	/**
243	* Query a manifest entry attribute.
244	*
245	* @returns IPRT status code.
246	* @retval VERR_BUFFER_OVERFLOW if the value buffer is too small. The @a
247	* pszValue buffer will not be modified.
248	* @retval VERR_NOT_FOUND if the entry was not found.
249	* @retval VERR_MANIFEST_ATTR_NOT_FOUND
250	* @retval VERR_MANIFEST_ATTR_TYPE_NOT_FOUND
251	* @retval VERR_MANIFEST_ATTR_TYPE_MISMATCH
252	*
253	* @param hManifest The manifest handle.
254	* @param pszEntry The entry name.
255	* @param pszAttr The attribute name. If NULL, it will be
256	* selected by @a fType alone.
257	* @param fType The attribute types the entry should match. Pass
258	* Pass RTMANIFEST_ATTR_ANY match any. If more
259	* than one is given, the first matching one is
260	* returned.
261	* @param pszValue Where to return value.
262	* @param cbValue The size of the buffer @a pszValue points to.
263	* @param pfType Where to return the attribute type value.
264	*/
265	RTDECL(int) RTManifestEntryQueryAttr(RTMANIFEST hManifest, const char pszEntry, const char pszAttr, uint32_t fType,
266	char pszValue, size_t cbValue, uint32_t pfType);
267
268	/**
269	* Adds a new entry to a manifest.
270	*
271	* The entry name rules:
272	* - The entry name can contain any character defined by unicode, except
273	* control characters, ':', '(' and ')'. The exceptions are mainly there
274	* because of uncertainty around how various formats handles these.
275	* - It is considered case sensitive.
276	* - Forward (unix) and backward (dos) slashes are considered path
277	* separators and converted to forward slashes.
278	*
279	* @returns IPRT status code.
280	* @retval VWRN_ALREADY_EXISTS if the entry already exists.
281	*
282	* @param hManifest The manifest handle.
283	* @param pszEntry The entry name (UTF-8).
284	*
285	* @remarks Some manifest formats will not be able to store an entry without
286	* any attributes. So, this is just here in case it comes in handy
287	* when dealing with formats which can.
288	*/
289	RTDECL(int) RTManifestEntryAdd(RTMANIFEST hManifest, const char *pszEntry);
290
291	/**
292	* Removes an entry.
293	*
294	* @returns IPRT status code.
295	* @param hManifest The manifest handle.
296	* @param pszEntry The entry name.
297	*/
298	RTDECL(int) RTManifestEntryRemove(RTMANIFEST hManifest, const char *pszEntry);
299
300	/**
301	* Add an entry for an I/O stream using a passthru stream.
302	*
303	* The passthru I/O stream will hash all the data read from or written to the
304	* stream and automatically add an entry to the manifest with the desired
305	* attributes when it is released. Alternatively one can call
306	* RTManifestPtIosAddEntryNow() to have more control over exactly when this
307	* action is performed and which status it yields.
308	*
309	* @returns IPRT status code.
310	* @param hManifest The manifest to add the entry to.
311	* @param hVfsIos The I/O stream to pass thru to/from.
312	* @param pszEntry The entry name.
313	* @param fAttrs The attributes to create for this stream.
314	* @param fReadOrWrite Whether it's a read or write I/O stream.
315	* @param phVfsIosPassthru Where to return the new handle.
316	*/
317	RTDECL(int) RTManifestEntryAddPassthruIoStream(RTMANIFEST hManifest, RTVFSIOSTREAM hVfsIos, const char *pszEntry,
318	uint32_t fAttrs, bool fReadOrWrite, PRTVFSIOSTREAM phVfsIosPassthru);
319
320	/**
321	* Adds the entry to the manifest right now.
322	*
323	* @returns IPRT status code.
324	* @param hVfsPtIos The manifest passthru I/O stream returned by
325	* RTManifestEntryAddPassthruIoStream().
326	*/
327	RTDECL(int) RTManifestPtIosAddEntryNow(RTVFSIOSTREAM hVfsPtIos);
328
329	/**
330	* Adds an entry for a file with the specified set of attributes.
331	*
332	* @returns IPRT status code.
333	*
334	* @param hManifest The manifest handle.
335	* @param hVfsIos The I/O stream handle of the entry. This will
336	* be processed to its end on successful return.
337	* (Must be positioned at the start to get
338	* the expected results.)
339	* @param pszEntry The entry name.
340	* @param fAttrs The attributes to create for this stream. See
341	* RTMANIFEST_ATTR_XXX.
342	*/
343	RTDECL(int) RTManifestEntryAddIoStream(RTMANIFEST hManifest, RTVFSIOSTREAM hVfsIos, const char *pszEntry, uint32_t fAttrs);
344
345	/**
346	* Checks if there is a manifest entry by the given name.
347	*
348	* @returns true if there is, false if not or if the handle is invalid.
349	* @param hManifest The manifest handle.
350	* @param pszEntry The entry name.
351	*/
352	RTDECL(bool) RTManifestEntryExists(RTMANIFEST hManifest, const char *pszEntry);
353
354	/**
355	* Reads in a "standard" manifest.
356	*
357	* This reads the format used by OVF, the distinfo in FreeBSD ports, and
358	* others.
359	*
360	* @returns IPRT status code.
361	* @param hManifest The handle to the manifest where to add the
362	* manifest that's read in.
363	* @param hVfsIos The I/O stream to read the manifest from.
364	*/
365	RTDECL(int) RTManifestReadStandard(RTMANIFEST hManifest, RTVFSIOSTREAM hVfsIos);
366
367	/**
368	* Reads in a "standard" manifest.
369	*
370	* This reads the format used by OVF, the distinfo in FreeBSD ports, and
371	* others.
372	*
373	* @returns IPRT status code.
374	* @param hManifest The handle to the manifest where to add the
375	* manifest that's read in.
376	* @param hVfsIos The I/O stream to read the manifest from.
377	* @param pszErr Where to return extended error info on failure.
378	* Optional.
379	* @param cbErr The size of the buffer @a pszErr points to.
380	*/
381	RTDECL(int) RTManifestReadStandardEx(RTMANIFEST hManifest, RTVFSIOSTREAM hVfsIos, char *pszErr, size_t cbErr);
382
383	/**
384	* Reads in a "standard" manifest from the specified file.
385	*
386	* This reads the format used by OVF, the distinfo in FreeBSD ports, and
387	* others.
388	*
389	* @returns IPRT status code.
390	* @param hManifest The handle to the manifest where to add the
391	* manifest that's read in.
392	* @param pszFilename The name of the file to read in.
393	*/
394	RTDECL(int) RTManifestReadStandardFromFile(RTMANIFEST hManifest, const char *pszFilename);
395
396	/**
397	* Writes a "standard" manifest.
398	*
399	* This writes the format used by OVF, the distinfo in FreeBSD ports, and
400	* others.
401	*
402	* @returns IPRT status code.
403	* @param hManifest The handle to the manifest to write.
404	* @param hVfsIos The I/O stream to read the manifest from.
405	*/
406	RTDECL(int) RTManifestWriteStandard(RTMANIFEST hManifest, RTVFSIOSTREAM hVfsIos);
407
408	/**
409	* Writes a "standard" manifest to the specified file.
410	*
411	* @returns IPRT status code.
412	* @param hManifest The handle to the manifest to write.
413	* @param pszFilename The name of the file.
414	*/
415	RTDECL(int) RTManifestWriteStandardToFile(RTMANIFEST hManifest, const char *pszFilename);
416
417
418
419
420
421	/**
422	* Input structure for RTManifestVerify() which contains the filename & the
423	* SHA1/SHA256 digest.
424	*/
425	typedef struct RTMANIFESTTEST
426	{
427	/** The filename. */
428	const char *pszTestFile;
429	/** The SHA1/SHA256 digest of the file. */
430	const char *pszTestDigest;
431	} RTMANIFESTTEST;
432	/** Pointer to the input structure. */
433	typedef RTMANIFESTTEST* PRTMANIFESTTEST;
434
435
436	/**
437	* Verify the given SHA1 digests against the entries in the manifest file.
438	*
439	* Please note that not only the various digest have to match, but the
440	* filenames as well. If there are more or even less files listed in the
441	* manifest file than provided by paTests, VERR_MANIFEST_FILE_MISMATCH will be
442	* returned.
443	*
444	* @returns iprt status code.
445	*
446	* @param pszManifestFile Filename of the manifest file to verify.
447	* @param paTests Array of files & SHA1 sums.
448	* @param cTests Number of entries in paTests.
449	* @param piFailed A index to paTests in the
450	* VERR_MANIFEST_DIGEST_MISMATCH error case
451	* (optional).
452	* @deprecated Use the RTMANIFEST based API instead.
453	*/
454	RTR3DECL(int) RTManifestVerify(const char pszManifestFile, PRTMANIFESTTEST paTests, size_t cTests, size_t piFailed);
455
456	/**
457	* This is analogous to function RTManifestVerify(), but calculates the SHA1
458	* sums of the given files itself.
459	*
460	* @returns iprt status code.
461	*
462	* @param pszManifestFile Filename of the manifest file to verify.
463	* @param papszFiles Array of files to check SHA1 sums.
464	* @param cFiles Number of entries in papszFiles.
465	* @param piFailed A index to papszFiles in the
466	* VERR_MANIFEST_DIGEST_MISMATCH error case
467	* (optional).
468	* @param pfnProgressCallback optional callback for the progress indication
469	* @param pvUser user defined pointer for the callback
470	* @deprecated Use the RTMANIFEST based API instead.
471	*/
472	RTR3DECL(int) RTManifestVerifyFiles(const char pszManifestFile, const char const papszFiles, size_t cFiles, size_t piFailed,
473	PFNRTPROGRESS pfnProgressCallback, void *pvUser);
474
475	/**
476	* Creates a manifest file for a set of files. The manifest file contains SHA1
477	* sums of every provided file and could be used to verify the data integrity
478	* of them.
479	*
480	* @returns iprt status code.
481	*
482	* @param pszManifestFile Filename of the manifest file to create.
483	* @param enmDigestType The digest type (RTDIGESTTYPE_*)
484	* @param papszFiles Array of files to create SHA1 sums for.
485	* @param cFiles Number of entries in papszFiles.
486	* @param pfnProgressCallback optional callback for the progress indication
487	* @param pvUser user defined pointer for the callback
488	* @deprecated Use the RTMANIFEST based API instead.
489	*/
490	RTR3DECL(int) RTManifestWriteFiles(const char *pszManifestFile, RTDIGESTTYPE enmDigestType,
491	const char * const *papszFiles, size_t cFiles,
492	PFNRTPROGRESS pfnProgressCallback, void *pvUser);
493
494	/**
495	* Queries the first digest type found in the given manifest.
496	*
497	* @returns iprt status code.
498	*
499	* @param pvBuf Pointer to memory buffer of the manifest file.
500	* @param cbSize Size of the memory buffer.
501	* @param penmDigestType Where to return the first digest type found in
502	* the manifest.
503	* @deprecated Use the RTMANIFEST based API instead.
504	*/
505	RTR3DECL(int) RTManifestVerifyDigestType(void const pvBuf, size_t cbSize, RTDIGESTTYPE penmDigestType);
506
507	/**
508	* Verify the given SHA1 digests against the entries in the manifest file in
509	* memory.
510	*
511	* @returns iprt status code.
512	*
513	* @param pvBuf Pointer to memory buffer of the manifest file.
514	* @param cbSize Size of the memory buffer.
515	* @param paTests Array of file names and digests.
516	* @param cTest Number of entries in paTests.
517	* @param piFailed A index to paTests in the
518	* VERR_MANIFEST_DIGEST_MISMATCH error case
519	* (optional).
520	* @deprecated Use the RTMANIFEST based API instead.
521	*/
522	RTR3DECL(int) RTManifestVerifyFilesBuf(void pvBuf, size_t cbSize, PRTMANIFESTTEST paTests, size_t cTests, size_t piFailed);
523
524	/**
525	* Creates a manifest file in memory for a set of files. The manifest file
526	* contains SHA1 sums of every provided file and could be used to verify the
527	* data integrity of them.
528	*
529	* @returns iprt status code.
530	*
531	* @param ppvBuf Pointer to resulting memory buffer.
532	* @param pcbSize Pointer for the size of the memory buffer.
533	* @param enmDigestType Which type of digest ("SHA1", "SHA256", ...)
534	* @param paFiles Array of file names and digests.
535	* @param cFiles Number of entries in paFiles.
536	* @deprecated Use the RTMANIFEST based API instead.
537	*/
538	RTR3DECL(int) RTManifestWriteFilesBuf(void *ppvBuf, size_t pcbSize, RTDIGESTTYPE enmDigestType, PRTMANIFESTTEST paFiles, size_t cFiles);
539
540	/** @} */
541
542	RT_C_DECLS_END
543
544	#endif
545

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

source: vbox/trunk/include/iprt/manifest.h@ 47241

Download in other formats: