VolumeProviderCompat.java revision e0c3fd8d5c24c7e8bcc54234f30c01e78137b67e 
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 */
16
17package android.support.v4.media;
18
19import android.os.Build;
20import android.support.v4.media.session.MediaSessionCompat;
21
22/**
23 * Handles requests to adjust or set the volume on a session. This is also used
24 * to push volume updates back to the session after a request has been handled.
25 * You can set a volume provider on a session by calling
26 * {@link MediaSessionCompat#setPlaybackToRemote}.
27 */
28public abstract class VolumeProviderCompat {
29    /**
30     * The volume is fixed and can not be modified. Requests to change volume
31     * should be ignored.
32     */
33    public static final int VOLUME_CONTROL_FIXED = 0;
34
35    /**
36     * The volume control uses relative adjustment via
37     * {@link #onAdjustVolume(int)}. Attempts to set the volume to a specific
38     * value should be ignored.
39     */
40    public static final int VOLUME_CONTROL_RELATIVE = 1;
41
42    /**
43     * The volume control uses an absolute value. It may be adjusted using
44     * {@link #onAdjustVolume(int)} or set directly using
45     * {@link #onSetVolumeTo(int)}.
46     */
47    public static final int VOLUME_CONTROL_ABSOLUTE = 2;
48
49    private final int mControlType;
50    private final int mMaxVolume;
51    private int mCurrentVolume;
52    private Callback mCallback;
53
54    private Object mVolumeProviderObj;
55
56    /**
57     * Create a new volume provider for handling volume events. You must specify
58     * the type of volume control and the maximum volume that can be used.
59     *
60     * @param volumeControl The method for controlling volume that is used by
61     *            this provider.
62     * @param maxVolume The maximum allowed volume.
63     * @param currentVolume The current volume.
64     */
65    public VolumeProviderCompat(int volumeControl, int maxVolume, int currentVolume) {
66        mControlType = volumeControl;
67        mMaxVolume = maxVolume;
68        mCurrentVolume = currentVolume;
69    }
70
71    /**
72     * Get the current volume of the provider.
73     *
74     * @return The current volume.
75     */
76    public final int getCurrentVolume() {
77        return mCurrentVolume;
78    }
79
80    /**
81     * Get the volume control type that this volume provider uses.
82     *
83     * @return The volume control type for this volume provider
84     */
85    public final int getVolumeControl() {
86        return mControlType;
87    }
88
89    /**
90     * Get the maximum volume this provider allows.
91     *
92     * @return The max allowed volume.
93     */
94    public final int getMaxVolume() {
95        return mMaxVolume;
96    }
97
98    /**
99     * Set the current volume and notify the system that the volume has been
100     * changed.
101     *
102     * @param currentVolume The current volume of the output.
103     */
104    public final void setCurrentVolume(int currentVolume) {
105        if (mCallback != null) {
106            mCallback.onVolumeChanged(this);
107        }
108    }
109
110    /**
111     * Override to handle requests to set the volume of the current output.
112     *
113     * @param volume The volume to set the output to.
114     */
115    public void onSetVolumeTo(int volume) {
116    }
117
118    /**
119     * Override to handle requests to adjust the volume of the current output.
120     *
121     * @param direction The direction to adjust the volume in.
122     */
123    public void onAdjustVolume(int direction) {
124    }
125
126    /**
127     * Sets a callback to receive volume changes.
128     * <p>
129     * Used internally by the support library.
130     * <p>
131     */
132    public void setCallback(Callback callback) {
133        mCallback = callback;
134    }
135
136    /**
137     * Gets the underlying framework {@link android.media.VolumeProvider} object.
138     * <p>
139     * This method is only supported on API 21+.
140     * </p>
141     *
142     * @return An equivalent {@link android.media.VolumeProvider} object, or null if none.
143     */
144    public Object getVolumeProvider() {
145        if (mVolumeProviderObj != null || Build.VERSION.SDK_INT < 21) {
146            return mVolumeProviderObj;
147        }
148
149        mVolumeProviderObj = VolumeProviderCompatApi21.createVolumeProvider(
150                mControlType, mMaxVolume, mCurrentVolume, new VolumeProviderCompatApi21.Delegate() {
151
152            @Override
153            public void onSetVolumeTo(int volume) {
154                VolumeProviderCompat.this.onSetVolumeTo(volume);
155            }
156
157            @Override
158            public void onAdjustVolume(int direction) {
159                VolumeProviderCompat.this.onAdjustVolume(direction);
160            }
161        });
162        return mVolumeProviderObj;
163    }
164
165    /**
166     * Listens for changes to the volume.
167     */
168    public static abstract class Callback {
169        public abstract void onVolumeChanged(VolumeProviderCompat volumeProvider);
170    }
171}