manifest.h@ 95897

Last change on this file since 95897 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: 21.8 KB

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

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

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

Download in other formats: