Merge "Improve javadocs in MediaController and VolumeProvider" into udc-dev (b6d728a9) · Commits · e / os / android_frameworks_base

media/java/android/media/VolumeProvider.java

+21 −20

Original line number	Diff line number	Diff line
		@@ -17,6 +17,7 @@ package android.media;

		import android.annotation.IntDef;
		import android.annotation.Nullable;
		import android.media.MediaRouter2.RoutingController;
		import android.media.session.MediaSession;

		import java.lang.annotation.Retention;
		@@ -66,32 +67,28 @@ public abstract class VolumeProvider {
		private Callback mCallback;

		/**
		* Create a new volume provider for handling volume events. You must specify
		* the type of volume control, the maximum volume that can be used, and the
		* current volume on the output.
		* Creates a new volume provider for handling volume events.
		*
		* @param volumeControl The method for controlling volume that is used by
		* this provider.
		* @param volumeControl See {@link #getVolumeControl()}.
		* @param maxVolume The maximum allowed volume.
		* @param currentVolume The current volume on the output.
		*/

		public VolumeProvider(@ControlType int volumeControl, int maxVolume, int currentVolume) {
		this(volumeControl, maxVolume, currentVolume, null);
		}

		/**
		* Create a new volume provider for handling volume events. You must specify
		* the type of volume control, the maximum volume that can be used, and the
		* current volume on the output.
		* Creates a new volume provider for handling volume events.
		*
		* @param volumeControl The method for controlling volume that is used by
		* this provider.
		* @param volumeControl See {@link #getVolumeControl()}.
		* @param maxVolume The maximum allowed volume.
		* @param currentVolume The current volume on the output.
		* @param volumeControlId The volume control ID of this provider.
		* @param volumeControlId See {@link #getVolumeControlId()}.
		*/
		public VolumeProvider(@ControlType int volumeControl, int maxVolume, int currentVolume,
		public VolumeProvider(
		@ControlType int volumeControl,
		int maxVolume,
		int currentVolume,
		@Nullable String volumeControlId) {
		mControlType = volumeControl;
		mMaxVolume = maxVolume;
		@@ -100,7 +97,10 @@ public abstract class VolumeProvider {
		}

		/**
		* Get the volume control type that this volume provider uses.
		* Gets the volume control type that this volume provider uses.
		*
		* <p>One of {@link #VOLUME_CONTROL_FIXED}, {@link #VOLUME_CONTROL_ABSOLUTE}, or {@link
		* #VOLUME_CONTROL_RELATIVE}.
		*
		* @return The volume control type for this volume provider
		*/
		@@ -110,7 +110,7 @@ public abstract class VolumeProvider {
		}

		/**
		* Get the maximum volume this provider allows.
		* Gets the maximum volume this provider allows.
		*
		* @return The max allowed volume.
		*/
		@@ -129,8 +129,8 @@ public abstract class VolumeProvider {
		}

		/**
		* Notify the system that the current volume has been changed. This must be
		* called every time the volume changes to ensure it is displayed properly.
		* Notifies the system that the current volume has been changed. This must be called every time
		* the volume changes to ensure it is displayed properly.
		*
		* @param currentVolume The current volume on the output.
		*/
		@@ -142,10 +142,11 @@ public abstract class VolumeProvider {
		}

		/**
		* Gets the volume control ID. It can be used to identify which volume provider is
		* used by the session.
		* Gets the {@link RoutingController#getId() routing controller id} of the {@link
		* RoutingController} associated with this volume provider, or null if unset.
		*
		* @return the volume control ID or {@code null} if it isn't set.
		* <p>This id allows mapping this volume provider to a routing controller, which provides
		* information about the media route and allows controlling its volume.
		*/
		@Nullable
		public final String getVolumeControlId() {

media/java/android/media/session/MediaController.java

+19 −40

Original line number	Diff line number	Diff line
		@@ -29,7 +29,6 @@ import android.media.AudioAttributes;
		import android.media.AudioManager;
		import android.media.MediaMetadata;
		import android.media.Rating;
		import android.media.RoutingSessionInfo;
		import android.media.VolumeProvider;
		import android.media.VolumeProvider.ControlType;
		import android.media.session.MediaSession.QueueItem;
		@@ -993,26 +992,23 @@ public final class MediaController {
		/**
		* Creates a new playback info.
		*
		* @param playbackType The playback type. Should be {@link #PLAYBACK_TYPE_LOCAL} or
		* {@link #PLAYBACK_TYPE_REMOTE}
		* @param volumeControl The volume control. Should be one of:
		* {@link VolumeProvider#VOLUME_CONTROL_ABSOLUTE},
		* {@link VolumeProvider#VOLUME_CONTROL_RELATIVE}, and
		* {@link VolumeProvider#VOLUME_CONTROL_FIXED}.
		* @param playbackType The playback type. Should be {@link #PLAYBACK_TYPE_LOCAL} or {@link
		* #PLAYBACK_TYPE_REMOTE}
		* @param volumeControl See {@link #getVolumeControl()}.
		* @param maxVolume The max volume. Should be equal or greater than zero.
		* @param currentVolume The current volume. Should be in the interval [0, maxVolume].
		* @param audioAttrs The audio attributes for this playback. Should not be null.
		* @param volumeControlId The {@link RoutingSessionInfo#getId() routing session id} of the
		* {@link RoutingSessionInfo} associated with this controller, or null if not
		* applicable. This id allows mapping this controller to a routing session which, when
		* applicable, provides information about the remote device, and support for volume
		* adjustment.
		* @param volumeControlId See {@link #getVolumeControlId()}.
		* @hide
		*/
		@SystemApi(client = SystemApi.Client.MODULE_LIBRARIES)
		public PlaybackInfo(@PlaybackType int playbackType, @ControlType int volumeControl,
		@IntRange(from = 0) int maxVolume, @IntRange(from = 0) int currentVolume,
		@NonNull AudioAttributes audioAttrs, @Nullable String volumeControlId) {
		public PlaybackInfo(
		@PlaybackType int playbackType,
		@ControlType int volumeControl,
		@IntRange(from = 0) int maxVolume,
		@IntRange(from = 0) int currentVolume,
		@NonNull AudioAttributes audioAttrs,
		@Nullable String volumeControlId) {
		mPlaybackType = playbackType;
		mVolumeControl = volumeControl;
		mMaxVolume = maxVolume;
		@@ -1044,14 +1040,8 @@ public final class MediaController {
		}

		/**
		* Get the type of volume control that can be used. One of:
		* <ul>
		* <li>{@link VolumeProvider#VOLUME_CONTROL_ABSOLUTE}</li>
		* <li>{@link VolumeProvider#VOLUME_CONTROL_RELATIVE}</li>
		* <li>{@link VolumeProvider#VOLUME_CONTROL_FIXED}</li>
		* </ul>
		*
		* @return The type of volume control that may be used with this session.
		* Get the volume control type associated to the session, as indicated by {@link
		* VolumeProvider#getVolumeControl()}.
		*/
		public int getVolumeControl() {
		return mVolumeControl;
		@@ -1076,10 +1066,9 @@ public final class MediaController {
		}

		/**
		* Get the audio attributes for this session. The attributes will affect
		* volume handling for the session. When the volume type is
		* {@link PlaybackInfo#PLAYBACK_TYPE_REMOTE} these may be ignored by the
		* remote volume handler.
		* Get the audio attributes for this session. The attributes will affect volume handling for
		* the session. When the playback type is {@link PlaybackInfo#PLAYBACK_TYPE_REMOTE} these
		* may be ignored by the remote volume handler.
		*
		* @return The attributes for this session.
		*/
		@@ -1088,19 +1077,9 @@ public final class MediaController {
		}

		/**
		* Gets the volume control ID for this session. It can be used to identify which
		* volume provider is used by the session.
		* <p>
		* When the session starts to use {@link #PLAYBACK_TYPE_REMOTE remote volume handling},
		* a volume provider should be set and it may set the volume control ID of the provider
		* if the session wants to inform which volume provider is used.
		* It can be {@code null} if the session didn't set the volume control ID or it uses
		* {@link #PLAYBACK_TYPE_LOCAL local playback}.
		* </p>
		*
		* @return the volume control ID for this session or {@code null} if it uses local playback
		* or not set.
		* @see VolumeProvider#getVolumeControlId()
		* Get the routing controller ID for this session, as indicated by {@link
		* VolumeProvider#getVolumeControlId()}. Returns null if unset, or if {@link
		* #getPlaybackType()} is {@link #PLAYBACK_TYPE_LOCAL}.
		*/
		@Nullable
		public String getVolumeControlId() {