manifest.h@ 71755

Last change on this file since 71755 was 69105, checked in by vboxsync, 7 years ago
include/iprt/: (C) year
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 21.7 KB

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

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

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

Download in other formats: