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;
17
18import android.media.session.MediaSession;
19
20/**
21 * Handles requests to adjust or set the volume on a session. This is also used
22 * to push volume updates back to the session. The provider must call
23 * {@link #setCurrentVolume(int)} each time the volume being provided changes.
24 * <p>
25 * You can set a volume provider on a session by calling
26 * {@link MediaSession#setPlaybackToRemote}.
27 */
28public abstract class VolumeProvider {
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    /**
55     * Create a new volume provider for handling volume events. You must specify
56     * the type of volume control, the maximum volume that can be used, and the
57     * current volume on the output.
58     *
59     * @param volumeControl The method for controlling volume that is used by
60     *            this provider.
61     * @param maxVolume The maximum allowed volume.
62     * @param currentVolume The current volume on the output.
63     */
64    public VolumeProvider(int volumeControl, int maxVolume, int currentVolume) {
65        mControlType = volumeControl;
66        mMaxVolume = maxVolume;
67        mCurrentVolume = currentVolume;
68    }
69
70    /**
71     * Get the volume control type that this volume provider uses.
72     *
73     * @return The volume control type for this volume provider
74     */
75    public final int getVolumeControl() {
76        return mControlType;
77    }
78
79    /**
80     * Get the maximum volume this provider allows.
81     *
82     * @return The max allowed volume.
83     */
84    public final int getMaxVolume() {
85        return mMaxVolume;
86    }
87
88    /**
89     * Gets the current volume. This will be the last value set by
90     * {@link #setCurrentVolume(int)}.
91     *
92     * @return The current volume.
93     */
94    public final int getCurrentVolume() {
95        return mCurrentVolume;
96    }
97
98    /**
99     * Notify the system that the current volume has been changed. This must be
100     * called every time the volume changes to ensure it is displayed properly.
101     *
102     * @param currentVolume The current volume on the output.
103     */
104    public final void setCurrentVolume(int currentVolume) {
105        mCurrentVolume = currentVolume;
106        if (mCallback != null) {
107            mCallback.onVolumeChanged(this);
108        }
109    }
110
111    /**
112     * Override to handle requests to set the volume of the current output.
113     * After the volume has been modified {@link #setCurrentVolume} must be
114     * called to notify the system.
115     *
116     * @param volume The volume to set the output to.
117     */
118    public void onSetVolumeTo(int volume) {
119    }
120
121    /**
122     * Override to handle requests to adjust the volume of the current output.
123     * Direction will be one of {@link AudioManager#ADJUST_LOWER},
124     * {@link AudioManager#ADJUST_RAISE}, {@link AudioManager#ADJUST_SAME}.
125     * After the volume has been modified {@link #setCurrentVolume} must be
126     * called to notify the system.
127     *
128     * @param direction The direction to change the volume in.
129     */
130    public void onAdjustVolume(int direction) {
131    }
132
133    /**
134     * Sets a callback to receive volume changes.
135     * @hide
136     */
137    public void setCallback(Callback callback) {
138        mCallback = callback;
139    }
140
141    /**
142     * Listens for changes to the volume.
143     * @hide
144     */
145    public static abstract class Callback {
146        public abstract void onVolumeChanged(VolumeProvider volumeProvider);
147    }
148}