1 /* 2 * Copyright (C) 2013 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.support.v7.media; 18 19 import android.app.PendingIntent; 20 import android.os.Bundle; 21 import android.os.SystemClock; 22 import android.support.v4.util.TimeUtils; 23 24 /** 25 * Describes the playback status of a media session. 26 * <p> 27 * This class is part of the remote playback protocol described by the 28 * {@link MediaControlIntent MediaControlIntent} class. 29 * </p><p> 30 * When a media session is created, it is initially in the 31 * {@link #SESSION_STATE_ACTIVE active} state. When the media session ends 32 * normally, it transitions to the {@link #SESSION_STATE_ENDED ended} state. 33 * If the media session is invalidated due to another session forcibly taking 34 * control of the route, then it transitions to the 35 * {@link #SESSION_STATE_INVALIDATED invalidated} state. 36 * Refer to the documentation of each state for an explanation of its meaning. 37 * </p><p> 38 * To monitor session status, the application should supply a {@link PendingIntent} to use as the 39 * {@link MediaControlIntent#EXTRA_SESSION_STATUS_UPDATE_RECEIVER session status update receiver} 40 * for a given {@link MediaControlIntent#ACTION_START_SESSION session start request}. 41 * </p><p> 42 * This object is immutable once created using a {@link Builder} instance. 43 * </p> 44 */ 45 public final class MediaSessionStatus { 46 private static final String KEY_TIMESTAMP = "timestamp"; 47 private static final String KEY_SESSION_STATE = "sessionState"; 48 private static final String KEY_QUEUE_PAUSED = "queuePaused"; 49 private static final String KEY_EXTRAS = "extras"; 50 51 private final Bundle mBundle; 52 53 /** 54 * Session state: Active. 55 * <p> 56 * Indicates that the media session is active and in control of the route. 57 * </p> 58 */ 59 public static final int SESSION_STATE_ACTIVE = 0; 60 61 /** 62 * Session state: Ended. 63 * <p> 64 * Indicates that the media session was ended normally using the 65 * {@link MediaControlIntent#ACTION_END_SESSION end session} action. 66 * </p><p> 67 * A terminated media session cannot be used anymore. To play more media, the 68 * application must start a new session. 69 * </p> 70 */ 71 public static final int SESSION_STATE_ENDED = 1; 72 73 /** 74 * Session state: Invalidated. 75 * <p> 76 * Indicates that the media session was invalidated involuntarily due to 77 * another session taking control of the route. 78 * </p><p> 79 * An invalidated media session cannot be used anymore. To play more media, the 80 * application must start a new session. 81 * </p> 82 */ 83 public static final int SESSION_STATE_INVALIDATED = 2; 84 MediaSessionStatus(Bundle bundle)85 private MediaSessionStatus(Bundle bundle) { 86 mBundle = bundle; 87 } 88 89 /** 90 * Gets the timestamp associated with the status information in 91 * milliseconds since boot in the {@link SystemClock#elapsedRealtime} time base. 92 * 93 * @return The status timestamp in the {@link SystemClock#elapsedRealtime()} time base. 94 */ getTimestamp()95 public long getTimestamp() { 96 return mBundle.getLong(KEY_TIMESTAMP); 97 } 98 99 /** 100 * Gets the session state. 101 * 102 * @return The session state. One of {@link #SESSION_STATE_ACTIVE}, 103 * {@link #SESSION_STATE_ENDED}, or {@link #SESSION_STATE_INVALIDATED}. 104 */ getSessionState()105 public int getSessionState() { 106 return mBundle.getInt(KEY_SESSION_STATE, SESSION_STATE_INVALIDATED); 107 } 108 109 /** 110 * Returns true if the session's queue is paused. 111 * 112 * @return True if the session's queue is paused. 113 */ isQueuePaused()114 public boolean isQueuePaused() { 115 return mBundle.getBoolean(KEY_QUEUE_PAUSED); 116 } 117 118 /** 119 * Gets a bundle of extras for this status object. 120 * The extras will be ignored by the media router but they may be used 121 * by applications. 122 */ getExtras()123 public Bundle getExtras() { 124 return mBundle.getBundle(KEY_EXTRAS); 125 } 126 127 @Override toString()128 public String toString() { 129 StringBuilder result = new StringBuilder(); 130 result.append("MediaSessionStatus{ "); 131 result.append("timestamp="); 132 TimeUtils.formatDuration(SystemClock.elapsedRealtime() - getTimestamp(), result); 133 result.append(" ms ago"); 134 result.append(", sessionState=").append(sessionStateToString(getSessionState())); 135 result.append(", queuePaused=").append(isQueuePaused()); 136 result.append(", extras=").append(getExtras()); 137 result.append(" }"); 138 return result.toString(); 139 } 140 sessionStateToString(int sessionState)141 private static String sessionStateToString(int sessionState) { 142 switch (sessionState) { 143 case SESSION_STATE_ACTIVE: 144 return "active"; 145 case SESSION_STATE_ENDED: 146 return "ended"; 147 case SESSION_STATE_INVALIDATED: 148 return "invalidated"; 149 } 150 return Integer.toString(sessionState); 151 } 152 153 /** 154 * Converts this object to a bundle for serialization. 155 * 156 * @return The contents of the object represented as a bundle. 157 */ asBundle()158 public Bundle asBundle() { 159 return mBundle; 160 } 161 162 /** 163 * Creates an instance from a bundle. 164 * 165 * @param bundle The bundle, or null if none. 166 * @return The new instance, or null if the bundle was null. 167 */ fromBundle(Bundle bundle)168 public static MediaSessionStatus fromBundle(Bundle bundle) { 169 return bundle != null ? new MediaSessionStatus(bundle) : null; 170 } 171 172 /** 173 * Builder for {@link MediaSessionStatus media session status objects}. 174 */ 175 public static final class Builder { 176 private final Bundle mBundle; 177 178 /** 179 * Creates a media session status builder using the current time as the 180 * reference timestamp. 181 * 182 * @param sessionState The session state. 183 */ Builder(int sessionState)184 public Builder(int sessionState) { 185 mBundle = new Bundle(); 186 setTimestamp(SystemClock.elapsedRealtime()); 187 setSessionState(sessionState); 188 } 189 190 /** 191 * Creates a media session status builder whose initial contents are 192 * copied from an existing status. 193 */ Builder(MediaSessionStatus status)194 public Builder(MediaSessionStatus status) { 195 if (status == null) { 196 throw new IllegalArgumentException("status must not be null"); 197 } 198 199 mBundle = new Bundle(status.mBundle); 200 } 201 202 /** 203 * Sets the timestamp associated with the status information in 204 * milliseconds since boot in the {@link SystemClock#elapsedRealtime} time base. 205 */ setTimestamp(long elapsedRealtimeTimestamp)206 public Builder setTimestamp(long elapsedRealtimeTimestamp) { 207 mBundle.putLong(KEY_TIMESTAMP, elapsedRealtimeTimestamp); 208 return this; 209 } 210 211 /** 212 * Sets the session state. 213 */ setSessionState(int sessionState)214 public Builder setSessionState(int sessionState) { 215 mBundle.putInt(KEY_SESSION_STATE, sessionState); 216 return this; 217 } 218 219 /** 220 * Sets whether the queue is paused. 221 */ setQueuePaused(boolean queuePaused)222 public Builder setQueuePaused(boolean queuePaused) { 223 mBundle.putBoolean(KEY_QUEUE_PAUSED, queuePaused); 224 return this; 225 } 226 227 /** 228 * Sets a bundle of extras for this status object. 229 * The extras will be ignored by the media router but they may be used 230 * by applications. 231 */ setExtras(Bundle extras)232 public Builder setExtras(Bundle extras) { 233 mBundle.putBundle(KEY_EXTRAS, extras); 234 return this; 235 } 236 237 /** 238 * Builds the {@link MediaSessionStatus media session status object}. 239 */ build()240 public MediaSessionStatus build() { 241 return new MediaSessionStatus(mBundle); 242 } 243 } 244 } 245