Squash commits of the following patches, cherry-picked from other branch - do not merge.

o Prepare for publishing MediaMetadataRetriever as public API
  step one:
  o replaced captureFrame with getFrameAtTime
  o removed getMode

o Replace MediaMetadataRetriever.captureFrame() with MediaMetadataRetriever.getFrameAtTime()
  as part of the preparation for publishing MediaMetadataRetriever as public Java API

o Remove captureFrame from MediaMetadataRetriever.java class
  It has been replaced by getFrameAtTime() method

o Replace extractAlbumArt() with getEmbeddedPicture() in MediaMetadataRetriever.java

o Publish MediaMetadataRetriever.java as public API
  o Removed setMode() methods and related mode constants
  o Removed some of the unused the metadata keys
  o Updated the javadoc
  o part of a multi-project change.

bug - 3309041

Change-Id: I2efb6e8b8d52897186b016cb4efda6862f5584c4

2 files changed, 197 insertions, 59 deletions

diff --git a/media/java/android/media/MediaMetadataRetriever.java b/media/java/android/media/MediaMetadataRetriever.java
index 008528d..77e939e 100644
--- a/media/java/android/media/MediaMetadataRetriever.java
+++ b/media/java/android/media/MediaMetadataRetriever.java
@@ -29,7 +29,6 @@ import java.io.IOException;
 /**
  * MediaMetadataRetriever class provides a unified interface for retrieving
  * frame and meta data from an input media file.
- * {@hide}
  */
 public class MediaMetadataRetriever
 {
@@ -42,41 +41,13 @@ public class MediaMetadataRetriever
     @SuppressWarnings("unused")
     private int mNativeContext;
  
+    private static final int EMBEDDED_PICTURE_TYPE_ANY = 0xFFFF;
+
     public MediaMetadataRetriever() {
         native_setup();
     }
 
     /**
-     * Call this method before setDataSource() so that the mode becomes
-     * effective for subsequent operations. This method can be called only once
-     * at the beginning if the intended mode of operation for a
-     * MediaMetadataRetriever object remains the same for its whole lifetime,
-     * and thus it is unnecessary to call this method each time setDataSource()
-     * is called. If this is not never called (which is allowed), by default the
-     * intended mode of operation is to both capture frame and retrieve meta
-     * data (i.e., MODE_GET_METADATA_ONLY | MODE_CAPTURE_FRAME_ONLY).
-     * Often, this may not be what one wants, since doing this has negative
-     * performance impact on execution time of a call to setDataSource(), since
-     * both types of operations may be time consuming.
-     * 
-     * @param mode The intended mode of operation. Can be any combination of 
-     * MODE_GET_METADATA_ONLY and MODE_CAPTURE_FRAME_ONLY:
-     * 1. MODE_GET_METADATA_ONLY & MODE_CAPTURE_FRAME_ONLY: 
-     *    For neither frame capture nor meta data retrieval
-     * 2. MODE_GET_METADATA_ONLY: For meta data retrieval only
-     * 3. MODE_CAPTURE_FRAME_ONLY: For frame capture only
-     * 4. MODE_GET_METADATA_ONLY | MODE_CAPTURE_FRAME_ONLY: 
-     *    For both frame capture and meta data retrieval
-     */
-    public native void setMode(int mode);
-    
-    /**
-     * @return the current mode of operation. A negative return value indicates
-     * some runtime error has occurred.
-     */
-    public native int getMode();
-
-    /**
      * Sets the data source (file pathname) to use. Call this
      * method before the rest of the methods in this class. This method may be
      * time-consuming.
@@ -190,22 +161,99 @@ public class MediaMetadataRetriever
 
     /**
      * Call this method after setDataSource(). This method finds a
-     * representative frame if successful and returns it as a bitmap. This is
-     * useful for generating a thumbnail for an input media source.
-     * 
+     * representative frame close to the given time position by considering
+     * the given option if possible, and returns it as a bitmap. This is
+     * useful for generating a thumbnail for an input data source or just
+     * obtain and display a frame at the given time position.
+     *
+     * @param timeUs The time position where the frame will be retrieved.
+     * When retrieving the frame at the given time position, there is no
+     * guarantee that the data source has a frame located at the position.
+     * When this happens, a frame nearby will be returned. If timeUs is
+     * negative, time position and option will ignored, and any frame
+     * that the implementation considers as representative may be returned.
+     *
+     * @param option a hint on how the frame is found. Use
+     * {@link #OPTION_PREVIOUS_SYNC} if one wants to retrieve a sync frame
+     * that has a timestamp earlier than or the same as timeUs. Use
+     * {@link #OPTION_NEXT_SYNC} if one wants to retrieve a sync frame
+     * that has a timestamp later than or the same as timeUs. Use
+     * {@link #OPTION_CLOSEST_SYNC} if one wants to retrieve a sync frame
+     * that has a timestamp closest to or the same as timeUs. Use
+     * {@link #OPTION_CLOSEST} if one wants to retrieve a frame that may
+     * or may not be a sync frame but is closest to or the same as timeUs.
+     * {@link #OPTION_CLOSEST} often has larger performance overhead compared
+     * to the other options if there is no sync frame located at timeUs.
+     *
      * @return A Bitmap containing a representative video frame, which 
      *         can be null, if such a frame cannot be retrieved.
      */
-    public native Bitmap captureFrame();
+    public Bitmap getFrameAtTime(long timeUs, int option) {
+        if (option < OPTION_PREVIOUS_SYNC ||
+            option > OPTION_CLOSEST) {
+            throw new IllegalArgumentException("Unsupported option: " + option);
+        }
+
+        return _getFrameAtTime(timeUs, option);
+    }
+
+    /**
+     * Call this method after setDataSource(). This method finds a
+     * representative frame close to the given time position if possible,
+     * and returns it as a bitmap. This is useful for generating a thumbnail
+     * for an input data source. Call this method if one does not care
+     * how the frame is found as long as it is close to the given time;
+     * otherwise, please call {@link #getFrameAtTime(long, int)}.
+     *
+     * @param timeUs The time position where the frame will be retrieved.
+     * When retrieving the frame at the given time position, there is no
+     * guarentee that the data source has a frame located at the position.
+     * When this happens, a frame nearby will be returned. If timeUs is
+     * negative, time position and option will ignored, and any frame
+     * that the implementation considers as representative may be returned.
+     *
+     * @return A Bitmap containing a representative video frame, which
+     *         can be null, if such a frame cannot be retrieved.
+     *
+     * @see #getFrameAtTime(long, int)
+     */
+    public Bitmap getFrameAtTime(long timeUs) {
+        return getFrameAtTime(timeUs, OPTION_CLOSEST_SYNC);
+    }
+
+    /**
+     * Call this method after setDataSource(). This method finds a
+     * representative frame at any time position if possible,
+     * and returns it as a bitmap. This is useful for generating a thumbnail
+     * for an input data source. Call this method if one does not
+     * care about where the frame is located; otherwise, please call
+     * {@link #getFrameAtTime(long)} or {@link #getFrameAtTime(long, int)}
+     *
+     * @return A Bitmap containing a representative video frame, which
+     *         can be null, if such a frame cannot be retrieved.
+     *
+     * @see #getFrameAtTime(long)
+     * @see #getFrameAtTime(long, int)
+     */
+    public Bitmap getFrameAtTime() {
+        return getFrameAtTime(-1, OPTION_CLOSEST_SYNC);
+    }
+
+    private native Bitmap _getFrameAtTime(long timeUs, int option);
+
     
     /**
      * Call this method after setDataSource(). This method finds the optional
-     * graphic or album art associated (embedded or external url linked) the 
-     * related data source.
+     * graphic or album art associated associated with the data source. If
+     * there are more than one pictures, (any) one of them is returned.
      * 
      * @return null if no such graphic is found.
      */
-    public native byte[] extractAlbumArt();
+    public byte[] getEmbeddedPicture() {
+        return getEmbeddedPicture(EMBEDDED_PICTURE_TYPE_ANY);
+    }
+
+    private native byte[] getEmbeddedPicture(int pictureType);
 
     /**
      * Call it when one is done with the object. This method releases the memory
@@ -226,38 +274,129 @@ public class MediaMetadataRetriever
         }
     }
 
-    public static final int MODE_GET_METADATA_ONLY  = 0x01;
-    public static final int MODE_CAPTURE_FRAME_ONLY = 0x02;
+    /**
+     * Option used in method {@link #getFrameAtTime(long, int)} to get a
+     * frame at a specified location.
+     *
+     * @see #getFrameAtTime(long, int)
+     */
+    /* Do not change these option values without updating their counterparts
+     * in include/media/stagefright/MediaSource.h!
+     */
+    /**
+     * This option is used with {@link #getFrameAtTime(long, int)} to retrieve
+     * a sync (or key) frame associated with a data source that is located
+     * right before or at the given time.
+     *
+     * @see #getFrameAtTime(long, int)
+     */
+    public static final int OPTION_PREVIOUS_SYNC    = 0x00;
+    /**
+     * This option is used with {@link #getFrameAtTime(long, int)} to retrieve
+     * a sync (or key) frame associated with a data source that is located
+     * right after or at the given time.
+     *
+     * @see #getFrameAtTime(long, int)
+     */
+    public static final int OPTION_NEXT_SYNC        = 0x01;
+    /**
+     * This option is used with {@link #getFrameAtTime(long, int)} to retrieve
+     * a sync (or key) frame associated with a data source that is located
+     * closest to (in time) or at the given time.
+     *
+     * @see #getFrameAtTime(long, int)
+     */
+    public static final int OPTION_CLOSEST_SYNC     = 0x02;
+    /**
+     * This option is used with {@link #getFrameAtTime(long, int)} to retrieve
+     * a frame (not necessarily a key frame) associated with a data source that
+     * is located closest to or at the given time.
+     *
+     * @see #getFrameAtTime(long, int)
+     */
+    public static final int OPTION_CLOSEST          = 0x03;
 
     /*
-     * Do not change these values without updating their counterparts
-     * in include/media/mediametadataretriever.h!
+     * Do not change these metadata key values without updating their
+     * counterparts in include/media/mediametadataretriever.h!
+     */
+    /**
+     * The metadata key to retrieve the numberic string describing the
+     * order of the audio data source on its original recording.
      */
     public static final int METADATA_KEY_CD_TRACK_NUMBER = 0;
+    /**
+     * The metadata key to retrieve the information about the album title
+     * of the data source.
+     */
     public static final int METADATA_KEY_ALBUM           = 1;
+    /**
+     * The metadata key to retrieve the information about the artist of
+     * the data source.
+     */
     public static final int METADATA_KEY_ARTIST          = 2;
+    /**
+     * The metadata key to retrieve the information about the author of
+     * the data source.
+     */
     public static final int METADATA_KEY_AUTHOR          = 3;
+    /**
+     * The metadata key to retrieve the information about the composer of
+     * the data source.
+     */
     public static final int METADATA_KEY_COMPOSER        = 4;
+    /**
+     * The metadata key to retrieve the date when the data source was created
+     * or modified.
+     */
     public static final int METADATA_KEY_DATE            = 5;
+    /**
+     * The metadata key to retrieve the content type or genre of the data
+     * source.
+     */
     public static final int METADATA_KEY_GENRE           = 6;
+    /**
+     * The metadata key to retrieve the data source title.
+     */
     public static final int METADATA_KEY_TITLE           = 7;
+    /**
+     * The metadata key to retrieve the year when the data source was created
+     * or modified.
+     */
     public static final int METADATA_KEY_YEAR            = 8;
+    /**
+     * The metadata key to retrieve the playback duration of the data source.
+     */
     public static final int METADATA_KEY_DURATION        = 9;
+    /**
+     * The metadata key to retrieve the number of tracks, such as audio, video,
+     * text, in the data source, such as a mp4 or 3gpp file.
+     */
     public static final int METADATA_KEY_NUM_TRACKS      = 10;
-    public static final int METADATA_KEY_IS_DRM_CRIPPLED = 11;
-    public static final int METADATA_KEY_CODEC           = 12;
-    public static final int METADATA_KEY_RATING          = 13;
-    public static final int METADATA_KEY_COMMENT         = 14;
-    public static final int METADATA_KEY_COPYRIGHT       = 15;
-    public static final int METADATA_KEY_BIT_RATE        = 16;
-    public static final int METADATA_KEY_FRAME_RATE      = 17;
-    public static final int METADATA_KEY_VIDEO_FORMAT    = 18;
-    public static final int METADATA_KEY_VIDEO_HEIGHT    = 19;
-    public static final int METADATA_KEY_VIDEO_WIDTH     = 20;
-    public static final int METADATA_KEY_WRITER          = 21;
-    public static final int METADATA_KEY_MIMETYPE        = 22;
-    public static final int METADATA_KEY_DISCNUMBER      = 23;
-    public static final int METADATA_KEY_ALBUMARTIST     = 24;
-    public static final int METADATA_KEY_COMPILATION     = 25;
+    /**
+     * The metadata key to retrieve the information of the writer (such as
+     * lyricist) of the data source.
+     */
+    public static final int METADATA_KEY_WRITER          = 11;
+    /**
+     * The metadata key to retrieve the mime type of the data source. Some
+     * example mime types include: "video/mp4", "audio/mp4", "audio/amr-wb",
+     * etc.
+     */
+    public static final int METADATA_KEY_MIMETYPE        = 12;
+    /**
+     * The metadata key to retrieve the information about the performers or
+     * artist associated with the data source.
+     */
+    public static final int METADATA_KEY_ALBUMARTIST     = 13;
+    /**
+     * The metadata key to retrieve the numberic string that describes which
+     * part of a set the audio data source comes from.
+     */
+    public static final int METADATA_KEY_DISC_NUMBER     = 14;
+    /**
+     * The metadata key to retrieve the music album compilation status.
+     */
+    public static final int METADATA_KEY_COMPILATION     = 15;
     // Add more here...
 }
diff --git a/media/java/android/media/ThumbnailUtils.java b/media/java/android/media/ThumbnailUtils.java
index 3d85e31..494b4cb 100644
--- a/media/java/android/media/ThumbnailUtils.java
+++ b/media/java/android/media/ThumbnailUtils.java
@@ -146,9 +146,8 @@ public class ThumbnailUtils {
         Bitmap bitmap = null;
         MediaMetadataRetriever retriever = new MediaMetadataRetriever();
         try {
-            retriever.setMode(MediaMetadataRetriever.MODE_CAPTURE_FRAME_ONLY);
             retriever.setDataSource(filePath);
-            bitmap = retriever.captureFrame();
+            bitmap = retriever.getFrameAtTime(-1);
         } catch (IllegalArgumentException ex) {
             // Assume this is a corrupt video file
         } catch (RuntimeException ex) {