manifest.h revision 835ac9173220411ef9fe578c3d4c03e5edfa20be
/** @file
* IPRT - Manifest file handling.
*/
/*
* Copyright (C) 2009 Oracle Corporation
*
* This file is part of VirtualBox Open Source Edition (OSE), as
* available from http://www.virtualbox.org. This file is free software;
* General Public License (GPL) as published by the Free Software
* Foundation, in version 2 as it comes in the "COPYING" file of the
* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
*
* The contents of this file may alternatively be used under the terms
* of the Common Development and Distribution License Version 1.0
* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
* VirtualBox OSE distribution, in which case the provisions of the
* CDDL are applicable instead of those of the GPL.
*
* You may elect to license modified versions of this file under the
* terms and conditions of either the GPL or the CDDL or both.
*/
#ifndef ___iprt_manifest_h
#define ___iprt_manifest_h
/** @defgroup grp_rt_manifest RTManifest - Manifest file creation and checking
* @ingroup grp_rt
* @{
*/
/** @name Manifest attribute types.
* The types can be ORed together to form a set.
* @{ */
/** For use with other attributes. Representation unknown. */
#define RTMANIFEST_ATTR_UNKNOWN 0
/** The size of the content. Represented as a decimal number. */
#define RTMANIFEST_ATTR_SIZE RT_BIT_32(0)
/** The MD5 of the content. Represented as a hex string. */
/** The SHA-1 of the content. Represented as a hex string. */
/** The SHA-256 of the content. Represented as a hex string. */
/** The SHA-512 of the content. Represented as a hex string. */
/** The end of the valid values. */
/** @} */
/**
* Creates an empty manifest.
*
* @returns IPRT status code.
* @param fFlags Flags, MBZ.
* @param phManifest Where to return the handle to the manifest.
*/
/**
* Retains a reference to the manifest handle.
*
* @returns The new reference count, UINT32_MAX if the handle is invalid.
* @param hManifest The handle to retain.
*/
/**
* Releases a reference to the manifest handle.
*
* @returns The new reference count, 0 if free. UINT32_MAX is returned if the
* handle is invalid.
* @param hManifest The handle to release.
* NIL is quietly ignored (returns 0).
*/
/**
* Creates a duplicate of the specified manifest.
*
* @returns IPRT status code
* @param hManifestSrc The manifest to clone.
* @param phManifestDst Where to store the handle to the duplicate.
*/
/**
* Compares two manifests for equality.
*
* @returns IPRT status code.
* @retval VINF_SUCCESS if equal.
* @retval VERR_NOT_EQUAL if not equal.
*
* @param hManifest1 The first manifest.
* @param hManifest2 The second manifest.
* @param papszIgnoreEntries Entries to ignore. Ends with a NULL entry.
* @param papszIgnoreAttrs Attributes to ignore. Ends with a NULL entry.
* @param pszEntry Where to store the name of the mismatching
* entry, or as much of the name as there is room
* for. This is always set. Optional.
* @param cbEntry The size of the buffer pointed to by @a
* pszEntry.
*/
RTDECL(int) RTManifestEqualsEx(RTMANIFEST hManifest1, RTMANIFEST hManifest2, const char * const *papszIgnoreEntries,
/**
* Compares two manifests for equality.
*
* @returns IPRT status code.
* @retval VINF_SUCCESS if equal.
* @retval VERR_NOT_EQUAL if not equal.
*
* @param hManifest1 The first manifest.
* @param hManifest2 The second manifest.
*/
/**
* Sets a manifest attribute.
*
* @returns IPRT status code.
* @param hManifest The manifest handle.
* @param pszAttr The attribute name. If this already exists,
* its value will be replaced.
* @param pszValue The value string.
* @param fType The attribute type, pass
* RTMANIFEST_ATTR_UNKNOWN if not known.
*/
RTDECL(int) RTManifestSetAttr(RTMANIFEST hManifest, const char *pszAttr, const char *pszValue, uint32_t fType);
/**
* Unsets (removes) a manifest attribute if it exists.
*
* @returns IPRT status code.
* @retval VWRN_NOT_FOUND if not found.
*
* @param hManifest The manifest handle.
* @param pszAttr The attribute name.
*/
/**
* Sets an attribute of a manifest entry.
*
* @returns IPRT status code.
* @param hManifest The manifest handle.
* @param pszEntry The entry name. This will automatically be
* added if there was no previous call to
* RTManifestEntryAdd for this name. See
* RTManifestEntryAdd for the entry name rules.
* @param pszAttr The attribute name. If this already exists,
* its value will be replaced.
* @param pszValue The value string.
* @param fType The attribute type, pass
* RTMANIFEST_ATTR_UNKNOWN if not known.
*/
/**
* Unsets (removes) an attribute of a manifest entry if they both exist.
*
* @returns IPRT status code.
* @retval VWRN_NOT_FOUND if not found.
*
* @param hManifest The manifest handle.
* @param pszEntry The entry name.
* @param pszAttr The attribute name.
*/
RTDECL(int) RTManifestEntryUnsetAttr(RTMANIFEST hManifest, const char *pszEntry, const char *pszAttr);
/**
* Adds a new entry to a manifest.
*
* The entry name rules:
* - The entry name can contain any character defined by unicode, except
* control characters, ':', '(' and ')'. The exceptions are mainly there
* because of uncertainty around how various formats handles these.
* - It is considered case sensitive.
* - Forward (unix) and backward (dos) slashes are considered path
* separators and converted to forward slashes.
*
* @returns IPRT status code.
* @retval VWRN_ALREADY_EXISTS if the entry already exists.
*
* @param hManifest The manifest handle.
* @param pszEntry The entry name (UTF-8).
*
* @remarks Some manifest formats will not be able to store an entry without
* any attributes. So, this is just here in case it comes in handy
* when dealing with formats which can.
*/
/**
* Removes an entry.
*
* @returns IPRT status code.
* @param hManifest The manifest handle.
* @param pszEntry The entry name.
*/
/**
* Add an entry for an I/O stream using a passthru stream.
*
* The passthru I/O stream will hash all the data read from or written to the
* stream and automatically add an entry to the manifest with the desired
* attributes when it is released. Alternatively one can call
* RTManifestPtIosAddEntryNow() to have more control over exactly when this
* action is performed and which status it yields.
*
* @returns IPRT status code.
* @param hManifest The manifest to add the entry to.
* @param pszEntry The entry name.
* @param fAttrs The attributes to create for this stream.
* @param fReadOrWrite Whether it's a read or write I/O stream.
* @param phVfsIosPassthru Where to return the new handle.
*/
RTDECL(int) RTManifestEntryAddPassthruIoStream(RTMANIFEST hManifest, RTVFSIOSTREAM hVfsIos, const char *pszEntry,
/**
* Adds the entry to the manifest right now.
*
* @returns IPRT status code.
* @param hVfsPtIos The manifest passthru I/O stream returned by
* RTManifestEntryAddPassthruIoStream().
*/
/**
* Adds an entry for a file with the specified set of attributes.
*
* @returns IPRT status code.
*
* @param hManifest The manifest handle.
* @param hVfsIos The I/O stream handle of the entry. This will
* be processed to its end on successful return.
* (Must be positioned at the start to get
* the expected results.)
* @param pszEntry The entry name.
* @param fAttrs The attributes to create for this stream. See
* RTMANIFEST_ATTR_XXX.
*/
RTDECL(int) RTManifestEntryAddIoStream(RTMANIFEST hManifest, RTVFSIOSTREAM hVfsIos, const char *pszEntry, uint32_t fAttrs);
/**
* Reads in a "standard" manifest.
*
* This reads the format used by OVF, the distinfo in FreeBSD ports, and
* others.
*
* @returns IPRT status code.
* @param hManifest The handle to the manifest where to add the
* manifest that's read in.
* @param hVfsIos The I/O stream to read the manifest from.
*/
/**
* Writes a "standard" manifest.
*
* This writes the format used by OVF, the distinfo in FreeBSD ports, and
* others.
*
* @returns IPRT status code.
* @param hManifest The handle to the manifest where to add the
* manifest that's read in.
* @param hVfsIos The I/O stream to read the manifest from.
*/
/**
* Input structure for RTManifestVerify() which contains the filename & the
* SHA1 digest.
*/
typedef struct RTMANIFESTTEST
{
/** The filename. */
const char *pszTestFile;
/** The SHA1 digest of the file. */
const char *pszTestDigest;
/** Pointer to the input structure. */
typedef RTMANIFESTTEST* PRTMANIFESTTEST;
/**
* Verify the given SHA1 digests against the entries in the manifest file.
*
* Please note that not only the various digest have to match, but the
* filenames as well. If there are more or even less files listed in the
* manifest file than provided by paTests, VERR_MANIFEST_FILE_MISMATCH will be
* returned.
*
* @returns iprt status code.
*
* @param pszManifestFile Filename of the manifest file to verify.
* @param paTests Array of files & SHA1 sums.
* @param cTests Number of entries in paTests.
* @param piFailed A index to paTests in the
* VERR_MANIFEST_DIGEST_MISMATCH error case
* (optional).
*/
RTR3DECL(int) RTManifestVerify(const char *pszManifestFile, PRTMANIFESTTEST paTests, size_t cTests, size_t *piFailed);
/**
* This is analogous to function RTManifestVerify(), but calculates the SHA1
* sums of the given files itself.
*
* @returns iprt status code.
*
* @param pszManifestFile Filename of the manifest file to verify.
* @param papszFiles Array of files to check SHA1 sums.
* @param cFiles Number of entries in papszFiles.
* @param piFailed A index to papszFiles in the
* VERR_MANIFEST_DIGEST_MISMATCH error case
* (optional).
* @param pfnProgressCallback optional callback for the progress indication
* @param pvUser user defined pointer for the callback
*/
RTR3DECL(int) RTManifestVerifyFiles(const char *pszManifestFile, const char * const *papszFiles, size_t cFiles, size_t *piFailed,
/**
* Creates a manifest file for a set of files. The manifest file contains SHA1
* sums of every provided file and could be used to verify the data integrity
* of them.
*
* @returns iprt status code.
*
* @param pszManifestFile Filename of the manifest file to create.
* @param papszFiles Array of files to create SHA1 sums for.
* @param cFiles Number of entries in papszFiles.
* @param pfnProgressCallback optional callback for the progress indication
* @param pvUser user defined pointer for the callback
*/
RTR3DECL(int) RTManifestWriteFiles(const char *pszManifestFile, const char * const *papszFiles, size_t cFiles,
/**
* Verify the given SHA1 digests against the entries in the manifest file in
* memory.
*
* @returns iprt status code.
*
* @param pvBuf Pointer to memory buffer of the manifest file.
* @param cbSize Size of the memory buffer.
* @param paTests Array of file names and digests.
* @param cTest Number of entries in paTests.
* @param piFailed A index to paTests in the
* VERR_MANIFEST_DIGEST_MISMATCH error case
* (optional).
*/
RTR3DECL(int) RTManifestVerifyFilesBuf(void *pvBuf, size_t cbSize, PRTMANIFESTTEST paTests, size_t cTests, size_t *piFailed);
/**
* Creates a manifest file in memory for a set of files. The manifest file
* contains SHA1 sums of every provided file and could be used to verify the
* data integrity of them.
*
* @returns iprt status code.
*
* @param ppvBuf Pointer to resulting memory buffer.
* @param pcbSize Pointer for the size of the memory buffer.
* @param paFiles Array of file names and digests.
* @param cFiles Number of entries in paFiles.
*/
RTR3DECL(int) RTManifestWriteFilesBuf(void **ppvBuf, size_t *pcbSize, PRTMANIFESTTEST paFiles, size_t cFiles);
/** @} */
#endif