heif_items.h File Reference

#include "heif_library.h"
#include "heif_error.h"
#include "heif_metadata.h"

Include dependency graph for heif_items.h:

Go to the source code of this file.

Macros
#define	heif_item_type_mime   heif_fourcc('m','i','m','e')
#define	heif_item_type_uri   heif_fourcc('u','r','i',' ')
#define	heif_item_type_exif   heif_fourcc('E','x','i','f')
#define	heif_item_type_grid   heif_fourcc('g','r','i','d')
#define	heif_item_type_hvc1   heif_fourcc('h','v','c','1')
#define	heif_item_type_unci   heif_fourcc('u','n','c','i')
#define	heif_item_type_av01   heif_fourcc('a','v','0','1')
#define	heif_item_type_avc1   heif_fourcc('a','v','c','1')

Functions
int	heif_context_get_number_of_items (const heif_context *ctx)
	Gets the number of items.
int	heif_context_get_list_of_item_IDs (const heif_context *ctx, heif_item_id *ID_array, int count)
	Get the item identifiers.
uint32_t	heif_item_get_item_type (const heif_context *ctx, heif_item_id item_id)
	Gets the item type.
int	heif_item_is_item_hidden (const heif_context *ctx, heif_item_id item_id)
const char *	heif_item_get_mime_item_content_type (const heif_context *ctx, heif_item_id item_id)
	Gets the MIME content_type for an item.
const char *	heif_item_get_mime_item_content_encoding (const heif_context *ctx, heif_item_id item_id)
	Gets the content_encoding for a MIME item.
const char *	heif_item_get_uri_item_uri_type (const heif_context *ctx, heif_item_id item_id)
	Gets the item_uri_type for an item.
const char *	heif_item_get_item_name (const heif_context *ctx, heif_item_id item_id)
heif_error	heif_item_set_item_name (heif_context *ctx, heif_item_id item, const char *item_name)
heif_error	heif_item_get_item_data (const heif_context *ctx, heif_item_id item_id, enum heif_metadata_compression *out_compression_format, uint8_t **out_data, size_t *out_data_size)
	Gets the raw metadata, as stored in the HEIF file.
void	heif_release_item_data (const heif_context *ctx, uint8_t **item_data)
	Free the item data.
heif_error	heif_item_get_property_extended_language (const heif_context *context, heif_item_id itemId, char **out_language)
	Get the extended language associated with the item.
heif_error	heif_item_set_property_extended_language (heif_context *context, heif_item_id item_id, const char *language, heif_property_id *out_optional_propertyId)
size_t	heif_context_get_item_references (const heif_context *ctx, heif_item_id from_item_id, int index, uint32_t *out_reference_type_4cc, heif_item_id **out_references_to)
	Get the item ids that reference the given item.
void	heif_release_item_references (const heif_context *ctx, heif_item_id **references)
heif_error	heif_context_add_item_reference (heif_context *ctx, uint32_t reference_type, heif_item_id from_item, heif_item_id to_item)
heif_error	heif_context_add_item_references (heif_context *ctx, uint32_t reference_type, heif_item_id from_item, const heif_item_id *to_item, int num_to_items)
heif_error	heif_context_add_item (heif_context *ctx, const char *item_type, const void *data, int size, heif_item_id *out_item_id)
	Add an item with an arbitrary four-character item type (e.g.
heif_error	heif_context_add_mime_item (heif_context *ctx, const char *content_type, enum heif_metadata_compression content_encoding, const void *data, int size, heif_item_id *out_item_id)
	Add a 'mime' item, optionally compressing the payload.
heif_error	heif_context_add_precompressed_mime_item (heif_context *ctx, const char *content_type, const char *content_encoding, const void *data, int size, heif_item_id *out_item_id)
	Add a 'mime' item whose payload has already been compressed by the caller.
heif_error	heif_context_add_uri_item (heif_context *ctx, const char *item_uri_type, const void *data, int size, heif_item_id *out_item_id)
	Add a 'uri ' item.

Macro Definition Documentation

heif_item_type_av01

#define heif_item_type_av01   heif_fourcc('a','v','0','1')

heif_item_type_avc1

#define heif_item_type_avc1   heif_fourcc('a','v','c','1')

heif_item_type_exif

#define heif_item_type_exif   heif_fourcc('E','x','i','f')

heif_item_type_grid

#define heif_item_type_grid   heif_fourcc('g','r','i','d')

heif_item_type_hvc1

#define heif_item_type_hvc1   heif_fourcc('h','v','c','1')

heif_item_type_mime

#define heif_item_type_mime   heif_fourcc('m','i','m','e')

heif_item_type_unci

#define heif_item_type_unci   heif_fourcc('u','n','c','i')

heif_item_type_uri

#define heif_item_type_uri   heif_fourcc('u','r','i',' ')

Function Documentation

heif_context_add_item()

heif_error heif_context_add_item	(	heif_context *	ctx,
		const char *	item_type,
		const void *	data,
		int	size,
		heif_item_id *	out_item_id )

Add an item with an arbitrary four-character item type (e.g.

"Exif").

Parameters

ctx	the file context
item_type	four-character item type
data	the item payload
size	number of bytes in 'data'
out_item_id	receives the ID of the new item (may be NULL)

heif_context_add_item_reference()

heif_error heif_context_add_item_reference	(	heif_context *	ctx,
		uint32_t	reference_type,
		heif_item_id	from_item,
		heif_item_id	to_item )

heif_context_add_item_references()

heif_error heif_context_add_item_references	(	heif_context *	ctx,
		uint32_t	reference_type,
		heif_item_id	from_item,
		const heif_item_id *	to_item,
		int	num_to_items )

heif_context_add_mime_item()

heif_error heif_context_add_mime_item	(	heif_context *	ctx,
		const char *	content_type,
		enum heif_metadata_compression	content_encoding,
		const void *	data,
		int	size,
		heif_item_id *	out_item_id )

Add a 'mime' item, optionally compressing the payload.

Parameters

ctx	the file context
content_type	MIME content type of the payload (e.g. "application/rdf+xml")
content_encoding	compression to apply to the payload before storing it. Use heif_metadata_compression_method_supported() to check which methods this build of libheif can compress. An unsupported method returns an error and no item is added.
data	the (uncompressed) item payload
size	number of bytes in 'data'
out_item_id	receives the ID of the new item (may be NULL)

heif_context_add_precompressed_mime_item()

heif_error heif_context_add_precompressed_mime_item	(	heif_context *	ctx,
		const char *	content_type,
		const char *	content_encoding,
		const void *	data,
		int	size,
		heif_item_id *	out_item_id )

Add a 'mime' item whose payload has already been compressed by the caller.

Parameters

ctx	the file context
content_type	MIME content type of the (uncompressed) payload
content_encoding	the HTTP content-coding name that was applied to 'data', stored verbatim as the item's content_encoding. Use "" for uncompressed data. libheif itself can decode "deflate", "compress_zlib" and "br" (when built with zlib / Brotli support) and treats "identity" as uncompressed; items with any other content_encoding are kept, but their data can only be retrieved in compressed form with heif_item_get_item_data().
data	the compressed item payload
size	number of bytes in 'data'
out_item_id	receives the ID of the new item (may be NULL)

heif_context_add_uri_item()

heif_error heif_context_add_uri_item	(	heif_context *	ctx,
		const char *	item_uri_type,
		const void *	data,
		int	size,
		heif_item_id *	out_item_id )

Add a 'uri ' item.

Parameters

ctx	the file context
item_uri_type	the URI that identifies the type of the item payload
data	the item payload
size	number of bytes in 'data'
out_item_id	receives the ID of the new item (may be NULL)

heif_context_get_item_references()

size_t heif_context_get_item_references	(	const heif_context *	ctx,
		heif_item_id	from_item_id,
		int	index,
		uint32_t *	out_reference_type_4cc,
		heif_item_id **	out_references_to )

Get the item ids that reference the given item.

Parameters

ctx	the file context.
from_item_id	the item identifier for the item.
index	the index of the reference to get.
out_reference_type_4cc	The 4cc of the reference. (e.g dimg, thmb, cdsc, or auxl)
out_references_to	the item references. Use heif_release_item_references to free the memory.

Returns

the number of items that reference the given item. Returns 0 if the index exceeds the number of references.

heif_context_get_list_of_item_IDs()

int heif_context_get_list_of_item_IDs	(	const heif_context *	ctx,
		heif_item_id *	ID_array,
		int	count )

Get the item identifiers.

Fills in the item IDs into the user-supplied array ID_array, preallocated with count entries.

Parameters

ctx	the file context
ID_array	the output array.
count	the number of items allocated within ID_array.

Returns

the total number of IDs filled into the array, which may be less than count.

heif_context_get_number_of_items()

int heif_context_get_number_of_items

(

const heif_context *

ctx

)

Gets the number of items.

This is not the same as the number of images, since there can be other types of items, such as metadata.

Parameters

ctx	the file context

Returns

the number of items

heif_item_get_item_data()

heif_error heif_item_get_item_data	(	const heif_context *	ctx,
		heif_item_id	item_id,
		enum heif_metadata_compression *	out_compression_format,
		uint8_t **	out_data,
		size_t *	out_data_size )

Gets the raw metadata, as stored in the HEIF file.

Data in a "mime" item with "content_encoding" can be compressed. When out_compression_format is NULL, the decompressed data will be returned. Otherwise, the compressed data is returned and out_compression_format will be filled with the compression format. If the compression method is not supported, an error will be returned.

It is valid to set out_data to NULL. In that case, only the out_data_size is filled. Note that it is inefficient to use out_data=NULL just to get the size of compressed data. In general, this should be avoided.

If there is no data assigned to the item or there is an error, out_data_size is set to zero.

Parameters

ctx	the file context
item_id	the item identifier for the item
out_compression_format	how the data is compressed. If the pointer is NULL, the decompressed data will be returned.
out_data	the corresponding raw metadata
out_data_size	the size of the metadata in bytes

Returns

whether the call succeeded, or there was an error

heif_item_get_item_name()

const char * heif_item_get_item_name	(	const heif_context *	ctx,
		heif_item_id	item_id )

heif_item_get_item_type()

uint32_t heif_item_get_item_type	(	const heif_context *	ctx,
		heif_item_id	item_id )

Gets the item type.

Usually, this is a four character code (e.g. mime or uri ), but it can theoretically be any 4-byte number. Thus, the type is returned as an integer. You can use heif_fourcc to map between the two representations.

Parameters

ctx	the file context
item_id	the item identifier for the item

Returns

the item type

heif_item_get_mime_item_content_encoding()

const char * heif_item_get_mime_item_content_encoding	(	const heif_context *	ctx,
		heif_item_id	item_id )

Gets the content_encoding for a MIME item.

Only valid if the item type is mime. If the item does not exist, or if it is not a mime item, NULL is returned.

If the item is not encoded, the returned value will be an empty string (not null).

Parameters

ctx	the file context
item_id	the item identifier for the item

Returns

the item content_type

heif_item_get_mime_item_content_type()

const char * heif_item_get_mime_item_content_type	(	const heif_context *	ctx,
		heif_item_id	item_id )

Gets the MIME content_type for an item.

Only valid if the item type is mime. If the item does not exist, or if it is not a mime item, NULL is returned.

Parameters

ctx	the file context
item_id	the item identifier for the item

Returns

the item content_type

heif_item_get_property_extended_language()

heif_error heif_item_get_property_extended_language	(	const heif_context *	context,
		heif_item_id	itemId,
		char **	out_language )

Get the extended language associated with the item.

The item is usually a text item.

Parameters

context	the heif file context containg the item.
itemId	the identifier for the item
out_language	output parameter with the item's language. Free with heif_string_release().

Returns

heif_error_ok on success, or an error value indicating the problem

heif_item_get_uri_item_uri_type()

const char * heif_item_get_uri_item_uri_type	(	const heif_context *	ctx,
		heif_item_id	item_id )

Gets the item_uri_type for an item.

Only valid if the item type is uri . If the item does not exist, or if it is not a uri item, NULL is returned.

Parameters

ctx	the file context
item_id	the item identifier for the item

Returns

the item item_uri_type

heif_item_is_item_hidden()

int heif_item_is_item_hidden	(	const heif_context *	ctx,
		heif_item_id	item_id )

heif_item_set_item_name()

heif_error heif_item_set_item_name	(	heif_context *	ctx,
		heif_item_id	item,
		const char *	item_name )

heif_item_set_property_extended_language()

heif_error heif_item_set_property_extended_language	(	heif_context *	context,
		heif_item_id	item_id,
		const char *	language,
		heif_property_id *	out_optional_propertyId )

heif_release_item_data()

void heif_release_item_data	(	const heif_context *	ctx,
		uint8_t **	item_data )

Free the item data.

This is used to free memory associated with the data returned by heif_item_get_item_data in 'out_data' and set the pointer to NULL.

Parameters

ctx	the file context
item_data	the data to free

heif_release_item_references()

void heif_release_item_references	(	const heif_context *	ctx,
		heif_item_id **	references )