From 5df18392633f339cea55fe3c01472ce839984b98 Mon Sep 17 00:00:00 2001
From: Jaewan Kim <jaewan@google.com>
Date: Tue, 20 Mar 2018 15:07:00 +0900
Subject: [PATCH] MediaPlaylistAgent: Add getMediaItem()

Provide a way for a custom MediaPlaylistAgent to tell which
MediaItem2 maps to the DataSourceDesc from the
MediaPlayerBase#PlayerEventCallback.

Bug: 74316764, Bug: 75500592
Test: Run CTS with MediaComponents/runcts.sh
Change-Id: I45c9893bf74b2635f31949be537885a79860cfb3
---
 .../java/android/media/MediaPlaylistAgent.java  | 17 +++++++++++------
 1 file changed, 11 insertions(+), 6 deletions(-)

diff --git a/media/java/android/media/MediaPlaylistAgent.java b/media/java/android/media/MediaPlaylistAgent.java
index 453e24a63f521..f3392291becd6 100644
--- a/media/java/android/media/MediaPlaylistAgent.java
+++ b/media/java/android/media/MediaPlaylistAgent.java
@@ -337,16 +337,21 @@ public abstract class MediaPlaylistAgent {
     }
 
     /**
-     * Gets a {@link MediaItem2} in the playlist that matches given {@code dsd}.
-     * You can override this method to have more finer control of updating {@link DataSourceDesc}
-     * on items in the playlist.
+     * Called by {@link MediaSession2} when it wants to translate {@link DataSourceDesc} from the
+     * {@link MediaPlayerBase.PlayerEventCallback} to the {@link MediaItem2}. Override this method
+     * if you want to create {@link DataSourceDesc}s dynamically, instead of specifying them with
+     * {@link #setPlaylist(List, MediaMetadata2)}.
+     * <p>
+     * Session would throw an exception if this returns {@code null} for {@param dsd} from the
+     * {@link MediaPlayerBase.PlayerEventCallback}.
+     * <p>
+     * Default implementation calls the {@link #getPlaylist()} and searches the {@link MediaItem2}
+     * with the {@param dsd}.
      *
+     * @param dsd The dsd to query.
      * @return A {@link MediaItem2} object in the playlist that matches given {@code dsd}.
-     *         {@code null} if playlist is not set, or if the playlist has no matching item.
      * @throws IllegalArgumentException if {@code dsd} is null
-     * @hide
      */
-    // TODO(jaewan): Unhide
     public @Nullable MediaItem2 getMediaItem(@NonNull DataSourceDesc dsd) {
         return mProvider.getMediaItem_impl(dsd);
     }