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