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
diff --git a/media/libmedia/IMediaMetadataRetriever.cpp b/media/libmedia/IMediaMetadataRetriever.cpp
index e529d25..d5298c9 100644
--- a/media/libmedia/IMediaMetadataRetriever.cpp
+++ b/media/libmedia/IMediaMetadataRetriever.cpp
@@ -81,9 +81,7 @@
     DISCONNECT = IBinder::FIRST_CALL_TRANSACTION,
     SET_DATA_SOURCE_URL,
     SET_DATA_SOURCE_FD,
-    SET_MODE,
-    GET_MODE,
-    CAPTURE_FRAME,
+    GET_FRAME_AT_TIME,
     EXTRACT_ALBUM_ART,
     EXTRACT_METADATA,
 };
@@ -124,32 +122,17 @@
         return reply.readInt32();
     }
 
-    status_t setMode(int mode)
+    sp<IMemory> getFrameAtTime(int64_t timeUs, int option)
     {
+        LOGV("getTimeAtTime: time(%lld us) and option(%d)", timeUs, option);
         Parcel data, reply;
         data.writeInterfaceToken(IMediaMetadataRetriever::getInterfaceDescriptor());
-        data.writeInt32(mode);
-        remote()->transact(SET_MODE, data, &reply);
-        return reply.readInt32();
-    }
-
-    status_t getMode(int* mode) const
-    {
-        Parcel data, reply;
-        data.writeInterfaceToken(IMediaMetadataRetriever::getInterfaceDescriptor());
-        remote()->transact(GET_MODE, data, &reply);
-        *mode = reply.readInt32();
-        return reply.readInt32();
-    }
-
-    sp<IMemory> captureFrame()
-    {
-        Parcel data, reply;
-        data.writeInterfaceToken(IMediaMetadataRetriever::getInterfaceDescriptor());
+        data.writeInt64(timeUs);
+        data.writeInt32(option);
 #ifndef DISABLE_GROUP_SCHEDULE_HACK
         sendSchedPolicy(data);
 #endif
-        remote()->transact(CAPTURE_FRAME, data, &reply);
+        remote()->transact(GET_FRAME_AT_TIME, data, &reply);
         status_t ret = reply.readInt32();
         if (ret != NO_ERROR) {
             return NULL;
@@ -216,26 +199,15 @@
             reply->writeInt32(setDataSource(fd, offset, length));
             return NO_ERROR;
         } break;
-        case SET_MODE: {
+        case GET_FRAME_AT_TIME: {
             CHECK_INTERFACE(IMediaMetadataRetriever, data, reply);
-            int mode = data.readInt32();
-            reply->writeInt32(setMode(mode));
-            return NO_ERROR;
-        } break;
-        case GET_MODE: {
-            CHECK_INTERFACE(IMediaMetadataRetriever, data, reply);
-            int mode;
-            status_t status = getMode(&mode);
-            reply->writeInt32(mode);
-            reply->writeInt32(status);
-            return NO_ERROR;
-        } break;
-        case CAPTURE_FRAME: {
-            CHECK_INTERFACE(IMediaMetadataRetriever, data, reply);
+            int64_t timeUs = data.readInt64();
+            int option = data.readInt32();
+            LOGV("getTimeAtTime: time(%lld us) and option(%d)", timeUs, option);
 #ifndef DISABLE_GROUP_SCHEDULE_HACK
             setSchedPolicy(data);
 #endif
-            sp<IMemory> bitmap = captureFrame();
+            sp<IMemory> bitmap = getFrameAtTime(timeUs, option);
             if (bitmap != 0) {  // Don't send NULL across the binder interface
                 reply->writeInt32(NO_ERROR);
                 reply->writeStrongBinder(bitmap->asBinder());
diff --git a/media/libmedia/mediametadataretriever.cpp b/media/libmedia/mediametadataretriever.cpp
index e2712ba..8dfcb3b 100644
--- a/media/libmedia/mediametadataretriever.cpp
+++ b/media/libmedia/mediametadataretriever.cpp
@@ -123,37 +123,15 @@
     return mRetriever->setDataSource(fd, offset, length);
 }
 
-status_t MediaMetadataRetriever::setMode(int mode)
+sp<IMemory> MediaMetadataRetriever::getFrameAtTime(int64_t timeUs, int option)
 {
-    LOGV("setMode(%d)", mode);
-    Mutex::Autolock _l(mLock);
-    if (mRetriever == 0) {
-        LOGE("retriever is not initialized");
-        return INVALID_OPERATION;
-    }
-    return mRetriever->setMode(mode);
-}
-
-status_t MediaMetadataRetriever::getMode(int* mode)
-{
-    LOGV("getMode");
-    Mutex::Autolock _l(mLock);
-    if (mRetriever == 0) {
-        LOGE("retriever is not initialized");
-        return INVALID_OPERATION;
-    }
-    return mRetriever->getMode(mode);
-}
-
-sp<IMemory> MediaMetadataRetriever::captureFrame()
-{
-    LOGV("captureFrame");
+    LOGV("getFrameAtTime: time(%lld us) option(%d)", timeUs, option);
     Mutex::Autolock _l(mLock);
     if (mRetriever == 0) {
         LOGE("retriever is not initialized");
         return NULL;
     }
-    return mRetriever->captureFrame();
+    return mRetriever->getFrameAtTime(timeUs, option);
 }
 
 const char* MediaMetadataRetriever::extractMetadata(int keyCode)
diff --git a/media/libmediaplayerservice/MetadataRetrieverClient.cpp b/media/libmediaplayerservice/MetadataRetrieverClient.cpp
index 39fce81..713e441 100644
--- a/media/libmediaplayerservice/MetadataRetrieverClient.cpp
+++ b/media/libmediaplayerservice/MetadataRetrieverClient.cpp
@@ -65,7 +65,6 @@
     mThumbnail = NULL;
     mAlbumArt = NULL;
     mRetriever = NULL;
-    mMode = METADATA_MODE_FRAME_CAPTURE_AND_METADATA_RETRIEVAL;
 }
 
 MetadataRetrieverClient::~MetadataRetrieverClient()
@@ -80,7 +79,7 @@
     char buffer[SIZE];
     String8 result;
     result.append(" MetadataRetrieverClient\n");
-    snprintf(buffer, 255, "  pid(%d) mode(%d)\n", mPid, mMode);
+    snprintf(buffer, 255, "  pid(%d)\n", mPid);
     result.append(buffer);
     write(fd, result.string(), result.size());
     write(fd, "\n", 1);
@@ -94,7 +93,6 @@
     mRetriever.clear();
     mThumbnail.clear();
     mAlbumArt.clear();
-    mMode = METADATA_MODE_FRAME_CAPTURE_AND_METADATA_RETRIEVAL;
     IPCThreadState::self()->flushCommands();
 }
 
@@ -140,10 +138,7 @@
     LOGV("player type = %d", playerType);
     sp<MediaMetadataRetrieverBase> p = createRetriever(playerType);
     if (p == NULL) return NO_INIT;
-    status_t ret = p->setMode(mMode);
-    if (ret == NO_ERROR) {
-        ret = p->setDataSource(url);
-    }
+    status_t ret = p->setDataSource(url);
     if (ret == NO_ERROR) mRetriever = p;
     return ret;
 }
@@ -181,55 +176,22 @@
         ::close(fd);
         return NO_INIT;
     }
-    status_t status = p->setMode(mMode);
-    if (status == NO_ERROR) {
-        p->setDataSource(fd, offset, length);
-    }
+    status_t status = p->setDataSource(fd, offset, length);
     if (status == NO_ERROR) mRetriever = p;
     ::close(fd);
     return status;
 }
 
-status_t MetadataRetrieverClient::setMode(int mode)
+sp<IMemory> MetadataRetrieverClient::getFrameAtTime(int64_t timeUs, int option)
 {
-    LOGV("setMode");
-    Mutex::Autolock lock(mLock);
-    if (mode < METADATA_MODE_NOOP ||
-        mode > METADATA_MODE_FRAME_CAPTURE_AND_METADATA_RETRIEVAL) {
-        LOGE("invalid mode %d", mode);
-        return BAD_VALUE;
-    }
-    mMode = mode;
-    return NO_ERROR;
-}
-
-status_t MetadataRetrieverClient::getMode(int* mode) const
-{
-    LOGV("getMode");
-    Mutex::Autolock lock(mLock);
-
-    // TODO:
-    // This may not be necessary.
-    // If setDataSource() has not been called, return the cached value
-    // otherwise, return the value retrieved from the retriever
-    if (mRetriever == NULL) {
-        *mode = mMode;
-    } else {
-        mRetriever->getMode(mode);
-    }
-    return NO_ERROR;
-}
-
-sp<IMemory> MetadataRetrieverClient::captureFrame()
-{
-    LOGV("captureFrame");
+    LOGV("getFrameAtTime: time(%lld us) option(%d)", timeUs, option);
     Mutex::Autolock lock(mLock);
     mThumbnail.clear();
     if (mRetriever == NULL) {
         LOGE("retriever is not initialized");
         return NULL;
     }
-    VideoFrame *frame = mRetriever->captureFrame();
+    VideoFrame *frame = mRetriever->getFrameAtTime(timeUs, option);
     if (frame == NULL) {
         LOGE("failed to capture a video frame");
         return NULL;
diff --git a/media/libmediaplayerservice/MetadataRetrieverClient.h b/media/libmediaplayerservice/MetadataRetrieverClient.h
index 4aab94f..b834715 100644
--- a/media/libmediaplayerservice/MetadataRetrieverClient.h
+++ b/media/libmediaplayerservice/MetadataRetrieverClient.h
@@ -43,9 +43,7 @@
     virtual void                    disconnect();
     virtual status_t                setDataSource(const char *url);
     virtual status_t                setDataSource(int fd, int64_t offset, int64_t length);
-    virtual status_t                setMode(int mode);
-    virtual status_t                getMode(int* mode) const;
-    virtual sp<IMemory>             captureFrame();
+    virtual sp<IMemory>             getFrameAtTime(int64_t timeUs, int option);
     virtual sp<IMemory>             extractAlbumArt();
     virtual const char*             extractMetadata(int keyCode);
 
@@ -60,7 +58,6 @@
     mutable Mutex                          mLock;
     sp<MediaMetadataRetrieverBase>         mRetriever;
     pid_t                                  mPid;
-    int                                    mMode;
 
     // Keep the shared memory copy of album art and capture frame (for thumbnail)
     sp<IMemory>                            mAlbumArt;
diff --git a/media/libstagefright/StagefrightMediaScanner.cpp b/media/libstagefright/StagefrightMediaScanner.cpp
index d3aa2f6..10c6e41 100644
--- a/media/libstagefright/StagefrightMediaScanner.cpp
+++ b/media/libstagefright/StagefrightMediaScanner.cpp
@@ -130,9 +130,7 @@
         return HandleMIDI(path, &client);
     }
 
-    if (mRetriever->setDataSource(path) == OK
-            && mRetriever->setMode(
-                METADATA_MODE_METADATA_RETRIEVAL_ONLY) == OK) {
+    if (mRetriever->setDataSource(path) == OK) {
         const char *value;
         if ((value = mRetriever->extractMetadata(
                         METADATA_KEY_MIMETYPE)) != NULL) {
@@ -181,9 +179,7 @@
     }
     lseek(fd, 0, SEEK_SET);
 
-    if (mRetriever->setDataSource(fd, 0, size) == OK
-            && mRetriever->setMode(
-                METADATA_MODE_FRAME_CAPTURE_ONLY) == OK) {
+    if (mRetriever->setDataSource(fd, 0, size) == OK) {
         sp<IMemory> mem = mRetriever->extractAlbumArt();
 
         if (mem != NULL) {
diff --git a/media/libstagefright/StagefrightMetadataRetriever.cpp b/media/libstagefright/StagefrightMetadataRetriever.cpp
index ac208cd..e8f4839 100644
--- a/media/libstagefright/StagefrightMetadataRetriever.cpp
+++ b/media/libstagefright/StagefrightMetadataRetriever.cpp
@@ -108,7 +108,10 @@
 static VideoFrame *extractVideoFrameWithCodecFlags(
         OMXClient *client,
         const sp<MetaData> &trackMeta,
-        const sp<MediaSource> &source, uint32_t flags) {
+        const sp<MediaSource> &source,
+        uint32_t flags,
+        int64_t frameTimeUs,
+        int seekMode) {
     sp<MediaSource> decoder =
         OMXCodec::Create(
                 client->interface(), source->getFormat(), false, source,
@@ -130,11 +133,22 @@
     // and spurious empty buffers.
 
     MediaSource::ReadOptions options;
+    if (seekMode < MediaSource::ReadOptions::SEEK_PREVIOUS_SYNC ||
+        seekMode > MediaSource::ReadOptions::SEEK_CLOSEST) {
+
+        LOGE("Unknown seek mode: %d", seekMode);
+        return NULL;
+    }
+
+    MediaSource::ReadOptions::SeekMode mode =
+            static_cast<MediaSource::ReadOptions::SeekMode>(seekMode);
+
     int64_t thumbNailTime;
-    if (trackMeta->findInt64(kKeyThumbnailTime, &thumbNailTime)) {
-        options.setSeekTo(thumbNailTime);
+    if (frameTimeUs < 0 && trackMeta->findInt64(kKeyThumbnailTime, &thumbNailTime)) {
+        options.setSeekTo(thumbNailTime, mode);
     } else {
         thumbNailTime = -1;
+        options.setSeekTo(frameTimeUs, mode);
     }
 
     MediaBuffer *buffer = NULL;
@@ -226,14 +240,10 @@
     return frame;
 }
 
-VideoFrame *StagefrightMetadataRetriever::captureFrame() {
-    LOGV("captureFrame");
+VideoFrame *StagefrightMetadataRetriever::getFrameAtTime(
+        int64_t timeUs, int option) {
 
-    if (0 == (mMode & METADATA_MODE_FRAME_CAPTURE_ONLY)) {
-        LOGV("captureFrame disabled by mode (0x%08x)", mMode);
-
-        return NULL;
-    }
+    LOGV("getFrameAtTime: %lld us option: %d", timeUs, option);
 
     if (mExtractor.get() == NULL) {
         LOGV("no extractor.");
@@ -270,13 +280,15 @@
 
     VideoFrame *frame =
         extractVideoFrameWithCodecFlags(
-                &mClient, trackMeta, source, OMXCodec::kPreferSoftwareCodecs);
+                &mClient, trackMeta, source, OMXCodec::kPreferSoftwareCodecs,
+                timeUs, option);
 
     if (frame == NULL) {
         LOGV("Software decoder failed to extract thumbnail, "
              "trying hardware decoder.");
 
-        frame = extractVideoFrameWithCodecFlags(&mClient, trackMeta, source, 0);
+        frame = extractVideoFrameWithCodecFlags(&mClient, trackMeta, source, 0,
+                        timeUs, option);
     }
 
     return frame;
@@ -285,12 +297,6 @@
 MediaAlbumArt *StagefrightMetadataRetriever::extractAlbumArt() {
     LOGV("extractAlbumArt (extractor: %s)", mExtractor.get() != NULL ? "YES" : "NO");
 
-    if (0 == (mMode & METADATA_MODE_METADATA_RETRIEVAL_ONLY)) {
-        LOGV("extractAlbumArt/metadata retrieval disabled by mode");
-
-        return NULL;
-    }
-
     if (mExtractor == NULL) {
         return NULL;
     }
@@ -309,12 +315,6 @@
 }
 
 const char *StagefrightMetadataRetriever::extractMetadata(int keyCode) {
-    if (0 == (mMode & METADATA_MODE_METADATA_RETRIEVAL_ONLY)) {
-        LOGV("extractAlbumArt/metadata retrieval disabled by mode");
-
-        return NULL;
-    }
-
     if (mExtractor == NULL) {
         return NULL;
     }
diff --git a/media/libstagefright/include/StagefrightMetadataRetriever.h b/media/libstagefright/include/StagefrightMetadataRetriever.h
index b80387f..07b1ec8 100644
--- a/media/libstagefright/include/StagefrightMetadataRetriever.h
+++ b/media/libstagefright/include/StagefrightMetadataRetriever.h
@@ -35,7 +35,7 @@
     virtual status_t setDataSource(const char *url);
     virtual status_t setDataSource(int fd, int64_t offset, int64_t length);
 
-    virtual VideoFrame *captureFrame();
+    virtual VideoFrame *getFrameAtTime(int64_t timeUs, int option);
     virtual MediaAlbumArt *extractAlbumArt();
     virtual const char *extractMetadata(int keyCode);