path: root/lib/header.h

#ifndef H_HEADER
#define H_HEADER

/** \ingroup header
 * \file lib/header.h
 *
 * An rpm header carries all information about a package. A header is
 * a collection of data elements called tags. Each tag has a data type,
 * and includes 1 or more values.
 * 
 */

/* RPM - Copyright (C) 1995-2001 Red Hat Software */

#include <rpm/rpmio.h>
#include <rpm/rpmtypes.h>
#include <rpm/rpmtd.h>
#include <rpm/rpmutil.h>

#ifdef __cplusplus
extern "C" {
#endif

/** \ingroup header 
 * Header magic value
 */ 
extern const unsigned char rpm_header_magic[8];

/** \ingroup header
 * Include calculation for 8 bytes of (magic, 0)?
 */
enum hMagic {
    HEADER_MAGIC_NO		= 0,
    HEADER_MAGIC_YES		= 1
};

/** \ingroup header
 * Create new (empty) header instance.
 * @return		header
 */
Header headerNew(void);

/** \ingroup header
 * Dereference a header instance.
 * @param h		header
 * @return		NULL always
 */
Header headerFree( Header h);

/** \ingroup header
 * Reference a header instance.
 * @param h		header
 * @return		new header reference
 */
Header headerLink(Header h);

/** \ingroup header
 * Sort tags in header.
 * @param h		header
 */
void headerSort(Header h);

/** \ingroup header
 * Restore tags in header to original ordering.
 * @param h		header
 */
void headerUnsort(Header h);

/** \ingroup header
 * Return size of on-disk header representation in bytes.
 * @param h		header
 * @param magicp	include size of 8 bytes for (magic, 0)?
 * @return		size of on-disk header
 */
unsigned int headerSizeof(Header h, int magicp);

/** \ingroup header
 * Perform simple sanity and range checks on header tag(s).
 * @param il		no. of tags in header
 * @param dl		no. of bytes in header data.
 * @param pev		1st element in tag array, big-endian
 * @param iv		failing (or last) tag element, host-endian
 * @param negate	negative offset expected?
 * @return		-1 on success, otherwise failing tag element index
 */
int headerVerifyInfo(int il, int dl, const void * pev, void * iv, int negate);

/** \ingroup header
 * Convert header to on-disk representation.
 * @deprecated		Use headerExport() instead
 * @param h		header (with pointers)
 * @return		on-disk header blob (i.e. with offsets)
 */
void * headerUnload(Header h);

/** \ingroup header
 * Export header to on-disk representation.
 * @param h		header (with pointers)
 * @retval bsize	on-disk header blob size in bytes
 * @return		on-disk header blob (i.e. with offsets)
 */
void * headerExport(Header h, unsigned int * bsize);

/** \ingroup header
 * Convert header to on-disk representation, and then reload.
 * This is used to insure that all header data is in one chunk.
 * @param h		header (with pointers)
 * @param tag		region tag
 * @return		on-disk header (with offsets)
 */
Header headerReload(Header h, rpmTagVal tag);

/** \ingroup header
 * Duplicate a header.
 * @param h		header
 * @return		new header instance
 */
Header headerCopy(Header h);

/** \ingroup header
 * Convert header to in-memory representation.
 * @deprecated		Use headerImport() instead
 * @param uh		on-disk header blob (i.e. with offsets)
 * @return		header
 */
Header headerLoad(void * uh);

/** \ingroup header
 * Make a copy and convert header to in-memory representation.
 * @deprecated		Use headerImport() instead
 * @param uh		on-disk header blob (i.e. with offsets)
 * @return		header
 */
Header headerCopyLoad(const void * uh);

enum headerImportFlags_e {
    HEADERIMPORT_COPY		= (1 << 0), /* Make copy of blob on import? */
    HEADERIMPORT_FAST		= (1 << 1), /* Faster but less safe? */
};

typedef rpmFlags headerImportFlags;

/** \ingroup header
 * Import header to in-memory representation.
 * @param blob		on-disk header blob (i.e. with offsets)
 * @param bsize		on-disk header blob size in bytes (0 if unknown)
 * @param flags		flags to control operation
 * @return		header
 */
Header headerImport(void *blob, unsigned int bsize, headerImportFlags flags);

/** \ingroup header
 * Read (and load) header from file handle.
 * @param fd		file handle
 * @param magicp	read (and verify) 8 bytes of (magic, 0)?
 * @return		header (or NULL on error)
 */
Header headerRead(FD_t fd, int magicp);

/** \ingroup header
 * Write (with unload) header to file handle.
 * @param fd		file handle
 * @param h		header
 * @param magicp	prefix write with 8 bytes of (magic, 0)?
 * @return		0 on success, 1 on error
 */
int headerWrite(FD_t fd, Header h, int magicp);

/** \ingroup header
 * Check if tag is in header.
 * @param h		header
 * @param tag		tag
 * @return		1 on success, 0 on failure
 */
int headerIsEntry(Header h, rpmTagVal tag);

/** \ingroup header
 * Modifier flags for headerGet() operation.
 * For consistent behavior you'll probably want to use ALLOC to ensure
 * the caller owns the data, but MINMEM is useful for avoiding extra
 * copy of data when you are sure the header wont go away.
 * Most of the time you'll probably want EXT too, but note that extensions 
 * tags don't generally honor the other flags, MINMEM, RAW, ALLOC and ARGV 
 * are only relevant for non-extension data.
 */
enum headerGetFlags_e {
    HEADERGET_DEFAULT	= 0,	    /* legacy headerGetEntry() behavior */
    HEADERGET_MINMEM 	= (1 << 0), /* pointers can refer to header memory */
    HEADERGET_EXT 	= (1 << 1), /* lookup extension types too */
    HEADERGET_RAW 	= (1 << 2), /* return raw contents (no i18n lookups) */
    HEADERGET_ALLOC	= (1 << 3), /* always allocate memory for all data */
    HEADERGET_ARGV	= (1 << 4), /* return string arrays NULL-terminated */
};

typedef rpmFlags headerGetFlags;

/** \ingroup header
 * Retrieve tag value.
 * @param h		header
 * @param tag		tag
 * @retval td		tag data container
 * @param flags		retrieval modifier flags
 * @return		1 on success, 0 on failure
 */
int headerGet(Header h, rpmTagVal tag, rpmtd td, headerGetFlags flags);


enum headerPutFlags_e {
    HEADERPUT_DEFAULT	= 0,
    HEADERPUT_APPEND 	= (1 << 0),
};

typedef rpmFlags headerPutFlags;

/** \ingroup header
 * Add or append tag to header.
 *
 * @param h		header
 * @param td		tag data container
 * @param flags		flags to control operation
 * @return		1 on success, 0 on failure
 */
int headerPut(Header h, rpmtd td, headerPutFlags flags);

/** \ingroup header 
 * @{
 * Type-safe methods for inserting tag data to header.
 * Tag data type is validated to match the function type, ie things like
 * headerPutUint32(h, RPMTAG_NAME, ...) will return failure. For non-array
 * types size must equal 1, and data is checked to be non-NULL. For array
 * types, add-or-append mode is always used.
 *
 * headerPutString() can be used on both RPM_STRING_TYPE and 
 * RPM_STRING_ARRAY_TYPE (to add a single string into the array) tags,
 * for others the type must match exactly.
 *
 * These are intended to "do the right thing" in the common case, if you 
 * need more fine grained control use headerPut() & friends instead.
 * @todo		Make doxygen group these meaningfully.
 *
 * @param h		header
 * @param tag		tag to insert
 * @param val		pointer to value(s)
 * @param size		number of items in array (1 or larger)
 * @return		1 on success, 0 on failure
 * 
 */
int headerPutString(Header h, rpmTagVal tag, const char *val);
int headerPutStringArray(Header h, rpmTagVal tag, const char **val, rpm_count_t size);
int headerPutBin(Header h, rpmTagVal tag, const uint8_t *val, rpm_count_t size);
int headerPutChar(Header h, rpmTagVal tag, const char *val, rpm_count_t size);
int headerPutUint8(Header h, rpmTagVal tag, const uint8_t *val, rpm_count_t size);
int headerPutUint16(Header h, rpmTagVal tag, const uint16_t *val, rpm_count_t size);
int headerPutUint32(Header h, rpmTagVal tag, const uint32_t *val, rpm_count_t size);
int headerPutUint64(Header h, rpmTagVal tag, const uint64_t *val, rpm_count_t size);
/** @} */

/** \ingroup header
 * Add locale specific tag to header.
 * A NULL lang is interpreted as the C locale. Here are the rules:
 * \verbatim
 *	- If the tag isn't in the header, it's added with the passed string
 *	   as new value.
 *	- If the tag occurs multiple times in entry, which tag is affected
 *	   by the operation is undefined.
 *	- If the tag is in the header w/ this language, the entry is
 *	   *replaced* (like headerMod()).
 * \endverbatim
 * This function is intended to just "do the right thing". If you need
 * more fine grained control use headerPut() and headerMod().
 *
 * @param h		header
 * @param tag		tag
 * @param string	tag value
 * @param lang		locale
 * @return		1 on success, 0 on failure
 */
int headerAddI18NString(Header h, rpmTagVal tag, const char * string,
		const char * lang);

/** \ingroup header
 * Modify tag in header.
 * If there are multiple entries with this tag, the first one gets replaced.
 * @param h		header
 * @param td		tag data container
 * @return		1 on success, 0 on failure
 */
int headerMod(Header h, rpmtd td);

/** \ingroup header
 * Delete tag in header.
 * Removes all entries of type tag from the header, returns 1 if none were
 * found.
 *
 * @param h		header
 * @param tag		tag
 * @return		0 on success, 1 on failure (INCONSISTENT)
 */
int headerDel(Header h, rpmTagVal tag);

/** \ingroup header
 * Return formatted output string from header tags.
 * The returned string must be free()d.
 *
 * @param h		header
 * @param fmt		format to use
 * @retval errmsg	error message (if any)
 * @return		formatted output string (malloc'ed)
 */
char * headerFormat(Header h, const char * fmt, errmsg_t * errmsg);

/** \ingroup header
 * Duplicate tag values from one header into another.
 * @param headerFrom	source header
 * @param headerTo	destination header
 * @param tagstocopy	array of tags that are copied
 */
void headerCopyTags(Header headerFrom, Header headerTo, 
		    const rpmTagVal * tagstocopy);

/** \ingroup header
 * Destroy header tag iterator.
 * @param hi		header tag iterator
 * @return		NULL always
 */
HeaderIterator headerFreeIterator(HeaderIterator hi);

/** \ingroup header
 * Create header tag iterator.
 * @param h		header
 * @return		header tag iterator
 */
HeaderIterator headerInitIterator(Header h);

/** \ingroup header
 * Return next tag contents from header.
 * @param hi		header tag iterator
 * @retval td		tag data container
 * @return		1 on success, 0 on failure
 */
int headerNext(HeaderIterator hi, rpmtd td);

/** \ingroup header
 * Return next tag number from header.
 * @param hi		header tag iterator
 * @return		next tag, RPMTAG_NOT_FOUND to stop iteration
 */
rpmTagVal headerNextTag(HeaderIterator hi);

/** \ingroup header
 * Return name, version, release strings from header.
 * @param h		header
 * @retval *np		name pointer (or NULL)
 * @retval *vp		version pointer (or NULL)
 * @retval *rp		release pointer (or NULL)
 * @return		0 always
 */
RPM_GNUC_DEPRECATED
int headerNVR(Header h,
		const char ** np,
		const char ** vp,
		const char ** rp);

/** \ingroup header
 * Return name, epoch, version, release, arch strings from header.
 * @param h		header
 * @retval *np		name pointer (or NULL)
 * @retval *ep		epoch pointer (or NULL)
 * @retval *vp		version pointer (or NULL)
 * @retval *rp		release pointer (or NULL)
 * @retval *ap		arch pointer (or NULL)
 * @return		0 always
 */
RPM_GNUC_DEPRECATED
int headerNEVRA(Header h,
		const char ** np,
		uint32_t ** ep,
		const char ** vp,
		const char ** rp,
		const char ** ap);

/** \ingroup header
 * Return (malloc'd) header name-version-release string.
 * @param h		header
 * @retval np		name tag value
 * @return		name-version-release string
 */
RPM_GNUC_DEPRECATED
char * headerGetNEVR(Header h, const char ** np );

/** \ingroup header
 * Return (malloc'd) header name-version-release.arch string.
 * @param h		header
 * @retval np		name tag value
 * @return		name-version-release string
 */
RPM_GNUC_DEPRECATED
char * headerGetNEVRA(Header h, const char ** np );

/* \ingroup header
 * Return (malloc'd) header (epoch:)version-release string.
 * @param h		header
 * @retval np		name tag value (or NULL)
 * @return             (epoch:)version-release string
 */
RPM_GNUC_DEPRECATED
char * headerGetEVR(Header h, const char **np);

/** \ingroup header
 * Return any non-array tag from header, converted to string
 * @param h		header
 * @param tag		tag to retrieve
 * @return 		string pointer (malloced) or NULL on failure
 */
char * headerGetAsString(Header h, rpmTagVal tag);

/** \ingroup header
 * Return a simple string tag from header
 * @param h		header
 * @param tag		tag to retrieve
 * @return		string pointer (to header memory) or NULL on failure
 */
const char * headerGetString(Header h, rpmTagVal tag);

/* \ingroup header
 * Return a simple number tag (or extension) from header
 * @param h		header
 * @param tag		tag to retrieve
 * @return		numeric tag value or 0 on failure
 */
uint64_t headerGetNumber(Header h, rpmTagVal tag);

/** \ingroup header
 * Return header color.
 * @param h		header
 * @return		header color
 */
RPM_GNUC_DEPRECATED
rpm_color_t headerGetColor(Header h);

/** \ingroup header
 * Check if header is a source or binary package header
 * @param h		header
 * @return		0 == binary, 1 == source
 */
int headerIsSource(Header h);

/** \ingroup header
 * Return header instance, ie is the header from rpmdb.
 * @param h		header
 * @return		rpmdb record number or 0
 */
unsigned int headerGetInstance(Header h);

typedef enum headerConvOps_e {
    HEADERCONV_EXPANDFILELIST	= 0,
    HEADERCONV_COMPRESSFILELIST = 1,
    HEADERCONV_RETROFIT_V3	= 2,
} headerConvOps;

/** \ingroup header
 * Convert header to/from (legacy) data presentation
 * @param h		header
 * @param op		one of headerConvOps operations
 * @return		1 on success, 0 on failure
 */
int headerConvert(Header h, int op);

#ifdef __cplusplus
}
#endif

#endif	/* H_HEADER */