- switched MP4ItmfItem to use MP4Atom* instead of indexes;

Kona8lend · Kona8lend · commit 1f53d0ec260c · 2009-05-27T14:10:45.000Z
this lets it survivie multiple removes/adds while supporting set operations.
- added general description docs for iTMF Generic and Tags APIs.
- moved responsibility for ilst empty cleanup to MP4File::FinishWrite().
- added moov.udta.meta empty cleanup.
- added moov.udta empty cleanup.
diff --git a/include/mp4v2/itmf_generic.h b/include/mp4v2/itmf_generic.h
@@ -6,6 +6,65 @@
  *  @defgroup mp4_itmf_generic MP4v2 iTMF (iTunes Metadata Format) Generic
  *  @{
  *
+ *  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; ie: 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 <b>manual</b> 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 <b>mean</b> and
+ *  <b>name</b> 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 <b>elements</b>
+ *  buffer and update <b>size</b> 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.
+ *
+ *  <b>iTMF Generic read workflow:</b>
+ *
+ *      @li MP4ItmfGetItems()
+ *      @li inspect each item...
+ *      @li MP4ItmfItemListFree()
+ *
+ *  <b>iTMF Generic read/modify/remove workflow:</b>
+ *
+ *      @li MP4ItmfGetItems()
+ *      @li inspect/modify item...
+ *      @li MP4ItmfSetItem() each modified item...
+ *      @li MP4ItmfRemoveItem()...
+ *      @li MP4ItmfItemListFree()
+ *
+ *  <b>iTMF Generic add workflow:</b>
+ *
+ *      @li MP4ItmfItemAlloc()
+ *      @li MP4ItmfAddItem()
+ *      @li MP4ItmfItemFree()
+ *
+ *  @par 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.
+ *
  *****************************************************************************/
 
 /** Basic types of value data as enumerated in spec. */
@@ -59,7 +118,8 @@ typedef struct MP4ItmfDataList_s
  */
 typedef struct MP4ItmfItem_s
 {
-    int32_t         index;    /**< 0-based index of item in ilst container. -1 if undefined. */
+    void* __handle; /**< internal use only. */
+
     char*           code;     /**< four-char code identifing atom type. NULL-terminated. */
     char*           mean;     /**< may be NULL. UTF-8 meaning. NULL-terminated. */
     char*           name;     /**< may be NULL. UTF-8 name. NULL-terminated. */
diff --git a/include/mp4v2/itmf_tags.h b/include/mp4v2/itmf_tags.h
@@ -6,6 +6,51 @@
  *  @defgroup mp4_itmf_tags MP4v2 iTMF (iTunes Metadata Format) Tags
  *  @{
  *
+ *  This is a high-level API used to manage iTMF metadata.
+ *
+ *  It provides more type-safety and simplified memory management as compared
+ *  to iTMF Generic API.
+ *
+ *  At the heart of this API is a read-only structure that holds all known
+ *  items and their current values. The value is always a pointer which if
+ *  NULL indicates its corresponding atom does not exist. Thus, one must
+ *  always check if the pointer is non-NULL before attempting to extract
+ *  its value.
+ *
+ *  The structure may not be directly modified. Instead, <b>set</b> functions
+ *  corresponding to each item are used to modify the backing-store of
+ *  the read-only structure. Setting the value ptr to NULL will effectively
+ *  remove it. Setting the value ptr to real data will immediately make a
+ *  copy of the value in the backing-store and the read-only structure
+ *  will correctly reflect the change.
+ *
+ *  The hidden data cache memory is automatically managed. Thus the user need
+ *  only guarantee the data is available during the lifetime of the set-function
+ *  call.
+ *
+ *  <b>iTMF Tags read workflow:</b>
+ *
+ *      @li MP4TagsAlloc()
+ *      @li MP4TagsFetch()
+ *      @li inspect each tag of interest...
+ *      @li MP4TagsStore() (if modified)
+ *      @li MP4TagsFree()
+ *
+ *  <b>iTMF Tags read/modify/add/remove workflow:</b>
+ *
+ *      @li MP4TagsAlloc()
+ *      @li MP4TagsFetch()
+ *      @li inspect each tag of interest...
+ *      @li MP4TagsSetName(), MP4TagsSetArtist()...
+ *      @li MP4TagsStore()
+ *      @li MP4TagsFree()
+ *
+ *  @par 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.
+ *
  *****************************************************************************/
 
 /** Enumeration of possible MP4TagArtwork::type values. */
diff --git a/src/itmf/generic.cpp b/src/itmf/generic.cpp
@@ -83,10 +83,10 @@ __dataListResize( MP4ItmfDataList& list, uint32_t size )
 void
 __itemInit( MP4ItmfItem& item )
 {
-    item.index = -1;
-    item.code  = NULL;
-    item.mean  = NULL;
-    item.name  = NULL;
+    item.__handle = NULL;
+    item.code     = NULL;
+    item.mean     = NULL;
+    item.name     = NULL;
 
     __dataListInit( item.dataList );
 }
@@ -151,11 +151,11 @@ __itemListAlloc()
 ///////////////////////////////////////////////////////////////////////////////
 
 static bool
-__itemAtomToModel( uint32_t index, MP4ItemAtom& item_atom, MP4ItmfItem& model )
+__itemAtomToModel( MP4ItemAtom& item_atom, MP4ItmfItem& model )
 {
     __itemClear( model );
-    model.index = index;
-    model.code  = strdup( item_atom.GetType() );
+    model.__handle = &item_atom;
+    model.code     = strdup( item_atom.GetType() );
 
     // handle special meaning atom
     if( ATOMID( item_atom.GetType() ) == ATOMID( "----" )) {
@@ -302,7 +302,7 @@ genericGetItems( MP4File& file )
     __itemListResize( list, itemCount );
 
     for( uint32_t i = 0; i < list.size; i++ )
-        __itemAtomToModel( i, *(MP4ItemAtom*)ilst->GetChildAtom( i ), list.elements[i] );
+        __itemAtomToModel( *(MP4ItemAtom*)ilst->GetChildAtom( i ), list.elements[i] );
 
     return &list;
 }
@@ -335,7 +335,7 @@ genericGetItemsByCode( MP4File& file, const string& code )
     const vector<uint32_t>::size_type max = indexList.size();
     for( vector<uint32_t>::size_type i = 0; i < max; i++ ) {
         uint32_t& aidx = indexList[i];
-        __itemAtomToModel( aidx, *(MP4ItemAtom*)ilst->GetChildAtom( aidx ), list.elements[i] );
+        __itemAtomToModel( *(MP4ItemAtom*)ilst->GetChildAtom( aidx ), list.elements[i] );
     }
 
     return &list;
@@ -387,7 +387,7 @@ genericGetItemsByMeaning( MP4File& file, const string& meaning, const string& na
     const vector<uint32_t>::size_type max = indexList.size();
     for( vector<uint32_t>::size_type i = 0; i < max; i++ ) {
         uint32_t& aidx = indexList[i];
-        __itemAtomToModel( aidx, *(MP4ItemAtom*)ilst->GetChildAtom( aidx ), list.elements[i] );
+        __itemAtomToModel( *(MP4ItemAtom*)ilst->GetChildAtom( aidx ), list.elements[i] );
     }
 
     return &list;
@@ -416,24 +416,32 @@ genericAddItem( MP4File& file, const MP4ItmfItem* item )
 bool
 genericSetItem( MP4File& file, const MP4ItmfItem* item )
 {
-    if( item->index == -1 )
+    if( !item->__handle )
         return false;
 
     MP4Atom* ilst = file.FindAtom( "moov.udta.meta.ilst" );
     if( !ilst )
         return false;
 
-    if( (uint32_t)item->index >= ilst->GetNumberOfChildAtoms() )
-        return genericAddItem( file, item );
-
-    MP4ItemAtom* old = (MP4ItemAtom*)ilst->GetChildAtom( item->index );
-    if( old ) {
-        ilst->DeleteChildAtom( ilst->GetChildAtom( item->index ));
-        delete old;
+    MP4ItemAtom* const old = static_cast<MP4ItemAtom*>(item->__handle);
+    const uint32_t childCount = ilst->GetNumberOfChildAtoms();
+    uint32_t fidx = numeric_limits<uint32_t>::max();
+    for( uint32_t i = 0; i < childCount; i++ ) {
+        MP4Atom* atom = ilst->GetChildAtom( i );
+        if( atom == old ) {
+            fidx = i;
+            break;
+        }
     }
 
+    if( fidx == numeric_limits<uint32_t>::max() )
+        return false;
+
+    ilst->DeleteChildAtom( old );
+    delete old;
+
     MP4ItemAtom& itemAtom = *(MP4ItemAtom*)MP4Atom::CreateAtom( ilst, item->code );
-    ilst->InsertChildAtom( &itemAtom, item->index );
+    ilst->InsertChildAtom( &itemAtom, fidx );
 
     return __itemModelToAtom( *item, itemAtom );
 }
@@ -443,26 +451,16 @@ genericSetItem( MP4File& file, const MP4ItmfItem* item )
 bool
 genericRemoveItem( MP4File& file, const MP4ItmfItem* item )
 {
-    if( item->index == -1 )
+    if( !item->__handle )
         return false;
 
     MP4Atom* ilst = file.FindAtom( "moov.udta.meta.ilst" );
     if( !ilst )
         return false;
 
-    if( (uint32_t)item->index >= ilst->GetNumberOfChildAtoms() )
-        return false;
-
-    MP4ItemAtom* itemAtom = (MP4ItemAtom*)ilst->GetChildAtom( item->index );
-    if( itemAtom ) {
-        ilst->DeleteChildAtom( ilst->GetChildAtom( item->index ));
-        delete itemAtom;
-    }
-
-    if( ilst->GetNumberOfChildAtoms() == 0 ) {
-        ilst->GetParentAtom()->DeleteChildAtom( ilst );
-        delete ilst;
-    }
+    MP4ItemAtom* const old = static_cast<MP4ItemAtom*>(item->__handle);
+    ilst->DeleteChildAtom( old );
+    delete old;
 
     return true;
 }
diff --git a/src/mp4file.cpp b/src/mp4file.cpp
@@ -463,6 +463,45 @@ void MP4File::BeginWrite()
 
 void MP4File::FinishWrite()
 {
+    // remove empty moov.udta.meta.ilst
+    {
+        MP4Atom* ilst = FindAtom( "moov.udta.meta.ilst" );
+        if( ilst ) {
+            if( ilst->GetNumberOfChildAtoms() == 0 ) {
+                ilst->GetParentAtom()->DeleteChildAtom( ilst );
+                delete ilst;
+            }
+        }
+    }
+
+    // remove empty moov.udta.meta
+    {
+        MP4Atom* meta = FindAtom( "moov.udta.meta" );
+        if( meta ) {
+            if( meta->GetNumberOfChildAtoms() == 0 ) {
+                meta->GetParentAtom()->DeleteChildAtom( meta );
+                delete meta;
+            }
+            else if( meta->GetNumberOfChildAtoms() == 1 ) {
+                if( ATOMID( meta->GetChildAtom( 0 )->GetType() ) == ATOMID( "hdlr" )) {
+                    meta->GetParentAtom()->DeleteChildAtom( meta );
+                    delete meta;
+                }
+            }
+        }
+    }
+
+    // remove empty moov.udta
+    {
+        MP4Atom* udta = FindAtom( "moov.udta" );
+        if( udta ) {
+            if( udta->GetNumberOfChildAtoms() == 0 ) {
+                udta->GetParentAtom()->DeleteChildAtom( udta );
+                delete udta;
+            }
+        }
+    }
+
     // for all tracks, flush chunking buffers
     for( uint32_t i = 0; i < m_pTracks.Size(); i++ ) {
         ASSERT( m_pTracks[i] );
