VirtualBox

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

Last change on this file since 73768 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
32RT_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 */
68RTDECL(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 */
76RTDECL(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 */
86RTDECL(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 */
95RTDECL(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 */
115RTDECL(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 */
141RTDECL(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 */
152RTDECL(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 */
167RTDECL(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 */
178RTDECL(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 */
201RTDECL(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 */
221RTDECL(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 */
234RTDECL(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 */
259RTDECL(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 */
283RTDECL(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 */
292RTDECL(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 */
311RTDECL(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 */
321RTDECL(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 */
329RTDECL(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 */
345RTDECL(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 */
354RTDECL(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 */
367RTDECL(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 */
383RTDECL(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 */
396RTDECL(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 */
408RTDECL(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 */
417RTDECL(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 */
427typedef 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. */
435typedef 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 */
456RTR3DECL(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 */
474RTR3DECL(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 */
492RTR3DECL(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 */
507RTR3DECL(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 */
524RTR3DECL(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 */
540RTR3DECL(int) RTManifestWriteFilesBuf(void **ppvBuf, size_t *pcbSize, RTDIGESTTYPE enmDigestType, PRTMANIFESTTEST paFiles, size_t cFiles);
541
542/** @} */
543
544RT_C_DECLS_END
545
546#endif
547
Note: See TracBrowser for help on using the repository browser.

© 2023 Oracle
Contact – Privacy policy – Terms of Use