Skip to content

Meta data functions

Jump to bottom
Dimitri Podborski edited this page Sep 17, 2020 · 1 revision

These functions allow you to manage meta boxes (atoms) at file, movie, and track level, and the items they contain. The meta-type in the following functions can be a four-character code, or one of the pre-defined codes:

MP7TextHandlerType
7BinaryHandlerType
MP21HandlerType
MP4NullHandlerType

ISONewFileMeta

ISOErr ISONewFileMeta( ISOMovie theMovie, 
            u32 metaType, 
            ISOMeta* meta);

Creates a new meta box (atom), with the indicated ‘handler’ type, at the file level. If there is already a meta box present, a additional meta box atom will be created and the new meta box will be added inside.

ISONewMovieMeta

ISOErr ISONewMovieMeta( ISOMovie theMovie, 
            u32 metaType, 
            ISOMeta* meta );

Creates a new meta box (atom), with the indicated ‘handler’ type, in the movie box (atom). If there is already a meta box present, a additional meta box atom will be created and the new meta box will be added inside.

ISONewTrackMeta

ISOErr ISONewTrackMeta( ISOTrack theTrack, 
            u32 metaType, 
            ISOMeta* meta );

Creates a new meta box (atom), with the indicated ‘handler’ type, in the indicated track box (atom). If there is already a meta box present, a additional meta box atom will be created and the new meta box will be added inside.

ISOAddMetaBoxRelation

ISOErr ISOAddMetaBoxRelation (ISOMeta first_meta, 
            ISOMeta second_meta, u8 relation_type );

Adds a meta box relation box to the additional meta data box, related to first and second meta box. They must live on the same level (file, movie, track).

ISOGetMetaBoxRelation

ISOErr ISOAddMetaBoxRelation (ISOMeta first_meta, 
            ISOMeta second_meta, u8 *relation_type );

The relation_type will contain the type found in a meta box relation box or 0.

ISOAddMetaDataReference

ISOErr ISOAddMetaDataReference( ISOMeta meta, 
            u16* out_data_ref_index, 
            ISOHandle urlHandle, 
            ISOHandle urnHandle );

Adds a data reference to the given meta-data. The returned reference in can later be passed to the ISOAddMetaItem.

ISOAddMetaItem

ISOErr ISOAddMetaItem( ISOMeta meta, 
            ISOMetaItem* outItem, 
            u64 base_offset, 
            u16 data_ref_index );

Creates a new meta-data item, and returns an opaque pointer to it. The data reference can be zero (for items to be in the same file) or as returned by ISOAddMetaDataReference. The base offset should generally be zero; the software will increment this to reflect the actual base offset of the item’s first extent in the file.

ISOAddMetaItemWithID

ISOErr ISOAddMetaItemWithID( ISOMeta meta, 
            ISOMetaItem* outItem, 
            u64 base_offset, 
            u16 data_ref_index, u16 item_ID );

Like the previous function, but allows a specific ID to be requested.

ISOAddItemExtent

ISOErr ISOAddItemExtent( ISOMetaItem item, MP4Handle data );

Adds some data to the given item, as its first (perhaps only) extent. Should generally be called only when the data reference for the item was supplied as zero. The data will be added to the related mdat box. NOTE: If there are multiple extents for one item, their data must be added using the same ISOAddItemExtent* function.

ISOAddItemExtentReference

ISOErr ISOAddItemExtentReference( ISOMetaItem item, 
            u64 offset, 
            u64 length );

Adds a reference to the data. Should generally be called only when a non-zero data reference was supplied for the item. NOTE: If there are multiple extents for one item, their data must be added using the same ISOAddItemExtent* function.

ISOAddItemExtentUsingItemData

ISOErr ISOAddItemExtentUsingItemData ( ISOMetaItem item, MP4Handle data );

Adds some data to the given item, as its first (perhaps only) extent. The data will be added to an item data box, which is contained in the meta data box. NOTE: If there are multiple extents for one item, their data must be added using the same ISOAddItemExtent* function.

ISOAddItemExtentItem

ISOErr ISOAddItemExtentItem( ISOMetaItem item,
            ISOMetaItem extent_item,
            u64 offset, 
            u64 length );

Indicates that the data for this extent is located at another item’s extends. NOTE: If there are multiple extents for one item, their data must be added using the same ISOAddItemExtent* function.

ISOAddItemReference

ISOErr ISOAddItemReference (ISOMetaItem item, 
            u32 reference_type,
            u32 to_item_ID, 
            u32 *outIndex);

This function adds an item reference to the item reference box. If there is no existing item reference box, it will be created. The outIndex will contain the position of the to_item_ID in all to_item_IDs of this item / reference_type combination.

ISOAddItemReferences

ISOErr ISOAddItemReferences (ISOMetaItem item, 
            u32 reference_type, 
            u16 reference_count, 
            MP4Handle to_item_IDs);

This function adds multiple item references to the item reference box. If there is no existing item reference box, it will be created. NOTE: If there are already existing references of this item / reference_type combination, they will be overwritten.

ISOGetItemReferences

ISOErr ISOGetItemReferences (ISOMetaItem item, 
            u32 reference_type, 
            u16 *reference_count,
            MP4Handle to_item_IDs);

This function collects all item references of the item / reference_type combination.

ISOAddPrimaryData

ISOErr ISOAddPrimaryData( ISOMeta meta, 
            u32 box_type, 
            MP4Handle data, 
            u8 is_full_atom );

Places the indicated data inside a box in the meta-box, with the indicated box type (e.g. ISOXMLAtomType or ISOBinaryXMLAtomType). The flag is_full_atom can be used to insert the four bytes of version and flags required in a full atom.

ISOGetPrimaryData

ISOErr ISOGetPrimaryData( ISOMeta meta, 
            u32 box_type, 
            MP4Handle data, 
            u8 is_full_atom );

Finds the box of the given type inside the meta box, and returns its contents. The flag is_full_atom can be used to skip the four bytes of version and flags of a full atom.

ISOGetPrimaryItemData

ISOErr ISOGetPrimaryItemData( ISOMeta meta, 
            u32 box_type, 
            MP4Handle data, 
            u8 is_full_atom );

Like ISOGetPrimaryData, but probably more useful, as if a box of the given type does not exist, finds the primary item and returns its data. Gives an error indication if neither the box nor the primary item exist.

ISOSetPrimaryItem

ISOErr ISOSetPrimaryItem( ISOMeta meta, ISOMetaItem item );

Sets the item of the indicated ID as the primary item (using a primary item box).

ISOGetPrimaryItemID

ISOErr ISOGetPrimaryItemID( ISOMeta meta, u16 *ID );

Finds the ID of the primary item.

ISOGetItemID

ISOErr ISOGetItemID( ISOMetaItem item, u16* ID );

Gets the ID of the indicated item.

ISOSetItemInfo

ISOErr ISOSetItemInfo( ISOMetaItem item, 
            u16 protection_index, 
            char* name, 
            char* content_type, 
            char* content_encoding );

Sets the information for the indicated item; the protection_index is returned by ISONewMetaProtection (see below).

ISOSetItemInfoExtension

ISOErr ISOSetItemInfoExtension ( ISOMetaItem item, 
            MP4Handle extension, 
            u32 extension_type );

Adds an item info extension to an existing item info entry.

ISOGetItemInfoExtension

ISOErr ISOGetItemInfoExtension ( ISOMetaItem item, 
            MP4Handle extension, 
            u32 *extension_type );

Gets an item info extension and its extension type from an item.

ISOSetItemInfoItemType

ISOErr ISOSetItemInfoItemType ( ISOMetaItem item, 
            u32 item_type, 
            char* item_uri_type);

Adds an item info item type to an existing item info entry. NOTE: item_uri_type can be NULL, if the item_type is not ‘uri ‘.

ISOGetItemInfoItemType

ISOErr ISOGetItemInfoItemType ( ISOMetaItem item, 
            u32 *item_type, 
            char** item_uri_type);

Gets an item info item type from an existing item info entry. NOTE: item_uri_type could be NULL, if the item_type is not ‘uri ‘.

ISOGetItemInfoExtension

ISOErr ISOGetItemInfoExtension ( ISOMetaItem item, 
            MP4Handle extension, 
            u32 *extension_type );

Gets an item info extension and its extension type from an item.

ISOGetFileMeta

ISOErr ISOGetFileMeta( ISOMovie theMovie, 
            ISOMeta* meta, 
            u32 inMetaType, 
            u32* outMetaType);

Gets a reference to the file-level meta data. The input parameter meta-type, if non-zero, can be used to check that the associated meta-data is of the given type. The output always supplies the type.

ISOGetMovieMeta

ISOErr ISOGetMovieMeta( ISOMovie theMovie, 
            ISOMeta* meta, 
            u32 inMetaType, 
            u32* outMetaType );

Gets a reference to the movie-level meta data. The input parameter meta-type, if non-zero, can be used to check that the associated meta-data is of the given type. The output always supplies the type.

ISOGetTrackMeta

ISOErr ISOGetTrackMeta( ISOTrack theTrack, 
            ISOMeta* meta, 
            u32 inMetaType, 
            u32* outMetaType );

Gets a reference to the track-level meta data. The input parameter meta-type, if non-zero, can be used to check that the associated meta-data is of the given type. The output always supplies the type.

ISOGetAllItemsWithType

ISOErr ISOGetAllItemsWithType (ISOMeta meta,
            u32 type, 
            ISOMetaItem **items,
            u32 *numberOfItemsFound);

Collects all items of a given type and presents the result in form of an array.

ISOFindItemByName

ISOErr ISOFindItemByName( ISOMeta meta, 
            ISOMetaItem* item, 
            char* name, 
            u8 exact_case );

Finds an item that has the associated name in its item information.

ISOFindItemByID

ISOErr ISOFindItemByID( ISOMeta meta, 
            ISOMetaItem* item, 
            u16 ID );

Gets a reference to an item by its ID.

ISOGetItemData

ISOErr ISOGetItemData( ISOMetaItem item, 
            MP4Handle data, 
            u64* base_offset );

Reads and returns the data associated with all the extents of the given item, concatenating them. The returned base offset will be adjusted to represent the offset in the resulting handle (which will generally match the value passed in to ISOAddMetaItem, typically zero).

ISOGetItemInfo

ISOErr ISOGetItemInfo( ISOMetaItem item, 
            u16* protection_index, 
            char* name, 
            char* content_type, 
            char* content_encoding );

Returns the information for a given item. It is your responsibility to make sure the buffers are large enough for the strings.

ISOCheckMetaDataReferences

ISOErr ISOCheckMetaDataReferences( ISOMeta meta );

Checks that all the data references used by the meta-data are accessible.

ISONewMetaProtection

ISOErr ISONewMetaProtection( ISOMeta meta, 
            u32 sch_type, 
            u32 sch_version, 
            char* sch_url, 
            u16* protection_index );

Creates a new item protection information inside the given meta-data box.

ISOAddMetaProtectionInfo

ISOErr ISOAddMetaProtectionInfo( ISOMeta meta, 
            u16 protection_index, 
            MP4GenericAtom schi_atom );

Adds an arbitrary atom to the scheme information of the associated protection information.

ISOGetMetaProtection

ISOErr ISOGetMetaProtection( ISOMeta meta, 
            u16 protection_index, 
            u32* sch_type, 
            u32* sch_version, 
            char* sch_url );

Gets the scheme type, version, and URL associated with the protection information of the given index.

ISOGetMetaProtectionInfo

ISOErr ISOGetMetaProtectionInfo( ISOMeta meta, 
            u16 protection_index, 
            u32 atom_type, 
            MP4GenericAtom* schi_atom  );

Finds and returns the atom of the given type inside the scheme information of the protection scheme at the given index.

ISOAddMetaItemProperty

ISOErr ISOAddMetaItemProperty (ISOMetaItem item, MP4GenericAtom* itemProperty, u8 essential);

Adds an item property, which can be any MP4GenericAtom, to an ISOMetaItem. The essential flag can be set with 1 and unset with 0.

ISOGetProperitesOfMetaItem

ISOErr ISOGetProperitesOfMetaItem (ISOMetaItem item, MP4GenericAtom** properties, u32 *propertiesFound);

Retruns an array of MP4GenericAtom pointers, which represent the item properties found for the item given. The u32 propertiesFound indicates the amount of items found and the size of the array, that is returned.

HOME

About
TODOs

How to use

API documentation single page

Clone this wiki locally