1 /* 2 * Copyright 2018 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 */ 16 17 package android.media; 18 19 import android.annotation.IntDef; 20 import android.annotation.NonNull; 21 import android.annotation.Nullable; 22 import android.media.update.ApiLoader; 23 import android.media.update.MediaItem2Provider; 24 import android.os.Bundle; 25 26 import java.lang.annotation.Retention; 27 import java.lang.annotation.RetentionPolicy; 28 29 /** 30 * @hide 31 * A class with information on a single media item with the metadata information. 32 * Media item are application dependent so we cannot guarantee that they contain the right values. 33 * <p> 34 * When it's sent to a controller or browser, it's anonymized and data descriptor wouldn't be sent. 35 * <p> 36 * This object isn't a thread safe. 37 */ 38 public class MediaItem2 { 39 /** @hide */ 40 @Retention(RetentionPolicy.SOURCE) 41 @IntDef(flag=true, value = { FLAG_BROWSABLE, FLAG_PLAYABLE }) 42 public @interface Flags { } 43 44 /** 45 * Flag: Indicates that the item has children of its own. 46 */ 47 public static final int FLAG_BROWSABLE = 1 << 0; 48 49 /** 50 * Flag: Indicates that the item is playable. 51 * <p> 52 * The id of this item may be passed to 53 * {@link MediaController2#playFromMediaId(String, Bundle)} 54 */ 55 public static final int FLAG_PLAYABLE = 1 << 1; 56 57 private final MediaItem2Provider mProvider; 58 59 /** 60 * Create a new media item 61 * @hide 62 */ 63 public MediaItem2(MediaItem2Provider provider) { 64 mProvider = provider; 65 } 66 67 /** 68 * @hide 69 */ 70 public MediaItem2Provider getProvider() { 71 return mProvider; 72 } 73 74 /** 75 * Return this object as a bundle to share between processes. 76 * 77 * @return a new bundle instance 78 */ 79 public Bundle toBundle() { 80 return mProvider.toBundle_impl(); 81 } 82 83 public static MediaItem2 fromBundle(Bundle bundle) { 84 return ApiLoader.getProvider().fromBundle_MediaItem2(bundle); 85 } 86 87 public String toString() { 88 return mProvider.toString_impl(); 89 } 90 91 /** 92 * Gets the flags of the item. 93 */ 94 public @Flags int getFlags() { 95 return mProvider.getFlags_impl(); 96 } 97 98 /** 99 * Returns whether this item is browsable. 100 * @see #FLAG_BROWSABLE 101 */ 102 public boolean isBrowsable() { 103 return mProvider.isBrowsable_impl(); 104 } 105 106 /** 107 * Returns whether this item is playable. 108 * @see #FLAG_PLAYABLE 109 */ 110 public boolean isPlayable() { 111 return mProvider.isPlayable_impl(); 112 } 113 114 /** 115 * Set a metadata. If the metadata is not null, its id should be matched with this instance's 116 * media id. 117 * 118 * @param metadata metadata to update 119 */ 120 public void setMetadata(@Nullable MediaMetadata2 metadata) { 121 mProvider.setMetadata_impl(metadata); 122 } 123 124 /** 125 * Returns the metadata of the media. 126 */ 127 public @Nullable MediaMetadata2 getMetadata() { 128 return mProvider.getMetadata_impl(); 129 } 130 131 /** 132 * Returns the media id for this item. 133 */ 134 public @NonNull String getMediaId() { 135 return mProvider.getMediaId_impl(); 136 } 137 138 /** 139 * Return the {@link DataSourceDesc} 140 * <p> 141 * Can be {@code null} if the MediaItem2 came from another process and anonymized 142 * 143 * @return data source descriptor 144 */ 145 public @Nullable DataSourceDesc getDataSourceDesc() { 146 return mProvider.getDataSourceDesc_impl(); 147 } 148 149 @Override 150 public boolean equals(Object obj) { 151 return mProvider.equals_impl(obj); 152 } 153 154 /** 155 * Build {@link MediaItem2} 156 */ 157 public static final class Builder { 158 private final MediaItem2Provider.BuilderProvider mProvider; 159 160 /** 161 * Constructor for {@link Builder} 162 * 163 * @param flags 164 */ 165 public Builder(@Flags int flags) { 166 mProvider = ApiLoader.getProvider().createMediaItem2Builder(this, flags); 167 } 168 169 /** 170 * Set the media id of this instance. {@code null} for unset. 171 * <p> 172 * Media id is used to identify a media contents between session and controller. 173 * <p> 174 * If the metadata is set with the {@link #setMetadata(MediaMetadata2)} and it has 175 * media id, id from {@link #setMediaId(String)} will be ignored and metadata's id will be 176 * used instead. If the id isn't set neither by {@link #setMediaId(String)} nor 177 * {@link #setMetadata(MediaMetadata2)}, id will be automatically generated. 178 * 179 * @param mediaId media id 180 * @return this instance for chaining 181 */ 182 public Builder setMediaId(@Nullable String mediaId) { 183 return mProvider.setMediaId_impl(mediaId); 184 } 185 186 /** 187 * Set the metadata of this instance. {@code null} for unset. 188 * <p> 189 * If the metadata is set with the {@link #setMetadata(MediaMetadata2)} and it has 190 * media id, id from {@link #setMediaId(String)} will be ignored and metadata's id will be 191 * used instead. If the id isn't set neither by {@link #setMediaId(String)} nor 192 * {@link #setMetadata(MediaMetadata2)}, id will be automatically generated. 193 * 194 * @param metadata metadata 195 * @return this instance for chaining 196 */ 197 public Builder setMetadata(@Nullable MediaMetadata2 metadata) { 198 return mProvider.setMetadata_impl(metadata); 199 } 200 201 /** 202 * Set the data source descriptor for this instance. {@code null} for unset. 203 * 204 * @param dataSourceDesc data source descriptor 205 * @return this instance for chaining 206 */ 207 public Builder setDataSourceDesc(@Nullable DataSourceDesc dataSourceDesc) { 208 return mProvider.setDataSourceDesc_impl(dataSourceDesc); 209 } 210 211 /** 212 * Build {@link MediaItem2}. 213 * 214 * @return a new {@link MediaItem2}. 215 */ 216 public MediaItem2 build() { 217 return mProvider.build_impl(); 218 } 219 } 220 } 221