1package android.media;
2
3import android.annotation.Nullable;
4import android.graphics.Bitmap;
5import android.media.browse.MediaBrowser;
6import android.net.Uri;
7import android.os.Bundle;
8import android.os.Parcel;
9import android.os.Parcelable;
10
11/**
12 * A simple set of metadata for a media item suitable for display. This can be
13 * created using the Builder or retrieved from existing metadata using
14 * {@link MediaMetadata#getDescription()}.
15 */
16public class MediaDescription implements Parcelable {
17    /**
18     * A unique persistent id for the content or null.
19     */
20    private final String mMediaId;
21    /**
22     * A primary title suitable for display or null.
23     */
24    private final CharSequence mTitle;
25    /**
26     * A subtitle suitable for display or null.
27     */
28    private final CharSequence mSubtitle;
29    /**
30     * A description suitable for display or null.
31     */
32    private final CharSequence mDescription;
33    /**
34     * A bitmap icon suitable for display or null.
35     */
36    private final Bitmap mIcon;
37    /**
38     * A Uri for an icon suitable for display or null.
39     */
40    private final Uri mIconUri;
41    /**
42     * Extras for opaque use by apps/system.
43     */
44    private final Bundle mExtras;
45    /**
46     * A Uri to identify this content.
47     */
48    private final Uri mMediaUri;
49
50    /**
51     * Used as a long extra field to indicate the bluetooth folder type of the media item as
52     * specified in the section 6.10.2.2 of the Bluetooth AVRCP 1.5. This is valid only for
53     * {@link MediaBrowser.MediaItem} with {@link MediaBrowser.MediaItem#FLAG_BROWSABLE}. The value
54     * should be one of the following:
55     * <ul>
56     * <li>{@link #BT_FOLDER_TYPE_MIXED}</li>
57     * <li>{@link #BT_FOLDER_TYPE_TITLES}</li>
58     * <li>{@link #BT_FOLDER_TYPE_ALBUMS}</li>
59     * <li>{@link #BT_FOLDER_TYPE_ARTISTS}</li>
60     * <li>{@link #BT_FOLDER_TYPE_GENRES}</li>
61     * <li>{@link #BT_FOLDER_TYPE_PLAYLISTS}</li>
62     * <li>{@link #BT_FOLDER_TYPE_YEARS}</li>
63     * </ul>
64     *
65     * @see #getExtras()
66     */
67    public static final String EXTRA_BT_FOLDER_TYPE = "android.media.extra.BT_FOLDER_TYPE";
68
69    /**
70     * The type of folder that is unknown or contains media elements of mixed types as specified in
71     * the section 6.10.2.2 of the Bluetooth AVRCP 1.5.
72     */
73    public static final long BT_FOLDER_TYPE_MIXED = 0;
74
75    /**
76     * The type of folder that contains media elements only as specified in the section 6.10.2.2 of
77     * the Bluetooth AVRCP 1.5.
78     */
79    public static final long BT_FOLDER_TYPE_TITLES = 1;
80
81    /**
82     * The type of folder that contains folders categorized by album as specified in the section
83     * 6.10.2.2 of the Bluetooth AVRCP 1.5.
84     */
85    public static final long BT_FOLDER_TYPE_ALBUMS = 2;
86
87    /**
88     * The type of folder that contains folders categorized by artist as specified in the section
89     * 6.10.2.2 of the Bluetooth AVRCP 1.5.
90     */
91    public static final long BT_FOLDER_TYPE_ARTISTS = 3;
92
93    /**
94     * The type of folder that contains folders categorized by genre as specified in the section
95     * 6.10.2.2 of the Bluetooth AVRCP 1.5.
96     */
97    public static final long BT_FOLDER_TYPE_GENRES = 4;
98
99    /**
100     * The type of folder that contains folders categorized by playlist as specified in the section
101     * 6.10.2.2 of the Bluetooth AVRCP 1.5.
102     */
103    public static final long BT_FOLDER_TYPE_PLAYLISTS = 5;
104
105    /**
106     * The type of folder that contains folders categorized by year as specified in the section
107     * 6.10.2.2 of the Bluetooth AVRCP 1.5.
108     */
109    public static final long BT_FOLDER_TYPE_YEARS = 6;
110
111    private MediaDescription(String mediaId, CharSequence title, CharSequence subtitle,
112            CharSequence description, Bitmap icon, Uri iconUri, Bundle extras, Uri mediaUri) {
113        mMediaId = mediaId;
114        mTitle = title;
115        mSubtitle = subtitle;
116        mDescription = description;
117        mIcon = icon;
118        mIconUri = iconUri;
119        mExtras = extras;
120        mMediaUri = mediaUri;
121    }
122
123    private MediaDescription(Parcel in) {
124        mMediaId = in.readString();
125        mTitle = in.readCharSequence();
126        mSubtitle = in.readCharSequence();
127        mDescription = in.readCharSequence();
128        mIcon = in.readParcelable(null);
129        mIconUri = in.readParcelable(null);
130        mExtras = in.readBundle();
131        mMediaUri = in.readParcelable(null);
132    }
133
134    /**
135     * Returns the media id or null. See
136     * {@link MediaMetadata#METADATA_KEY_MEDIA_ID}.
137     */
138    public @Nullable String getMediaId() {
139        return mMediaId;
140    }
141
142    /**
143     * Returns a title suitable for display or null.
144     *
145     * @return A title or null.
146     */
147    public @Nullable CharSequence getTitle() {
148        return mTitle;
149    }
150
151    /**
152     * Returns a subtitle suitable for display or null.
153     *
154     * @return A subtitle or null.
155     */
156    public @Nullable CharSequence getSubtitle() {
157        return mSubtitle;
158    }
159
160    /**
161     * Returns a description suitable for display or null.
162     *
163     * @return A description or null.
164     */
165    public @Nullable CharSequence getDescription() {
166        return mDescription;
167    }
168
169    /**
170     * Returns a bitmap icon suitable for display or null.
171     *
172     * @return An icon or null.
173     */
174    public @Nullable Bitmap getIconBitmap() {
175        return mIcon;
176    }
177
178    /**
179     * Returns a Uri for an icon suitable for display or null.
180     *
181     * @return An icon uri or null.
182     */
183    public @Nullable Uri getIconUri() {
184        return mIconUri;
185    }
186
187    /**
188     * Returns any extras that were added to the description.
189     *
190     * @return A bundle of extras or null.
191     */
192    public @Nullable Bundle getExtras() {
193        return mExtras;
194    }
195
196    /**
197     * Returns a Uri representing this content or null.
198     *
199     * @return A media Uri or null.
200     */
201    public @Nullable Uri getMediaUri() {
202        return mMediaUri;
203    }
204
205    @Override
206    public int describeContents() {
207        return 0;
208    }
209
210    @Override
211    public void writeToParcel(Parcel dest, int flags) {
212        dest.writeString(mMediaId);
213        dest.writeCharSequence(mTitle);
214        dest.writeCharSequence(mSubtitle);
215        dest.writeCharSequence(mDescription);
216        dest.writeParcelable(mIcon, flags);
217        dest.writeParcelable(mIconUri, flags);
218        dest.writeBundle(mExtras);
219        dest.writeParcelable(mMediaUri, flags);
220    }
221
222    @Override
223    public boolean equals(Object o) {
224        if (o == null) {
225            return false;
226        }
227
228        if (!(o instanceof MediaDescription)){
229            return false;
230        }
231
232        final MediaDescription d = (MediaDescription) o;
233
234        if (!String.valueOf(mTitle).equals(String.valueOf(d.mTitle))) {
235            return false;
236        }
237
238        if (!String.valueOf(mSubtitle).equals(String.valueOf(d.mSubtitle))) {
239            return false;
240        }
241
242        if (!String.valueOf(mDescription).equals(String.valueOf(d.mDescription))) {
243            return false;
244        }
245
246        return true;
247    }
248
249    @Override
250    public String toString() {
251        return mTitle + ", " + mSubtitle + ", " + mDescription;
252    }
253
254    public static final Parcelable.Creator<MediaDescription> CREATOR =
255            new Parcelable.Creator<MediaDescription>() {
256                @Override
257                public MediaDescription createFromParcel(Parcel in) {
258                    return new MediaDescription(in);
259                }
260
261                @Override
262                public MediaDescription[] newArray(int size) {
263                    return new MediaDescription[size];
264                }
265            };
266
267    /**
268     * Builder for {@link MediaDescription} objects.
269     */
270    public static class Builder {
271        private String mMediaId;
272        private CharSequence mTitle;
273        private CharSequence mSubtitle;
274        private CharSequence mDescription;
275        private Bitmap mIcon;
276        private Uri mIconUri;
277        private Bundle mExtras;
278        private Uri mMediaUri;
279
280        /**
281         * Creates an initially empty builder.
282         */
283        public Builder() {
284        }
285
286        /**
287         * Sets the media id.
288         *
289         * @param mediaId The unique id for the item or null.
290         * @return this
291         */
292        public Builder setMediaId(@Nullable String mediaId) {
293            mMediaId = mediaId;
294            return this;
295        }
296
297        /**
298         * Sets the title.
299         *
300         * @param title A title suitable for display to the user or null.
301         * @return this
302         */
303        public Builder setTitle(@Nullable CharSequence title) {
304            mTitle = title;
305            return this;
306        }
307
308        /**
309         * Sets the subtitle.
310         *
311         * @param subtitle A subtitle suitable for display to the user or null.
312         * @return this
313         */
314        public Builder setSubtitle(@Nullable CharSequence subtitle) {
315            mSubtitle = subtitle;
316            return this;
317        }
318
319        /**
320         * Sets the description.
321         *
322         * @param description A description suitable for display to the user or
323         *            null.
324         * @return this
325         */
326        public Builder setDescription(@Nullable CharSequence description) {
327            mDescription = description;
328            return this;
329        }
330
331        /**
332         * Sets the icon.
333         *
334         * @param icon A {@link Bitmap} icon suitable for display to the user or
335         *            null.
336         * @return this
337         */
338        public Builder setIconBitmap(@Nullable Bitmap icon) {
339            mIcon = icon;
340            return this;
341        }
342
343        /**
344         * Sets the icon uri.
345         *
346         * @param iconUri A {@link Uri} for an icon suitable for display to the
347         *            user or null.
348         * @return this
349         */
350        public Builder setIconUri(@Nullable Uri iconUri) {
351            mIconUri = iconUri;
352            return this;
353        }
354
355        /**
356         * Sets a bundle of extras.
357         *
358         * @param extras The extras to include with this description or null.
359         * @return this
360         */
361        public Builder setExtras(@Nullable Bundle extras) {
362            mExtras = extras;
363            return this;
364        }
365
366        /**
367         * Sets the media uri.
368         *
369         * @param mediaUri The content's {@link Uri} for the item or null.
370         * @return this
371         */
372        public Builder setMediaUri(@Nullable Uri mediaUri) {
373            mMediaUri = mediaUri;
374            return this;
375        }
376
377        public MediaDescription build() {
378            return new MediaDescription(mMediaId, mTitle, mSubtitle, mDescription, mIcon, mIconUri,
379                    mExtras, mMediaUri);
380        }
381    }
382}
383