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 mCurrentVolume = currentVolume; 119 Object volumeProviderObj = getVolumeProvider(); 120 if (volumeProviderObj != null) { 121 VolumeProviderCompatApi21.setCurrentVolume(volumeProviderObj, currentVolume); 122 } 123 if (mCallback != null) { 124 mCallback.onVolumeChanged(this); 125 } 126 } 127 128 /** 129 * Override to handle requests to set the volume of the current output. 130 * 131 * @param volume The volume to set the output to. 132 */ 133 public void onSetVolumeTo(int volume) { 134 } 135 136 /** 137 * Override to handle requests to adjust the volume of the current output. 138 * 139 * @param direction The direction to adjust the volume in. 140 */ 141 public void onAdjustVolume(int direction) { 142 } 143 144 /** 145 * Sets a callback to receive volume changes. 146 * <p> 147 * Used internally by the support library. 148 * <p> 149 */ 150 public void setCallback(Callback callback) { 151 mCallback = callback; 152 } 153 154 /** 155 * Gets the underlying framework {@link android.media.VolumeProvider} object. 156 * <p> 157 * This method is only supported on API 21+. 158 * </p> 159 * 160 * @return An equivalent {@link android.media.VolumeProvider} object, or null if none. 161 */ 162 public Object getVolumeProvider() { 163 if (mVolumeProviderObj != null || Build.VERSION.SDK_INT < 21) { 164 return mVolumeProviderObj; 165 } 166 167 mVolumeProviderObj = VolumeProviderCompatApi21.createVolumeProvider( 168 mControlType, mMaxVolume, mCurrentVolume, new VolumeProviderCompatApi21.Delegate() { 169 170 @Override 171 public void onSetVolumeTo(int volume) { 172 VolumeProviderCompat.this.onSetVolumeTo(volume); 173 } 174 175 @Override 176 public void onAdjustVolume(int direction) { 177 VolumeProviderCompat.this.onAdjustVolume(direction); 178 } 179 }); 180 return mVolumeProviderObj; 181 } 182 183 /** 184 * Listens for changes to the volume. 185 */ 186 public static abstract class Callback { 187 public abstract void onVolumeChanged(VolumeProviderCompat volumeProvider); 188 } 189} 190