PlaybackState.java revision 07c7077c54717dbbf2c401ea32d00fa6df6d77c6 
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.media.session;
17
18import android.os.Parcel;
19import android.os.Parcelable;
20
21/**
22 * Playback state for a {@link Session}. This includes a state like
23 * {@link PlaybackState#PLAYSTATE_PLAYING}, the current playback position,
24 * and the current control capabilities.
25 */
26public final class PlaybackState implements Parcelable {
27    /**
28     * Indicates this performer supports the stop command.
29     *
30     * @see #setActions
31     */
32    public static final long ACTION_STOP = 1 << 0;
33
34    /**
35     * Indicates this performer supports the pause command.
36     *
37     * @see #setActions
38     */
39    public static final long ACTION_PAUSE = 1 << 1;
40
41    /**
42     * Indicates this performer supports the play command.
43     *
44     * @see #setActions
45     */
46    public static final long ACTION_PLAY = 1 << 2;
47
48    /**
49     * Indicates this performer supports the rewind command.
50     *
51     * @see #setActions
52     */
53    public static final long ACTION_REWIND = 1 << 3;
54
55    /**
56     * Indicates this performer supports the previous command.
57     *
58     * @see #setActions
59     */
60    public static final long ACTION_PREVIOUS_ITEM = 1 << 4;
61
62    /**
63     * Indicates this performer supports the next command.
64     *
65     * @see #setActions
66     */
67    public static final long ACTION_NEXT_ITEM = 1 << 5;
68
69    /**
70     * Indicates this performer supports the fast forward command.
71     *
72     * @see #setActions
73     */
74    public static final long ACTION_FASTFORWARD = 1 << 6;
75
76    /**
77     * Indicates this performer supports the set rating command.
78     *
79     * @see #setActions
80     */
81    public static final long ACTION_RATING = 1 << 7;
82
83    /**
84     * Indicates this performer supports the seek to command.
85     *
86     * @see #setActions
87     */
88    public static final long ACTION_SEEK_TO = 1 << 8;
89
90    /**
91     * This is the default playback state and indicates that no media has been
92     * added yet, or the performer has been reset and has no content to play.
93     *
94     * @see #setState
95     */
96    public final static int PLAYSTATE_NONE = 0;
97
98    /**
99     * State indicating this item is currently stopped.
100     *
101     * @see #setState
102     */
103    public final static int PLAYSTATE_STOPPED = 1;
104
105    /**
106     * State indicating this item is currently paused.
107     *
108     * @see #setState
109     */
110    public final static int PLAYSTATE_PAUSED = 2;
111
112    /**
113     * State indicating this item is currently playing.
114     *
115     * @see #setState
116     */
117    public final static int PLAYSTATE_PLAYING = 3;
118
119    /**
120     * State indicating this item is currently fast forwarding.
121     *
122     * @see #setState
123     */
124    public final static int PLAYSTATE_FAST_FORWARDING = 4;
125
126    /**
127     * State indicating this item is currently rewinding.
128     *
129     * @see #setState
130     */
131    public final static int PLAYSTATE_REWINDING = 5;
132
133    /**
134     * State indicating this item is currently buffering and will begin playing
135     * when enough data has buffered.
136     *
137     * @see #setState
138     */
139    public final static int PLAYSTATE_BUFFERING = 6;
140
141    /**
142     * State indicating this item is currently in an error state. The error
143     * message should also be set when entering this state.
144     *
145     * @see #setState
146     */
147    public final static int PLAYSTATE_ERROR = 7;
148
149    /**
150     * State indicating the class doing playback is currently connecting to a
151     * route. Depending on the implementation you may return to the previous
152     * state when the connection finishes or enter {@link #PLAYSTATE_NONE}. If
153     * the connection failed {@link #PLAYSTATE_ERROR} should be used.
154     */
155    public final static int PLAYSTATE_CONNECTING = 8;
156
157    private int mState;
158    private long mPosition;
159    private long mBufferPosition;
160    private float mSpeed;
161    private long mCapabilities;
162    private String mErrorMessage;
163
164    /**
165     * Create an empty PlaybackState. At minimum a state and actions should be
166     * set before publishing a PlaybackState.
167     */
168    public PlaybackState() {
169    }
170
171    /**
172     * Create a new PlaybackState from an existing PlaybackState. All fields
173     * will be copied to the new state.
174     *
175     * @param from The PlaybackState to duplicate
176     */
177    public PlaybackState(PlaybackState from) {
178        this.setState(from.getState());
179        this.setPosition(from.getPosition());
180        this.setBufferPosition(from.getBufferPosition());
181        this.setSpeed(from.getSpeed());
182        this.setActions(from.getActions());
183        this.setErrorMessage(from.getErrorMessage());
184    }
185
186    private PlaybackState(Parcel in) {
187        this.setState(in.readInt());
188        this.setPosition(in.readLong());
189        this.setBufferPosition(in.readLong());
190        this.setSpeed(in.readFloat());
191        this.setActions(in.readLong());
192        this.setErrorMessage(in.readString());
193    }
194
195    @Override
196    public int describeContents() {
197        return 0;
198    }
199
200    @Override
201    public void writeToParcel(Parcel dest, int flags) {
202        dest.writeInt(getState());
203        dest.writeLong(getPosition());
204        dest.writeLong(getBufferPosition());
205        dest.writeFloat(getSpeed());
206        dest.writeLong(getActions());
207        dest.writeString(getErrorMessage());
208    }
209
210    /**
211     * Get the current state of playback. One of the following:
212     * <ul>
213     * <li> {@link PlaybackState#PLAYSTATE_NONE}</li>
214     * <li> {@link PlaybackState#PLAYSTATE_STOPPED}</li>
215     * <li> {@link PlaybackState#PLAYSTATE_PLAYING}</li>
216     * <li> {@link PlaybackState#PLAYSTATE_PAUSED}</li>
217     * <li> {@link PlaybackState#PLAYSTATE_FAST_FORWARDING}</li>
218     * <li> {@link PlaybackState#PLAYSTATE_REWINDING}</li>
219     * <li> {@link PlaybackState#PLAYSTATE_BUFFERING}</li>
220     * <li> {@link PlaybackState#PLAYSTATE_ERROR}</li>
221     */
222    public int getState() {
223        return mState;
224    }
225
226    /**
227     * Set the current state of playback. One of the following:
228     * <ul>
229     * <li> {@link PlaybackState#PLAYSTATE_NONE}</li>
230     * <li> {@link PlaybackState#PLAYSTATE_STOPPED}</li>
231     * <li> {@link PlaybackState#PLAYSTATE_PLAYING}</li>
232     * <li> {@link PlaybackState#PLAYSTATE_PAUSED}</li>
233     * <li> {@link PlaybackState#PLAYSTATE_FAST_FORWARDING}</li>
234     * <li> {@link PlaybackState#PLAYSTATE_REWINDING}</li>
235     * <li> {@link PlaybackState#PLAYSTATE_BUFFERING}</li>
236     * <li> {@link PlaybackState#PLAYSTATE_ERROR}</li>
237     */
238    public void setState(int mState) {
239        this.mState = mState;
240    }
241
242    /**
243     * Get the current playback position in ms.
244     */
245    public long getPosition() {
246        return mPosition;
247    }
248
249    /**
250     * Set the current playback position in ms.
251     */
252    public void setPosition(long position) {
253        mPosition = position;
254    }
255
256    /**
257     * Get the current buffer position in ms. This is the farthest playback
258     * point that can be reached from the current position using only buffered
259     * content.
260     */
261    public long getBufferPosition() {
262        return mBufferPosition;
263    }
264
265    /**
266     * Set the current buffer position in ms. This is the farthest playback
267     * point that can be reached from the current position using only buffered
268     * content.
269     */
270    public void setBufferPosition(long bufferPosition) {
271        mBufferPosition = bufferPosition;
272    }
273
274    /**
275     * Get the current playback speed as a multiple of normal playback. This
276     * should be negative when rewinding. A value of 1 means normal playback and
277     * 0 means paused.
278     */
279    public float getSpeed() {
280        return mSpeed;
281    }
282
283    /**
284     * Set the current playback speed as a multiple of normal playback. This
285     * should be negative when rewinding. A value of 1 means normal playback and
286     * 0 means paused.
287     */
288    public void setSpeed(float speed) {
289        mSpeed = speed;
290    }
291
292    /**
293     * Get the current actions available on this session. This should use a
294     * bitmask of the available actions.
295     * <ul>
296     * <li> {@link PlaybackState#ACTION_PREVIOUS_ITEM}</li>
297     * <li> {@link PlaybackState#ACTION_REWIND}</li>
298     * <li> {@link PlaybackState#ACTION_PLAY}</li>
299     * <li> {@link PlaybackState#ACTION_PAUSE}</li>
300     * <li> {@link PlaybackState#ACTION_STOP}</li>
301     * <li> {@link PlaybackState#ACTION_FASTFORWARD}</li>
302     * <li> {@link PlaybackState#ACTION_NEXT_ITEM}</li>
303     * <li> {@link PlaybackState#ACTION_SEEK_TO}</li>
304     * <li> {@link PlaybackState#ACTION_RATING}</li>
305     * </ul>
306     */
307    public long getActions() {
308        return mCapabilities;
309    }
310
311    /**
312     * Set the current capabilities available on this session. This should use a
313     * bitmask of the available capabilities.
314     * <ul>
315     * <li> {@link PlaybackState#ACTION_PREVIOUS_ITEM}</li>
316     * <li> {@link PlaybackState#ACTION_REWIND}</li>
317     * <li> {@link PlaybackState#ACTION_PLAY}</li>
318     * <li> {@link PlaybackState#ACTION_PAUSE}</li>
319     * <li> {@link PlaybackState#ACTION_STOP}</li>
320     * <li> {@link PlaybackState#ACTION_FASTFORWARD}</li>
321     * <li> {@link PlaybackState#ACTION_NEXT_ITEM}</li>
322     * <li> {@link PlaybackState#ACTION_SEEK_TO}</li>
323     * <li> {@link PlaybackState#ACTION_RATING}</li>
324     * </ul>
325     */
326    public void setActions(long capabilities) {
327        mCapabilities = capabilities;
328    }
329
330    /**
331     * Get a user readable error message. This should be set when the state is
332     * {@link PlaybackState#PLAYSTATE_ERROR}.
333     */
334    public String getErrorMessage() {
335        return mErrorMessage;
336    }
337
338    /**
339     * Set a user readable error message. This should be set when the state is
340     * {@link PlaybackState#PLAYSTATE_ERROR}.
341     */
342    public void setErrorMessage(String errorMessage) {
343        mErrorMessage = errorMessage;
344    }
345
346    public static final Parcelable.Creator<PlaybackState> CREATOR
347            = new Parcelable.Creator<PlaybackState>() {
348        @Override
349        public PlaybackState createFromParcel(Parcel in) {
350            return new PlaybackState(in);
351        }
352
353        @Override
354        public PlaybackState[] newArray(int size) {
355            return new PlaybackState[size];
356        }
357    };
358}
359