MediaDescriptionCompat.java revision 81f61057e1542008c03d6a85e8ef475d9177149f 
1/*
2 * Copyright (C) 2014 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16package android.support.v4.media;
17
18import android.graphics.Bitmap;
19import android.net.Uri;
20import android.os.Build;
21import android.os.Bundle;
22import android.os.Parcel;
23import android.os.Parcelable;
24import android.support.annotation.Nullable;
25import android.text.TextUtils;
26
27/**
28 * A simple set of metadata for a media item suitable for display. This can be
29 * created using the Builder or retrieved from existing metadata using
30 * {@link MediaMetadataCompat#getDescription()}.
31 */
32public final class MediaDescriptionCompat implements Parcelable {
33    /**
34     * A unique persistent id for the content or null.
35     */
36    private final String mMediaId;
37    /**
38     * A primary title suitable for display or null.
39     */
40    private final CharSequence mTitle;
41    /**
42     * A subtitle suitable for display or null.
43     */
44    private final CharSequence mSubtitle;
45    /**
46     * A description suitable for display or null.
47     */
48    private final CharSequence mDescription;
49    /**
50     * A bitmap icon suitable for display or null.
51     */
52    private final Bitmap mIcon;
53    /**
54     * A Uri for an icon suitable for display or null.
55     */
56    private final Uri mIconUri;
57    /**
58     * Extras for opaque use by apps/system.
59     */
60    private final Bundle mExtras;
61    /**
62     * A Uri to identify this content.
63     */
64    private final Uri mMediaUri;
65
66    /**
67     * A cached copy of the equivalent framework object.
68     */
69    private Object mDescriptionObj;
70
71    private MediaDescriptionCompat(String mediaId, CharSequence title, CharSequence subtitle,
72            CharSequence description, Bitmap icon, Uri iconUri, Bundle extras, Uri mediaUri) {
73        mMediaId = mediaId;
74        mTitle = title;
75        mSubtitle = subtitle;
76        mDescription = description;
77        mIcon = icon;
78        mIconUri = iconUri;
79        mExtras = extras;
80        mMediaUri = mediaUri;
81    }
82
83    private MediaDescriptionCompat(Parcel in) {
84        mMediaId = in.readString();
85        mTitle = TextUtils.CHAR_SEQUENCE_CREATOR.createFromParcel(in);
86        mSubtitle = TextUtils.CHAR_SEQUENCE_CREATOR.createFromParcel(in);
87        mDescription = TextUtils.CHAR_SEQUENCE_CREATOR.createFromParcel(in);
88        mIcon = in.readParcelable(null);
89        mIconUri = in.readParcelable(null);
90        mExtras = in.readBundle();
91        mMediaUri = in.readParcelable(null);
92    }
93
94    /**
95     * Returns the media id or null. See
96     * {@link MediaMetadataCompat#METADATA_KEY_MEDIA_ID}.
97     */
98    @Nullable
99    public String getMediaId() {
100        return mMediaId;
101    }
102
103    /**
104     * Returns a title suitable for display or null.
105     *
106     * @return A title or null.
107     */
108    @Nullable
109    public CharSequence getTitle() {
110        return mTitle;
111    }
112
113    /**
114     * Returns a subtitle suitable for display or null.
115     *
116     * @return A subtitle or null.
117     */
118    @Nullable
119    public CharSequence getSubtitle() {
120        return mSubtitle;
121    }
122
123    /**
124     * Returns a description suitable for display or null.
125     *
126     * @return A description or null.
127     */
128    @Nullable
129    public CharSequence getDescription() {
130        return mDescription;
131    }
132
133    /**
134     * Returns a bitmap icon suitable for display or null.
135     *
136     * @return An icon or null.
137     */
138    @Nullable
139    public Bitmap getIconBitmap() {
140        return mIcon;
141    }
142
143    /**
144     * Returns a Uri for an icon suitable for display or null.
145     *
146     * @return An icon uri or null.
147     */
148    @Nullable
149    public Uri getIconUri() {
150        return mIconUri;
151    }
152
153    /**
154     * Returns any extras that were added to the description.
155     *
156     * @return A bundle of extras or null.
157     */
158    @Nullable
159    public Bundle getExtras() {
160        return mExtras;
161    }
162
163    /**
164     * Returns a Uri representing this content or null.
165     *
166     * @return A media Uri or null.
167     */
168    @Nullable
169    public Uri getMediaUri() {
170        return mMediaUri;
171    }
172
173    @Override
174    public int describeContents() {
175        return 0;
176    }
177
178    @Override
179    public void writeToParcel(Parcel dest, int flags) {
180        if (Build.VERSION.SDK_INT < 21) {
181            dest.writeString(mMediaId);
182            TextUtils.writeToParcel(mTitle, dest, flags);
183            TextUtils.writeToParcel(mSubtitle, dest, flags);
184            TextUtils.writeToParcel(mDescription, dest, flags);
185            dest.writeParcelable(mIcon, flags);
186            dest.writeParcelable(mIconUri, flags);
187            dest.writeBundle(mExtras);
188            dest.writeParcelable(mMediaUri, flags);
189        } else {
190            MediaDescriptionCompatApi21.writeToParcel(getMediaDescription(), dest, flags);
191        }
192    }
193
194    @Override
195    public String toString() {
196        return mTitle + ", " + mSubtitle + ", " + mDescription;
197    }
198
199    /**
200     * Gets the underlying framework {@link android.media.MediaDescription}
201     * object.
202     * <p>
203     * This method is only supported on
204     * {@link android.os.Build.VERSION_CODES#LOLLIPOP} and later.
205     * </p>
206     *
207     * @return An equivalent {@link android.media.MediaDescription} object, or
208     *         null if none.
209     */
210    public Object getMediaDescription() {
211        if (mDescriptionObj != null || Build.VERSION.SDK_INT < 21) {
212            return mDescriptionObj;
213        }
214        Object bob = MediaDescriptionCompatApi21.Builder.newInstance();
215        MediaDescriptionCompatApi21.Builder.setMediaId(bob, mMediaId);
216        MediaDescriptionCompatApi21.Builder.setTitle(bob, mTitle);
217        MediaDescriptionCompatApi21.Builder.setSubtitle(bob, mSubtitle);
218        MediaDescriptionCompatApi21.Builder.setDescription(bob, mDescription);
219        MediaDescriptionCompatApi21.Builder.setIconBitmap(bob, mIcon);
220        MediaDescriptionCompatApi21.Builder.setIconUri(bob, mIconUri);
221        MediaDescriptionCompatApi21.Builder.setExtras(bob, mExtras);
222        if (Build.VERSION.SDK_INT >= 23) {
223            MediaDescriptionCompatApi23.Builder.setMediaUri(bob, mMediaUri);
224        }
225        mDescriptionObj = MediaDescriptionCompatApi21.Builder.build(bob);
226
227        return mDescriptionObj;
228    }
229
230    /**
231     * Creates an instance from a framework
232     * {@link android.media.MediaDescription} object.
233     * <p>
234     * This method is only supported on API 21+.
235     * </p>
236     *
237     * @param descriptionObj A {@link android.media.MediaDescription} object, or
238     *            null if none.
239     * @return An equivalent {@link MediaMetadataCompat} object, or null if
240     *         none.
241     */
242    public static MediaDescriptionCompat fromMediaDescription(Object descriptionObj) {
243        if (descriptionObj == null || Build.VERSION.SDK_INT < 21) {
244            return null;
245        }
246
247        Builder bob = new Builder();
248        bob.setMediaId(MediaDescriptionCompatApi21.getMediaId(descriptionObj));
249        bob.setTitle(MediaDescriptionCompatApi21.getTitle(descriptionObj));
250        bob.setSubtitle(MediaDescriptionCompatApi21.getSubtitle(descriptionObj));
251        bob.setDescription(MediaDescriptionCompatApi21.getDescription(descriptionObj));
252        bob.setIconBitmap(MediaDescriptionCompatApi21.getIconBitmap(descriptionObj));
253        bob.setIconUri(MediaDescriptionCompatApi21.getIconUri(descriptionObj));
254        bob.setExtras(MediaDescriptionCompatApi21.getExtras(descriptionObj));
255        if (Build.VERSION.SDK_INT >= 23) {
256            bob.setMediaUri(MediaDescriptionCompatApi23.getMediaUri(descriptionObj));
257        }
258        MediaDescriptionCompat descriptionCompat = bob.build();
259        descriptionCompat.mDescriptionObj = descriptionObj;
260
261        return descriptionCompat;
262    }
263
264    public static final Parcelable.Creator<MediaDescriptionCompat> CREATOR =
265            new Parcelable.Creator<MediaDescriptionCompat>() {
266            @Override
267                public MediaDescriptionCompat createFromParcel(Parcel in) {
268                    if (Build.VERSION.SDK_INT < 21) {
269                        return new MediaDescriptionCompat(in);
270                    } else {
271                        return fromMediaDescription(MediaDescriptionCompatApi21.fromParcel(in));
272                    }
273                }
274
275            @Override
276                public MediaDescriptionCompat[] newArray(int size) {
277                    return new MediaDescriptionCompat[size];
278                }
279            };
280
281    /**
282     * Builder for {@link MediaDescriptionCompat} objects.
283     */
284    public static final class Builder {
285        private String mMediaId;
286        private CharSequence mTitle;
287        private CharSequence mSubtitle;
288        private CharSequence mDescription;
289        private Bitmap mIcon;
290        private Uri mIconUri;
291        private Bundle mExtras;
292        private Uri mMediaUri;
293
294        /**
295         * Creates an initially empty builder.
296         */
297        public Builder() {
298        }
299
300        /**
301         * Sets the media id.
302         *
303         * @param mediaId The unique id for the item or null.
304         * @return this
305         */
306        public Builder setMediaId(@Nullable String mediaId) {
307            mMediaId = mediaId;
308            return this;
309        }
310
311        /**
312         * Sets the title.
313         *
314         * @param title A title suitable for display to the user or null.
315         * @return this
316         */
317        public Builder setTitle(@Nullable CharSequence title) {
318            mTitle = title;
319            return this;
320        }
321
322        /**
323         * Sets the subtitle.
324         *
325         * @param subtitle A subtitle suitable for display to the user or null.
326         * @return this
327         */
328        public Builder setSubtitle(@Nullable CharSequence subtitle) {
329            mSubtitle = subtitle;
330            return this;
331        }
332
333        /**
334         * Sets the description.
335         *
336         * @param description A description suitable for display to the user or
337         *            null.
338         * @return this
339         */
340        public Builder setDescription(@Nullable CharSequence description) {
341            mDescription = description;
342            return this;
343        }
344
345        /**
346         * Sets the icon.
347         *
348         * @param icon A {@link Bitmap} icon suitable for display to the user or
349         *            null.
350         * @return this
351         */
352        public Builder setIconBitmap(@Nullable Bitmap icon) {
353            mIcon = icon;
354            return this;
355        }
356
357        /**
358         * Sets the icon uri.
359         *
360         * @param iconUri A {@link Uri} for an icon suitable for display to the
361         *            user or null.
362         * @return this
363         */
364        public Builder setIconUri(@Nullable Uri iconUri) {
365            mIconUri = iconUri;
366            return this;
367        }
368
369        /**
370         * Sets a bundle of extras.
371         *
372         * @param extras The extras to include with this description or null.
373         * @return this
374         */
375        public Builder setExtras(@Nullable Bundle extras) {
376            mExtras = extras;
377            return this;
378        }
379
380        /**
381         * Sets the media uri.
382         *
383         * @param mediaUri The content's {@link Uri} for the item or null.
384         * @return this
385         */
386        public Builder setMediaUri(@Nullable Uri mediaUri) {
387            mMediaUri = mediaUri;
388            return this;
389        }
390
391        /**
392         * Creates a {@link MediaDescriptionCompat} instance with the specified
393         * fields.
394         *
395         * @return A MediaDescriptionCompat instance.
396         */
397        public MediaDescriptionCompat build() {
398            return new MediaDescriptionCompat(mMediaId, mTitle, mSubtitle, mDescription, mIcon,
399                    mIconUri, mExtras, mMediaUri);
400        }
401    }
402}
403