MP4v2

Classes | Typedefs | Enumerations | Functions
MP4v2 iTMF (iTunes Metadata Format) Generic

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.