VirtualBox

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

Last change on this file since 77807 was 76585, checked in by vboxsync, 6 years ago

*: scm --fix-header-guard-endif
  • 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-2019 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
35RT_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 */
71RTDECL(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 */
79RTDECL(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 */
89RTDECL(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 */
98RTDECL(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 */
118RTDECL(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 */
144RTDECL(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 */
155RTDECL(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 */
170RTDECL(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 */
181RTDECL(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 */
204RTDECL(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 */
224RTDECL(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 */
237RTDECL(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 */
262RTDECL(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 */
286RTDECL(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 */
295RTDECL(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 */
314RTDECL(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 */
324RTDECL(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 */
332RTDECL(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 */
348RTDECL(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 */
357RTDECL(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 */
370RTDECL(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 */
386RTDECL(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 */
399RTDECL(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 */
411RTDECL(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 */
420RTDECL(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 */
430typedef 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. */
438typedef 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 */
459RTR3DECL(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 */
477RTR3DECL(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 */
495RTR3DECL(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 */
510RTR3DECL(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 */
527RTR3DECL(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 */
543RTR3DECL(int) RTManifestWriteFilesBuf(void **ppvBuf, size_t *pcbSize, RTDIGESTTYPE enmDigestType, PRTMANIFESTTEST paFiles, size_t cFiles);
544
545/** @} */
546
547RT_C_DECLS_END
548
549#endif /* !IPRT_INCLUDED_manifest_h */
550
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle
Contact – Privacy/Do Not Sell My Info – Terms of Use