This is a low-level API used to manage iTMF metadata. More...

Classes
struct	MP4ItmfData_s
	Data structure. More...

struct	MP4ItmfDataList_s
	List of data. More...

struct	MP4ItmfItem_s
	Item structure. More...

struct	MP4ItmfItemList_s
	List of items. More...

Typedefs
typedef enum MP4ItmfBasicType_e	MP4ItmfBasicType
	Basic types of value data as enumerated in spec.

typedef struct MP4ItmfData_s	MP4ItmfData
	Data structure. More...

typedef struct MP4ItmfDataList_s	MP4ItmfDataList
	List of data.

typedef struct MP4ItmfItem_s	MP4ItmfItem
	Item structure. More...

typedef struct MP4ItmfItemList_s	MP4ItmfItemList
	List of items.

Enumerations
enum	MP4ItmfBasicType_e { MP4_ITMF_BT_IMPLICIT = 0, MP4_ITMF_BT_UTF8 = 1, MP4_ITMF_BT_UTF16 = 2, MP4_ITMF_BT_SJIS = 3, MP4_ITMF_BT_HTML = 6, MP4_ITMF_BT_XML = 7, MP4_ITMF_BT_UUID = 8, MP4_ITMF_BT_ISRC = 9, MP4_ITMF_BT_MI3P = 10, MP4_ITMF_BT_GIF = 12, MP4_ITMF_BT_JPEG = 13, MP4_ITMF_BT_PNG = 14, MP4_ITMF_BT_URL = 15, MP4_ITMF_BT_DURATION = 16, MP4_ITMF_BT_DATETIME = 17, MP4_ITMF_BT_GENRES = 18, MP4_ITMF_BT_INTEGER = 21, MP4_ITMF_BT_RIAA_PA = 24, MP4_ITMF_BT_UPC = 25, MP4_ITMF_BT_BMP = 27, MP4_ITMF_BT_UNDEFINED = 255 }
	Basic types of value data as enumerated in spec. More...

Functions
MP4ItmfItem *	MP4ItmfItemAlloc (const char *code, uint32_t numData)
	Allocate an item on the heap. More...

void	MP4ItmfItemFree (MP4ItmfItem *item)
	Free an item (deep free). More...

void	MP4ItmfItemListFree (MP4ItmfItemList *itemList)
	Free an item list (deep free). More...

MP4ItmfItemList *	MP4ItmfGetItems (MP4FileHandle hFile)
	Get list of all items from file. More...

MP4ItmfItemList *	MP4ItmfGetItemsByCode (MP4FileHandle hFile, const char *code)
	Get list of items by code from file. More...

MP4ItmfItemList *	MP4ItmfGetItemsByMeaning (MP4FileHandle hFile, const char meaning, const char name)
	Get list of items by meaning from file. More...

bool	MP4ItmfAddItem (MP4FileHandle hFile, const MP4ItmfItem *item)
	Add an item to file. More...

bool	MP4ItmfSetItem (MP4FileHandle hFile, const MP4ItmfItem *item)
	Overwrite an existing item in file. More...

bool	MP4ItmfRemoveItem (MP4FileHandle hFile, const MP4ItmfItem *item)
	Remove an existing item from file. More...

Detailed Description

This is a low-level API used to manage iTMF metadata.

It provides support for virtually any kind of iTMF metadata item, including meaning atoms, sometimes referred to as reverse-DNS meanings. Structures are directly modified; i.e. there are no fuctions which modify values for you. There is little type-safety, logic checks, or specifications compliance checks. For these reasons it is recommended to use iTMF Tags API when possible.

At the heart of this API is an MP4ItmfItem which corresponds to an iTMF metadata item atom. The item, and any recursive data structures contained within require manual memory management. The general rule to follow is that you must always check/free a ptr if you intend to resize data. In cases where you know the existing data size is exactly what is needed, you may overwrite the buffer contents.

Each item always has at least 1 data elements which corresponds to a data atom. Additionally, each item has optional mean and name values which correspond to mean and name atoms.

Each MP4ItmfItem has a list of MP4ItmfData. Similarily, care must be taken to manage memory with one key difference; these structures also have a valueSize field. If value is NULL then set valueSize=0. Otherwise, set valueSize to the size (in bytes) of value buffer.

In rare cases where the number of data elements in a single item is > 1, the user must manually free/alloc/copy the elements buffer and update size accordingly.

The mp4 file structure is modified only when MP4AddItem(), MP4SetItem() and MP4RemoveItem() are used. Simply free'ing the item list does not modify the mp4 file.

iTMF Generic read workflow:

@li MP4ItmfGetItems()
@li inspect each item...
@li MP4ItmfItemListFree()

iTMF Generic read/modify/remove workflow:

@li MP4ItmfGetItems()
@li inspect/modify item...
@li MP4ItmfSetItem() each modified item...
@li MP4ItmfRemoveItem()...
@li MP4ItmfItemListFree()

iTMF Generic add workflow:

@li MP4ItmfItemAlloc()
@li MP4ItmfAddItem()
@li MP4ItmfItemFree()

Warning:: Care must be taken when using multiple mechanisms to modify an open mp4 file as it is not thread-safe, nor does it permit overlapping different API workflows which have a begin/end to their workflow. That is to say do not interleave an iTMF Generic workflow with an iTMF Tags workflow.

Typedef Documentation

◆ MP4ItmfData

typedef struct MP4ItmfData_s MP4ItmfData

Data structure.

Models an iTMF data atom contained in an iTMF metadata item atom.

◆ MP4ItmfItem

typedef struct MP4ItmfItem_s MP4ItmfItem

Item structure.

Models an iTMF metadata item atom contained in an ilst atom.

Enumeration Type Documentation

◆ MP4ItmfBasicType_e

enum MP4ItmfBasicType_e

Basic types of value data as enumerated in spec.

Enumerator
MP4_ITMF_BT_IMPLICIT	for use with tags for which no type needs to be indicated
MP4_ITMF_BT_UTF8	without any count or null terminator
MP4_ITMF_BT_UTF16	also known as UTF-16BE
MP4_ITMF_BT_SJIS	deprecated unless it is needed for special Japanese characters
MP4_ITMF_BT_HTML	the HTML file header specifies which HTML version
MP4_ITMF_BT_XML	the XML header must identify the DTD or schemas
MP4_ITMF_BT_UUID	also known as GUID; stored as 16 bytes in binary (valid as an ID)
MP4_ITMF_BT_ISRC	stored as UTF-8 text (valid as an ID)
MP4_ITMF_BT_MI3P	stored as UTF-8 text (valid as an ID)
MP4_ITMF_BT_GIF	(deprecated) a GIF image
MP4_ITMF_BT_JPEG	a JPEG image
MP4_ITMF_BT_PNG	a PNG image
MP4_ITMF_BT_URL	absolute, in UTF-8 characters
MP4_ITMF_BT_DURATION	in milliseconds, 32-bit integer
MP4_ITMF_BT_DATETIME	in UTC, counting seconds since midnight, January 1, 1904; 32 or 64-bits
MP4_ITMF_BT_GENRES	a list of enumerated values
MP4_ITMF_BT_INTEGER	a signed big-endian integer with length one of { 1,2,3,4,8 } bytes
MP4_ITMF_BT_RIAA_PA	RIAA parental advisory; { -1=no, 1=yes, 0=unspecified }, 8-bit ingteger.
MP4_ITMF_BT_UPC	Universal Product Code, in text UTF-8 format (valid as an ID)
MP4_ITMF_BT_BMP	Windows bitmap image.
MP4_ITMF_BT_UNDEFINED	undefined

Function Documentation

◆ MP4ItmfAddItem()

bool MP4ItmfAddItem	(	MP4FileHandle	hFile,
		const MP4ItmfItem *	item
	)

Add an item to file.

Parameters

hFile	handle of file to operate on.
item	object to add.

Returns: true on success, false on failure.

Examples: example/itmf/generic.c.

◆ MP4ItmfGetItems()

MP4ItmfItemList* MP4ItmfGetItems ( MP4FileHandle hFile )

Get list of all items from file.

Parameters

hFile handle of file to operate on.

Returns: On succes, list of items, which must be free'd. On failure, NULL.

Examples: example/itmf/generic.c.

◆ MP4ItmfGetItemsByCode()

MP4ItmfItemList* MP4ItmfGetItemsByCode	(	MP4FileHandle	hFile,
		const char *	code
	)

Get list of items by code from file.

Parameters

hFile	handle of file to operate on.
code	four-char code identifying atom type. NULL-terminated.

Returns: On succes, list of items, which must be free'd. On failure, NULL.

◆ MP4ItmfGetItemsByMeaning()

MP4ItmfItemList* MP4ItmfGetItemsByMeaning	(	MP4FileHandle	hFile,
		const char *	meaning,
		const char *	name
	)

Get list of items by meaning from file.

Implicitly only returns atoms of code {-—}.

Parameters

hFile	handle of file to operate on.
meaning	UTF-8 meaning. NULL-terminated.
name	may be NULL. UTF-8 name. NULL-terminated.

Returns: On succes, list of items, which must be free'd. On failure, NULL.

◆ MP4ItmfItemAlloc()

MP4ItmfItem* MP4ItmfItemAlloc	(	const char *	code,
		uint32_t	numData
	)

Allocate an item on the heap.

Parameters

code	four-char code identifying atom type. NULL-terminated.
numData	number of data elements to allocate. Must be >= 1.

Returns: newly allocated item.

Examples: example/itmf/generic.c.

◆ MP4ItmfItemFree()

void MP4ItmfItemFree ( MP4ItmfItem * item )

Free an item (deep free).

Parameters

item	to be free'd.

Examples: example/itmf/generic.c.

◆ MP4ItmfItemListFree()

void MP4ItmfItemListFree ( MP4ItmfItemList * itemList )

Free an item list (deep free).

Parameters

itemList to be free'd.

Examples: example/itmf/generic.c.

◆ MP4ItmfRemoveItem()

bool MP4ItmfRemoveItem	(	MP4FileHandle	hFile,
		const MP4ItmfItem *	item
	)

Remove an existing item from file.

Parameters

hFile	handle of file to operate on.
item	object to remove. Must have a valid index obtained from prior get.

Returns: true on success, false on failure.

◆ MP4ItmfSetItem()

bool MP4ItmfSetItem	(	MP4FileHandle	hFile,
		const MP4ItmfItem *	item
	)

Overwrite an existing item in file.

Parameters

hFile	handle of file to operate on.
item	object to overwrite. Must have a valid index obtained from prior get.

Returns: true on success, false on failure.

Classes

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ MP4ItmfData

◆ MP4ItmfItem

Enumeration Type Documentation

◆ MP4ItmfBasicType_e

Function Documentation

◆ MP4ItmfAddItem()

◆ MP4ItmfGetItems()

◆ MP4ItmfGetItemsByCode()

◆ MP4ItmfGetItemsByMeaning()

◆ MP4ItmfItemAlloc()

◆ MP4ItmfItemFree()

◆ MP4ItmfItemListFree()

◆ MP4ItmfRemoveItem()

◆ MP4ItmfSetItem()