heif_items.h File Reference

#include "libheif/heif.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',' ')

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.
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)
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)
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)
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)

Macro Definition Documentation

heif_item_type_mime

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

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 )

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 )

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 )

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 )

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_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_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 )