Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit f09f9275 authored by Santiago Seifert's avatar Santiago Seifert
Browse files

Improve javadocs in MediaController and VolumeProvider 

Bug: 277877803
Test: N/A javadoc change only.
Change-Id: I6fe9ec88f93057ea697310a461914146cd0cc7ad
parent 2b31afee

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