Tweak javadocs for selectable and transferable routes (b6f67344) · Commits · e / os / android_frameworks_base

media/java/android/media/MediaRouter2.java

+15 −7

Original line number	Diff line number	Diff line
		@@ -1771,10 +1771,12 @@ public final class MediaRouter2 {
		}

		/**
		* A class to control media routing session in media route provider. For example,
		* selecting/deselecting/transferring to routes of a session can be done through this. Instances
		* are created when {@link TransferCallback#onTransfer(RoutingController, RoutingController)} is
		* called, which is invoked after {@link #transferTo(MediaRoute2Info)} is called.
		* Controls a media routing session.
		*
		* <p>Routing controllers wrap a {@link RoutingSessionInfo}, taking care of mapping route ids to
		* {@link MediaRoute2Info} instances. You can still access the underlying session using {@link
		* #getRoutingSessionInfo()}, but keep in mind it can be changed by other threads. Changes to
		* the routing session are notified via {@link ControllerCallback}.
		*/
		public class RoutingController {
		private final Object mControllerLock = new Object();
		@@ -1836,7 +1838,9 @@ public final class MediaRouter2 {
		}

		/**
		* @return the unmodifiable list of currently selected routes
		* Returns the unmodifiable list of currently selected routes
		*
		* @see RoutingSessionInfo#getSelectedRoutes()
		*/
		@NonNull
		public List<MediaRoute2Info> getSelectedRoutes() {
		@@ -1848,7 +1852,9 @@ public final class MediaRouter2 {
		}

		/**
		* @return the unmodifiable list of selectable routes for the session.
		* Returns the unmodifiable list of selectable routes for the session.
		*
		* @see RoutingSessionInfo#getSelectableRoutes()
		*/
		@NonNull
		public List<MediaRoute2Info> getSelectableRoutes() {
		@@ -1860,7 +1866,9 @@ public final class MediaRouter2 {
		}

		/**
		* @return the unmodifiable list of deselectable routes for the session.
		* Returns the unmodifiable list of deselectable routes for the session.
		*
		* @see RoutingSessionInfo#getDeselectableRoutes()
		*/
		@NonNull
		public List<MediaRoute2Info> getDeselectableRoutes() {

media/java/android/media/RoutingSessionInfo.java

+50 −2

Original line number	Diff line number	Diff line
		@@ -262,7 +262,8 @@ public final class RoutingSessionInfo implements Parcelable {
		}

		/**
		* Gets the provider id of the session.
		* Gets the provider ID of the session.
		*
		* @hide
		*/
		@Nullable
		@@ -271,7 +272,15 @@ public final class RoutingSessionInfo implements Parcelable {
		}

		/**
		* Gets the list of IDs of selected routes for the session. It shouldn't be empty.
		* Gets the list of IDs of selected routes for the session.
		*
		* <p>Selected routes are the routes that this session is actively routing media to.
		*
		* <p>The behavior of a routing session with multiple selected routes is ultimately defined by
		* the {@link MediaRoute2ProviderService} implementation. However, typically, it's expected that
		* all the selected routes of a routing session are playing the same media in sync.
		*
		* @return A non-empty list of selected route ids.
		*/
		@NonNull
		public List<String> getSelectedRoutes() {
		@@ -280,6 +289,16 @@ public final class RoutingSessionInfo implements Parcelable {

		/**
		* Gets the list of IDs of selectable routes for the session.
		*
		* <p>Selectable routes can be added to a routing session (via {@link
		* MediaRouter2.RoutingController#selectRoute}) in order to add them to the {@link
		* #getSelectedRoutes() selected routes}, so that media plays on the newly selected route along
		* with the other selected routes.
		*
		* <p>Not to be confused with {@link #getTransferableRoutes() transferable routes}. Transferring
		* to a route makes it the sole selected route.
		*
		* @return A possibly empty list of selectable route ids.
		*/
		@NonNull
		public List<String> getSelectableRoutes() {
		@@ -288,6 +307,17 @@ public final class RoutingSessionInfo implements Parcelable {

		/**
		* Gets the list of IDs of deselectable routes for the session.
		*
		* <p>Deselectable routes can be removed from the {@link #getSelectedRoutes() selected routes},
		* so that the routing session stops routing to the newly deselected route, but continues on any
		* remaining selected routes.
		*
		* <p>Deselectable routes should be a subset of the {@link #getSelectedRoutes() selected
		* routes}, meaning not all of the selected routes might be deselectable. For example, one of
		* the selected routes may be a leader device coordinating group playback, which must always
		* remain selected while the session is active.
		*
		* @return A possibly empty list of deselectable route ids.
		*/
		@NonNull
		public List<String> getDeselectableRoutes() {
		@@ -296,6 +326,24 @@ public final class RoutingSessionInfo implements Parcelable {

		/**
		* Gets the list of IDs of transferable routes for the session.
		*
		* <p>Transferring to a route (for example, using {@link MediaRouter2#transferTo}) replaces the
		* list of {@link #getSelectedRoutes() selected routes} with the target route, causing playback
		* to move from one route to another.
		*
		* <p>Note that this is different from {@link #getSelectableRoutes() selectable routes}, because
		* selecting a route makes it part of the selected routes, while transferring to a route makes
		* it the selected route. A route can be both transferable and selectable.
		*
		* <p>Note that playback may transfer across routes without the target route being in the list
		* of transferable routes. This can happen by creating a new routing session to the target
		* route, and releasing the routing session being transferred from. The difference is that a
		* transfer to a route in the transferable list can happen with no intervention from the app,
		* with the route provider taking care of the entire operation. A transfer to a route that is
		* not in the list of transferable routes (by creating a new session) requires the app to move
		* the playback state from one device to the other.
		*
		* @return A possibly empty list of transferable route ids.
		*/
		@NonNull
		public List<String> getTransferableRoutes() {