heif_items.h

Go to the documentation of this file.

/*
 * HEIF codec.
 * Copyright (c) 2023 Dirk Farin <dirk.farin@gmail.com>
 *
 * This file is part of libheif.
 *
 * libheif is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as
 * published by the Free Software Foundation, either version 3 of
 * the License, or (at your option) any later version.
 *
 * libheif is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with libheif.  If not, see <http://www.gnu.org/licenses/>.
 */
 
#ifndef LIBHEIF_HEIF_ITEMS_H
#define LIBHEIF_HEIF_ITEMS_H
 
#include "heif_library.h"
#include "heif_error.h"
#include "heif_metadata.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 

LIBHEIF_API
int heif_context_get_number_of_items(const heif_context* ctx);

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

LIBHEIF_API
uint32_t heif_item_get_item_type(const heif_context* ctx, heif_item_id item_id);
 
#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')
 
LIBHEIF_API
int heif_item_is_item_hidden(const heif_context* ctx, heif_item_id item_id);
 

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

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

LIBHEIF_API
const char* heif_item_get_uri_item_uri_type(const heif_context* ctx, heif_item_id item_id);
 
LIBHEIF_API
const char* heif_item_get_item_name(const heif_context* ctx, heif_item_id item_id);
 
LIBHEIF_API
heif_error heif_item_set_item_name(heif_context* ctx,
                                   heif_item_id item,
                                   const char* item_name);
 

LIBHEIF_API
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);

LIBHEIF_API
void heif_release_item_data(const heif_context* ctx, uint8_t** item_data);
 
 
// ------------------------- item language -------------------------

LIBHEIF_API
heif_error heif_item_get_property_extended_language(const heif_context* context,
                                                    heif_item_id itemId,
                                                    char** out_language);
 
LIBHEIF_API
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);
 
// ------------------------- item references -------------------------

LIBHEIF_API
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);
 
LIBHEIF_API
void heif_release_item_references(const heif_context* ctx, heif_item_id** references);
 
LIBHEIF_API
heif_error heif_context_add_item_reference(heif_context* ctx,
                                           uint32_t reference_type,
                                           heif_item_id from_item,
                                           heif_item_id to_item);
 
LIBHEIF_API
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);
 
// ------------------------- adding new items -------------------------
 
/*
 * All functions in this section add a new item to the context and return its ID in
 * 'out_item_id'. The item ID is freshly allocated and does not collide with any item that
 * already exists in the context, including items read from an input file.
 *
 * 'data' is copied into the context, the caller may release it afterwards. 'size' is the
 * number of bytes in 'data'. A NULL 'data' is only allowed together with size 0.
 * 'out_item_id' may be NULL, in which case the item is added but its ID is not reported.
 *
 * The new item is marked as hidden. Use heif_context_add_item_reference() to link it to an
 * image (e.g. with a 'cdsc' reference for metadata that describes the image).
 *
 * Note that a file must contain at least one image or image sequence to be written;
 * a context holding only items added with these functions cannot be written.
 */

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

LIBHEIF_API
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);

LIBHEIF_API
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);

LIBHEIF_API
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);
 
#ifdef __cplusplus
}
#endif
 
#endif