MP4v2
|
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... | |
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()
typedef struct MP4ItmfData_s MP4ItmfData |
Data structure.
Models an iTMF data atom contained in an iTMF metadata item atom.
typedef struct MP4ItmfItem_s MP4ItmfItem |
Item structure.
Models an iTMF metadata item atom contained in an ilst atom.
enum MP4ItmfBasicType_e |
Basic types of value data as enumerated in spec.
bool MP4ItmfAddItem | ( | MP4FileHandle | hFile, |
const MP4ItmfItem * | item | ||
) |
Add an item to file.
hFile | handle of file to operate on. |
item | object to add. |
MP4ItmfItemList* MP4ItmfGetItems | ( | MP4FileHandle | hFile | ) |
Get list of all items from file.
hFile | handle of file to operate on. |
MP4ItmfItemList* MP4ItmfGetItemsByCode | ( | MP4FileHandle | hFile, |
const char * | code | ||
) |
Get list of items by code from file.
hFile | handle of file to operate on. |
code | four-char code identifying atom type. NULL-terminated. |
MP4ItmfItemList* MP4ItmfGetItemsByMeaning | ( | MP4FileHandle | hFile, |
const char * | meaning, | ||
const char * | name | ||
) |
Get list of items by meaning from file.
Implicitly only returns atoms of code {-—}.
hFile | handle of file to operate on. |
meaning | UTF-8 meaning. NULL-terminated. |
name | may be NULL. UTF-8 name. NULL-terminated. |
MP4ItmfItem* MP4ItmfItemAlloc | ( | const char * | code, |
uint32_t | numData | ||
) |
Allocate an item on the heap.
code | four-char code identifying atom type. NULL-terminated. |
numData | number of data elements to allocate. Must be >= 1. |
void MP4ItmfItemFree | ( | MP4ItmfItem * | item | ) |
void MP4ItmfItemListFree | ( | MP4ItmfItemList * | itemList | ) |
bool MP4ItmfRemoveItem | ( | MP4FileHandle | hFile, |
const MP4ItmfItem * | item | ||
) |
Remove an existing item from file.
hFile | handle of file to operate on. |
item | object to remove. Must have a valid index obtained from prior get. |
bool MP4ItmfSetItem | ( | MP4FileHandle | hFile, |
const MP4ItmfItem * | item | ||
) |
Overwrite an existing item in file.
hFile | handle of file to operate on. |
item | object to overwrite. Must have a valid index obtained from prior get. |