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.text.TextUtils; 25 26/** 27 * A simple set of metadata for a media item suitable for display. This can be 28 * created using the Builder or retrieved from existing metadata using 29 * {@link MediaMetadataCompat#getDescription()}. 30 */ 31public final class MediaDescriptionCompat implements Parcelable { 32 /** 33 * A unique persistent id for the content or null. 34 */ 35 private final String mMediaId; 36 /** 37 * A primary title suitable for display or null. 38 */ 39 private final CharSequence mTitle; 40 /** 41 * A subtitle suitable for display or null. 42 */ 43 private final CharSequence mSubtitle; 44 /** 45 * A description suitable for display or null. 46 */ 47 private final CharSequence mDescription; 48 /** 49 * A bitmap icon suitable for display or null. 50 */ 51 private final Bitmap mIcon; 52 /** 53 * A Uri for an icon suitable for display or null. 54 */ 55 private final Uri mIconUri; 56 /** 57 * Extras for opaque use by apps/system. 58 */ 59 private final Bundle mExtras; 60 61 /** 62 * A cached copy of the equivalent framework object. 63 */ 64 private Object mDescriptionObj; 65 66 private MediaDescriptionCompat(String mediaId, CharSequence title, CharSequence subtitle, 67 CharSequence description, Bitmap icon, Uri iconUri, Bundle extras) { 68 mMediaId = mediaId; 69 mTitle = title; 70 mSubtitle = subtitle; 71 mDescription = description; 72 mIcon = icon; 73 mIconUri = iconUri; 74 mExtras = extras; 75 } 76 77 private MediaDescriptionCompat(Parcel in) { 78 mMediaId = in.readString(); 79 mTitle = TextUtils.CHAR_SEQUENCE_CREATOR.createFromParcel(in); 80 mSubtitle = TextUtils.CHAR_SEQUENCE_CREATOR.createFromParcel(in); 81 mDescription = TextUtils.CHAR_SEQUENCE_CREATOR.createFromParcel(in); 82 mIcon = in.readParcelable(null); 83 mIconUri = in.readParcelable(null); 84 mExtras = in.readBundle(); 85 } 86 87 /** 88 * Returns the media id or null. See 89 * {@link MediaMetadataCompat#METADATA_KEY_MEDIA_ID}. 90 */ 91 public String getMediaId() { 92 return mMediaId; 93 } 94 95 /** 96 * Returns a title suitable for display or null. 97 * 98 * @return A title or null. 99 */ 100 public CharSequence getTitle() { 101 return mTitle; 102 } 103 104 /** 105 * Returns a subtitle suitable for display or null. 106 * 107 * @return A subtitle or null. 108 */ 109 public CharSequence getSubtitle() { 110 return mSubtitle; 111 } 112 113 /** 114 * Returns a description suitable for display or null. 115 * 116 * @return A description or null. 117 */ 118 public CharSequence getDescription() { 119 return mDescription; 120 } 121 122 /** 123 * Returns a bitmap icon suitable for display or null. 124 * 125 * @return An icon or null. 126 */ 127 public Bitmap getIconBitmap() { 128 return mIcon; 129 } 130 131 /** 132 * Returns a Uri for an icon suitable for display or null. 133 * 134 * @return An icon uri or null. 135 */ 136 public Uri getIconUri() { 137 return mIconUri; 138 } 139 140 /** 141 * Returns any extras that were added to the description. 142 * 143 * @return A bundle of extras or null. 144 */ 145 public Bundle getExtras() { 146 return mExtras; 147 } 148 149 @Override 150 public int describeContents() { 151 return 0; 152 } 153 154 @Override 155 public void writeToParcel(Parcel dest, int flags) { 156 if (Build.VERSION.SDK_INT < 21) { 157 dest.writeString(mMediaId); 158 TextUtils.writeToParcel(mTitle, dest, flags); 159 TextUtils.writeToParcel(mSubtitle, dest, flags); 160 TextUtils.writeToParcel(mDescription, dest, flags); 161 dest.writeParcelable(mIcon, flags); 162 dest.writeParcelable(mIconUri, flags); 163 dest.writeBundle(mExtras); 164 } else { 165 MediaDescriptionCompatApi21.writeToParcel(getMediaDescription(), dest, flags); 166 } 167 } 168 169 @Override 170 public String toString() { 171 return mTitle + ", " + mSubtitle + ", " + mDescription; 172 } 173 174 /** 175 * Gets the underlying framework {@link android.media.MediaDescription} 176 * object. 177 * <p> 178 * This method is only supported on 179 * {@link android.os.Build.VERSION_CODES#LOLLIPOP} and later. 180 * </p> 181 * 182 * @return An equivalent {@link android.media.MediaDescription} object, or 183 * null if none. 184 */ 185 public Object getMediaDescription() { 186 if (mDescriptionObj != null || Build.VERSION.SDK_INT < 21) { 187 return mDescriptionObj; 188 } 189 Object bob = MediaDescriptionCompatApi21.Builder.newInstance(); 190 MediaDescriptionCompatApi21.Builder.setMediaId(bob, mMediaId); 191 MediaDescriptionCompatApi21.Builder.setTitle(bob, mTitle); 192 MediaDescriptionCompatApi21.Builder.setSubtitle(bob, mSubtitle); 193 MediaDescriptionCompatApi21.Builder.setDescription(bob, mDescription); 194 MediaDescriptionCompatApi21.Builder.setIconBitmap(bob, mIcon); 195 MediaDescriptionCompatApi21.Builder.setIconUri(bob, mIconUri); 196 MediaDescriptionCompatApi21.Builder.setExtras(bob, mExtras); 197 mDescriptionObj = MediaDescriptionCompatApi21.Builder.build(bob); 198 199 return mDescriptionObj; 200 } 201 202 /** 203 * Creates an instance from a framework 204 * {@link android.media.MediaDescription} object. 205 * <p> 206 * This method is only supported on API 21+. 207 * </p> 208 * 209 * @param descriptionObj A {@link android.media.MediaDescription} object, or 210 * null if none. 211 * @return An equivalent {@link MediaMetadataCompat} object, or null if 212 * none. 213 */ 214 public static MediaDescriptionCompat fromMediaDescription(Object descriptionObj) { 215 if (descriptionObj == null || Build.VERSION.SDK_INT < 21) { 216 return null; 217 } 218 219 Builder bob = new Builder(); 220 bob.setMediaId(MediaDescriptionCompatApi21.getMediaId(descriptionObj)); 221 bob.setTitle(MediaDescriptionCompatApi21.getTitle(descriptionObj)); 222 bob.setSubtitle(MediaDescriptionCompatApi21.getSubtitle(descriptionObj)); 223 bob.setDescription(MediaDescriptionCompatApi21.getDescription(descriptionObj)); 224 bob.setIconBitmap(MediaDescriptionCompatApi21.getIconBitmap(descriptionObj)); 225 bob.setIconUri(MediaDescriptionCompatApi21.getIconUri(descriptionObj)); 226 bob.setExtras(MediaDescriptionCompatApi21.getExtras(descriptionObj)); 227 MediaDescriptionCompat descriptionCompat = bob.build(); 228 descriptionCompat.mDescriptionObj = descriptionObj; 229 230 return descriptionCompat; 231 } 232 233 public static final Parcelable.Creator<MediaDescriptionCompat> CREATOR = 234 new Parcelable.Creator<MediaDescriptionCompat>() { 235 @Override 236 public MediaDescriptionCompat createFromParcel(Parcel in) { 237 if (Build.VERSION.SDK_INT < 21) { 238 return new MediaDescriptionCompat(in); 239 } else { 240 return fromMediaDescription(MediaDescriptionCompatApi21.fromParcel(in)); 241 } 242 } 243 244 @Override 245 public MediaDescriptionCompat[] newArray(int size) { 246 return new MediaDescriptionCompat[size]; 247 } 248 }; 249 250 /** 251 * Builder for {@link MediaDescriptionCompat} objects. 252 */ 253 public static final class Builder { 254 private String mMediaId; 255 private CharSequence mTitle; 256 private CharSequence mSubtitle; 257 private CharSequence mDescription; 258 private Bitmap mIcon; 259 private Uri mIconUri; 260 private Bundle mExtras; 261 262 /** 263 * Creates an initially empty builder. 264 */ 265 public Builder() { 266 } 267 268 /** 269 * Sets the media id. 270 * 271 * @param mediaId The unique id for the item or null. 272 * @return this 273 */ 274 public Builder setMediaId(String mediaId) { 275 mMediaId = mediaId; 276 return this; 277 } 278 279 /** 280 * Sets the title. 281 * 282 * @param title A title suitable for display to the user or null. 283 * @return this 284 */ 285 public Builder setTitle(CharSequence title) { 286 mTitle = title; 287 return this; 288 } 289 290 /** 291 * Sets the subtitle. 292 * 293 * @param subtitle A subtitle suitable for display to the user or null. 294 * @return this 295 */ 296 public Builder setSubtitle(CharSequence subtitle) { 297 mSubtitle = subtitle; 298 return this; 299 } 300 301 /** 302 * Sets the description. 303 * 304 * @param description A description suitable for display to the user or 305 * null. 306 * @return this 307 */ 308 public Builder setDescription(CharSequence description) { 309 mDescription = description; 310 return this; 311 } 312 313 /** 314 * Sets the icon. 315 * 316 * @param icon A {@link Bitmap} icon suitable for display to the user or 317 * null. 318 * @return this 319 */ 320 public Builder setIconBitmap(Bitmap icon) { 321 mIcon = icon; 322 return this; 323 } 324 325 /** 326 * Sets the icon uri. 327 * 328 * @param iconUri A {@link Uri} for an icon suitable for display to the 329 * user or null. 330 * @return this 331 */ 332 public Builder setIconUri(Uri iconUri) { 333 mIconUri = iconUri; 334 return this; 335 } 336 337 /** 338 * Sets a bundle of extras. 339 * 340 * @param extras The extras to include with this description or null. 341 * @return this 342 */ 343 public Builder setExtras(Bundle extras) { 344 mExtras = extras; 345 return this; 346 } 347 348 /** 349 * Creates a {@link MediaDescriptionCompat} instance with the specified 350 * fields. 351 * 352 * @return A MediaDescriptionCompat instance. 353 */ 354 public MediaDescriptionCompat build() { 355 return new MediaDescriptionCompat(mMediaId, mTitle, mSubtitle, mDescription, mIcon, 356 mIconUri, mExtras); 357 } 358 } 359} 360