MediaPlayer/TimedMetaData: API updates related to timed metadata

- renamed MediaPlayer.*OnTimedMetaData* to *OnTimedMetaDataAvailable*
- added `final` modifier to TimedMetaData class
- added javadocs for TimedMetaData public methods
- renamed private members and cooresponding accessors for TimedMetaData
- reworded existing TimedMetaData javadoc

Bug: 21045118
Change-Id: If0113307fce08083226fc7f64c4fe6f93553d899

api/current.txt

@@ -16087,7 +16087,7 @@ package android.media {
     method public void setOnInfoListener(android.media.MediaPlayer.OnInfoListener);
     method public void setOnPreparedListener(android.media.MediaPlayer.OnPreparedListener);
     method public void setOnSeekCompleteListener(android.media.MediaPlayer.OnSeekCompleteListener);
-    method public void setOnTimedMetaDataListener(android.media.MediaPlayer.OnTimedMetaDataListener);
+    method public void setOnTimedMetaDataAvailableListener(android.media.MediaPlayer.OnTimedMetaDataAvailableListener);
     method public void setOnTimedTextListener(android.media.MediaPlayer.OnTimedTextListener);
     method public void setOnVideoSizeChangedListener(android.media.MediaPlayer.OnVideoSizeChangedListener);
     method public void setPlaybackParams(android.media.PlaybackParams);
@@ -16149,8 +16149,8 @@ package android.media {
     method public abstract void onSeekComplete(android.media.MediaPlayer);
   }
 
-  public static abstract interface MediaPlayer.OnTimedMetaDataListener {
-    method public abstract void onTimedMetaData(android.media.MediaPlayer, android.media.TimedMetaData);
+  public static abstract interface MediaPlayer.OnTimedMetaDataAvailableListener {
+    method public abstract void onTimedMetaDataAvailable(android.media.MediaPlayer, android.media.TimedMetaData);
   }
 
   public static abstract interface MediaPlayer.OnTimedTextListener {
@@ -16691,9 +16691,9 @@ package android.media {
     field public static final int OPTIONS_RECYCLE_INPUT = 2; // 0x2
   }
 
-  public class TimedMetaData {
-    method public byte[] getRawData();
-    method public long getTimeUs();
+  public final class TimedMetaData {
+    method public byte[] getMetaData();
+    method public long getTimestamp();
   }
 
   public final class TimedText {

api/system-current.txt

@@ -17320,7 +17320,7 @@ package android.media {
     method public void setOnInfoListener(android.media.MediaPlayer.OnInfoListener);
     method public void setOnPreparedListener(android.media.MediaPlayer.OnPreparedListener);
     method public void setOnSeekCompleteListener(android.media.MediaPlayer.OnSeekCompleteListener);
-    method public void setOnTimedMetaDataListener(android.media.MediaPlayer.OnTimedMetaDataListener);
+    method public void setOnTimedMetaDataAvailableListener(android.media.MediaPlayer.OnTimedMetaDataAvailableListener);
     method public void setOnTimedTextListener(android.media.MediaPlayer.OnTimedTextListener);
     method public void setOnVideoSizeChangedListener(android.media.MediaPlayer.OnVideoSizeChangedListener);
     method public void setPlaybackParams(android.media.PlaybackParams);
@@ -17382,8 +17382,8 @@ package android.media {
     method public abstract void onSeekComplete(android.media.MediaPlayer);
   }
 
-  public static abstract interface MediaPlayer.OnTimedMetaDataListener {
-    method public abstract void onTimedMetaData(android.media.MediaPlayer, android.media.TimedMetaData);
+  public static abstract interface MediaPlayer.OnTimedMetaDataAvailableListener {
+    method public abstract void onTimedMetaDataAvailable(android.media.MediaPlayer, android.media.TimedMetaData);
   }
 
   public static abstract interface MediaPlayer.OnTimedTextListener {
@@ -17926,9 +17926,9 @@ package android.media {
     field public static final int OPTIONS_RECYCLE_INPUT = 2; // 0x2
   }
 
-  public class TimedMetaData {
-    method public byte[] getRawData();
-    method public long getTimeUs();
+  public final class TimedMetaData {
+    method public byte[] getMetaData();
+    method public long getTimestamp();
   }
 
   public final class TimedText {

media/java/android/media/MediaPlayer.java

@@ -2866,14 +2866,14 @@ public class MediaPlayer implements SubtitleController.Listener
                 return;
 
             case MEDIA_META_DATA:
-                if (mOnTimedMetaDataListener == null) {
+                if (mOnTimedMetaDataAvailableListener == null) {
                     return;
                 }
                 if (msg.obj instanceof Parcel) {
                     Parcel parcel = (Parcel) msg.obj;
                     TimedMetaData data = TimedMetaData.createTimedMetaDataFromParcel(parcel);
                     parcel.recycle();
-                    mOnTimedMetaDataListener.onTimedMetaData(mMediaPlayer, data);
+                    mOnTimedMetaDataAvailableListener.onTimedMetaDataAvailable(mMediaPlayer, data);
                 }
                 return;
 
@@ -3117,9 +3117,9 @@ public class MediaPlayer implements SubtitleController.Listener
      * Interface definition of a callback to be invoked when a
      * track has timed metadata available.
      *
-     * @see MediaPlayer#setOnTimedMetaDataListener(OnTimedMetaDataListener)
+     * @see MediaPlayer#setOnTimedMetaDataAvailableListener(OnTimedMetaDataAvailableListener)
      */
-    public interface OnTimedMetaDataListener
+    public interface OnTimedMetaDataAvailableListener
     {
         /**
          * Called to indicate avaliable timed metadata
@@ -3131,7 +3131,7 @@ public class MediaPlayer implements SubtitleController.Listener
          * @param mp             the MediaPlayer associated with this callback
          * @param data           the timed metadata sample associated with this event
          */
-        public void onTimedMetaData(MediaPlayer mp, TimedMetaData data);
+        public void onTimedMetaDataAvailable(MediaPlayer mp, TimedMetaData data);
     }
 
     /**
@@ -3141,17 +3141,17 @@ public class MediaPlayer implements SubtitleController.Listener
      * {@link TimedMetaData}.
      *
      * @see MediaPlayer#selectTrack(int)
-     * @see MediaPlayer.OnTimedMetaDataListener
+     * @see MediaPlayer.OnTimedMetaDataAvailableListener
      * @see TimedMetaData
      *
      * @param listener the callback that will be run
      */
-    public void setOnTimedMetaDataListener(OnTimedMetaDataListener listener)
+    public void setOnTimedMetaDataAvailableListener(OnTimedMetaDataAvailableListener listener)
     {
-        mOnTimedMetaDataListener = listener;
+        mOnTimedMetaDataAvailableListener = listener;
     }
 
-    private OnTimedMetaDataListener mOnTimedMetaDataListener;
+    private OnTimedMetaDataAvailableListener mOnTimedMetaDataAvailableListener;
 
     /* Do not change these values without updating their counterparts
      * in include/media/mediaplayer.h!

media/java/android/media/TimedMetaData.java

@@ -19,21 +19,20 @@ package android.media;
 import android.os.Parcel;
 
 /**
- * Class that embodies a piece of timed metadata, including
+ * Class that embodies one timed metadata access unit, including
  *
  * <ul>
  * <li> a time stamp, and </li>
  * <li> raw uninterpreted byte-array extracted directly from the container. </li>
  * </ul>
  *
- * @see MediaPlayer#setOnTimedMetaDataListener(android.media.MediaPlayer.OnTimedMetaDataListener)
+ * @see MediaPlayer#setOnTimedMetaDataAvailableListener(android.media.MediaPlayer.OnTimedMetaDataListener)
  */
-
-public class TimedMetaData {
+public final class TimedMetaData {
     private static final String TAG = "TimedMetaData";
 
-    private long mTimeUs;
-    private byte[] mRawData;
+    private long mTimestampUs;
+    private byte[] mMetaData;
 
     /**
      * @hide
@@ -48,12 +47,20 @@ public class TimedMetaData {
         }
     }
 
-    public long getTimeUs() {
-        return mTimeUs;
+    /**
+     * @return the timestamp associated with this metadata access unit in microseconds;
+     * 0 denotes playback start.
+     */
+    public long getTimestamp() {
+        return mTimestampUs;
     }
 
-    public byte[] getRawData() {
-        return mRawData;
+    /**
+     * @return raw, uninterpreted content of this metadata access unit; for ID3 tags this includes
+     * everything starting from the 3 byte signature "ID3".
+     */
+    public byte[] getMetaData() {
+        return mMetaData;
     }
 
     private boolean parseParcel(Parcel parcel) {
@@ -62,9 +69,9 @@ public class TimedMetaData {
             return false;
         }
 
-        mTimeUs = parcel.readLong();
-        mRawData = new byte[parcel.readInt()];
-        parcel.readByteArray(mRawData);
+        mTimestampUs = parcel.readLong();
+        mMetaData = new byte[parcel.readInt()];
+        parcel.readByteArray(mMetaData);
 
         return true;
     }