Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Improve javadocs in MediaController and VolumeProvider

Browse Source 
Bug: 277877803
Test: N/A javadoc change only.
Change-Id: I6fe9ec88f93057ea697310a461914146cd0cc7ad
This commit is contained in:
Santiago Seifert
2023-04-18 14:59:09 +00:00
parent 2b31afee53
commit f09f927554
2 changed files with 40 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files

41
media/java/android/media/VolumeProvider.java
View File

@@ -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() {

59
media/java/android/media/session/MediaController.java
View File

@@ -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() {