android-34/android/media/RouteListingPreference.java - platform/prebuilts/fullsdk/sources - Git at Google

 /*
  * Copyright (C) 2022 The Android Open Source Project
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
  *      http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */

 package android.media;

 import android.annotation.IntDef;
 import android.annotation.NonNull;
 import android.annotation.Nullable;
 import android.content.ComponentName;
 import android.content.Intent;
 import android.os.Parcel;
 import android.os.Parcelable;
 import android.text.TextUtils;

 import com.android.internal.util.Preconditions;

 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.util.ArrayList;
 import java.util.List;
 import java.util.Locale;
 import java.util.Objects;

 /**
  * Allows applications to customize the list of routes used for media routing (for example, in the
  * System UI Output Switcher).
  *
  * @see MediaRouter2#setRouteListingPreference
  * @see Item
  */
 public final class RouteListingPreference implements Parcelable {

     /**
      * {@link Intent} action that the system uses to take the user the app when the user selects an
      * {@link Item} whose {@link Item#getSelectionBehavior() selection behavior} is {@link
      * Item#SELECTION_BEHAVIOR_GO_TO_APP}.
      *
      * <p>The launched intent will identify the selected item using the extra identified by {@link
      * #EXTRA_ROUTE_ID}.
      *
      * @see #getLinkedItemComponentName()
      * @see Item#SELECTION_BEHAVIOR_GO_TO_APP
      */
     public static final String ACTION_TRANSFER_MEDIA = "android.media.action.TRANSFER_MEDIA";

     /**
      * {@link Intent} string extra key that contains the {@link Item#getRouteId() id} of the route
      * to transfer to, as part of an {@link #ACTION_TRANSFER_MEDIA} intent.
      *
      * @see #getLinkedItemComponentName()
      * @see Item#SELECTION_BEHAVIOR_GO_TO_APP
      */
     public static final String EXTRA_ROUTE_ID = "android.media.extra.ROUTE_ID";

     @NonNull
     public static final Creator<RouteListingPreference> CREATOR =
             new Creator<>() {
                 @Override
                 public RouteListingPreference createFromParcel(Parcel in) {
                     return new RouteListingPreference(in);
                 }

                 @Override
                 public RouteListingPreference[] newArray(int size) {
                     return new RouteListingPreference[size];
                 }
             };

     @NonNull private final List<Item> mItems;
     private final boolean mUseSystemOrdering;
     @Nullable private final ComponentName mLinkedItemComponentName;

     private RouteListingPreference(Builder builder) {
         mItems = builder.mItems;
         mUseSystemOrdering = builder.mUseSystemOrdering;
         mLinkedItemComponentName = builder.mLinkedItemComponentName;
     }

     private RouteListingPreference(Parcel in) {
         List<Item> items =
                 in.readParcelableList(new ArrayList<>(), Item.class.getClassLoader(), Item.class);
         mItems = List.copyOf(items);
         mUseSystemOrdering = in.readBoolean();
         mLinkedItemComponentName = ComponentName.readFromParcel(in);
     }

     /**
      * Returns an unmodifiable list containing the {@link Item items} that the app wants to be
      * listed for media routing.
      */
     @NonNull
     public List<Item> getItems() {
         return mItems;
     }

     /**
      * Returns true if the application would like media route listing to use the system's ordering
      * strategy, or false if the application would like route listing to respect the ordering
      * obtained from {@link #getItems()}.
      *
      * <p>The system's ordering strategy is implementation-dependent, but may take into account each
      * route's recency or frequency of use in order to rank them.
      */
     public boolean getUseSystemOrdering() {
         return mUseSystemOrdering;
     }

     /**
      * Returns a {@link ComponentName} for navigating to the application.
      *
      * <p>Must not be null if any of the {@link #getItems() items} of this route listing preference
      * has {@link Item#getSelectionBehavior() selection behavior} {@link
      * Item#SELECTION_BEHAVIOR_GO_TO_APP}.
      *
      * <p>The system navigates to the application when the user selects {@link Item} with {@link
      * Item#SELECTION_BEHAVIOR_GO_TO_APP} by launching an intent to the returned {@link
      * ComponentName}, using action {@link #ACTION_TRANSFER_MEDIA}, with the extra {@link
      * #EXTRA_ROUTE_ID}.
      */
     @Nullable
     public ComponentName getLinkedItemComponentName() {
         return mLinkedItemComponentName;
     }

     // RouteListingPreference Parcelable implementation.

     @Override
     public int describeContents() {
         return 0;
     }

     @Override
     public void writeToParcel(@NonNull Parcel dest, int flags) {
         dest.writeParcelableList(mItems, flags);
         dest.writeBoolean(mUseSystemOrdering);
         ComponentName.writeToParcel(mLinkedItemComponentName, dest);
     }

     // Equals and hashCode.

     @Override
     public boolean equals(Object other) {
         if (this == other) {
             return true;
         }
         if (!(other instanceof RouteListingPreference)) {
             return false;
         }
         RouteListingPreference that = (RouteListingPreference) other;
         return mItems.equals(that.mItems)
                 && mUseSystemOrdering == that.mUseSystemOrdering
                 && Objects.equals(mLinkedItemComponentName, that.mLinkedItemComponentName);
     }

     @Override
     public int hashCode() {
         return Objects.hash(mItems, mUseSystemOrdering, mLinkedItemComponentName);
     }

     /** Builder for {@link RouteListingPreference}. */
     public static final class Builder {

         private List<Item> mItems;
         private boolean mUseSystemOrdering;
         private ComponentName mLinkedItemComponentName;

         /** Creates a new instance with default values (documented in the setters). */
         public Builder() {
             mItems = List.of();
             mUseSystemOrdering = true;
         }

         /**
          * See {@link #getItems()}
          *
          * <p>The default value is an empty list.
          */
         @NonNull
         public Builder setItems(@NonNull List<Item> items) {
             mItems = List.copyOf(Objects.requireNonNull(items));
             return this;
         }

         /**
          * See {@link #getUseSystemOrdering()}
          *
          * <p>The default value is {@code true}.
          */
         // Lint requires "isUseSystemOrdering", but "getUseSystemOrdering" is a better name.
         @SuppressWarnings("MissingGetterMatchingBuilder")
         @NonNull
         public Builder setUseSystemOrdering(boolean useSystemOrdering) {
             mUseSystemOrdering = useSystemOrdering;
             return this;
         }

         /**
          * See {@link #getLinkedItemComponentName()}.
          *
          * <p>The default value is {@code null}.
          */
         @NonNull
         public Builder setLinkedItemComponentName(@Nullable ComponentName linkedItemComponentName) {
             mLinkedItemComponentName = linkedItemComponentName;
             return this;
         }

         /**
          * Creates and returns a new {@link RouteListingPreference} instance with the given
          * parameters.
          */
         @NonNull
         public RouteListingPreference build() {
             return new RouteListingPreference(this);
         }
     }

     /** Holds preference information for a specific route in a {@link RouteListingPreference}. */
     public static final class Item implements Parcelable {

         /** @hide */
         @Retention(RetentionPolicy.SOURCE)
         @IntDef(
                 prefix = {"SELECTION_BEHAVIOR_"},
                 value = {
                     SELECTION_BEHAVIOR_NONE,
                     SELECTION_BEHAVIOR_TRANSFER,
                     SELECTION_BEHAVIOR_GO_TO_APP
                 })
         public @interface SelectionBehavior {}

         /** The corresponding route is not selectable by the user. */
         public static final int SELECTION_BEHAVIOR_NONE = 0;
         /** If the user selects the corresponding route, the media transfers to the said route. */
         public static final int SELECTION_BEHAVIOR_TRANSFER = 1;
         /**
          * If the user selects the corresponding route, the system takes the user to the
          * application.
          *
          * <p>The system uses {@link #getLinkedItemComponentName()} in order to navigate to the app.
          */
         public static final int SELECTION_BEHAVIOR_GO_TO_APP = 2;

         /** @hide */
         @Retention(RetentionPolicy.SOURCE)
         @IntDef(
                 flag = true,
                 prefix = {"FLAG_"},
                 value = {FLAG_ONGOING_SESSION, FLAG_ONGOING_SESSION_MANAGED, FLAG_SUGGESTED})
         public @interface Flags {}

         /**
          * The corresponding route is already hosting a session with the app that owns this listing
          * preference.
          */
         public static final int FLAG_ONGOING_SESSION = 1;

         /**
          * Signals that the ongoing session on the corresponding route is managed by the current
          * user of the app.
          *
          * <p>The system can use this flag to provide visual indication that the route is not only
          * hosting a session, but also that the user has ownership over said session.
          *
          * <p>This flag is ignored if {@link #FLAG_ONGOING_SESSION} is not set, or if the
          * corresponding route is not currently selected.
          *
          * <p>This flag does not affect volume adjustment (see {@link VolumeProvider}, and {@link
          * MediaRoute2Info#getVolumeHandling()}), or any aspect other than the visual representation
          * of the corresponding item.
          */
         public static final int FLAG_ONGOING_SESSION_MANAGED = 1 << 1;

         /**
          * The corresponding route is specially likely to be selected by the user.
          *
          * <p>A UI reflecting this preference may reserve a specific space for suggested routes,
          * making it more accessible to the user. If the number of suggested routes exceeds the
          * number supported by the UI, the routes listed first in {@link
          * RouteListingPreference#getItems()} will take priority.
          */
         public static final int FLAG_SUGGESTED = 1 << 2;

         /** @hide */
         @Retention(RetentionPolicy.SOURCE)
         @IntDef(
                 prefix = {"SUBTEXT_"},
                 value = {
                     SUBTEXT_NONE,
                     SUBTEXT_ERROR_UNKNOWN,
                     SUBTEXT_SUBSCRIPTION_REQUIRED,
                     SUBTEXT_DOWNLOADED_CONTENT_ROUTING_DISALLOWED,
                     SUBTEXT_AD_ROUTING_DISALLOWED,
                     SUBTEXT_DEVICE_LOW_POWER,
                     SUBTEXT_UNAUTHORIZED,
                     SUBTEXT_TRACK_UNSUPPORTED,
                     SUBTEXT_CUSTOM
                 })
         public @interface SubText {}

         /** The corresponding route has no associated subtext. */
         public static final int SUBTEXT_NONE = 0;
         /**
          * The corresponding route's subtext must indicate that it is not available because of an
          * unknown error.
          */
         public static final int SUBTEXT_ERROR_UNKNOWN = 1;
         /**
          * The corresponding route's subtext must indicate that it requires a special subscription
          * in order to be available for routing.
          */
         public static final int SUBTEXT_SUBSCRIPTION_REQUIRED = 2;
         /**
          * The corresponding route's subtext must indicate that downloaded content cannot be routed
          * to it.
          */
         public static final int SUBTEXT_DOWNLOADED_CONTENT_ROUTING_DISALLOWED = 3;
         /**
          * The corresponding route's subtext must indicate that it is not available because an ad is
          * in progress.
          */
         public static final int SUBTEXT_AD_ROUTING_DISALLOWED = 4;
         /**
          * The corresponding route's subtext must indicate that it is not available because the
          * device is in low-power mode.
          */
         public static final int SUBTEXT_DEVICE_LOW_POWER = 5;
         /**
          * The corresponding route's subtext must indicate that it is not available because the user
          * is not authorized to route to it.
          */
         public static final int SUBTEXT_UNAUTHORIZED = 6;
         /**
          * The corresponding route's subtext must indicate that it is not available because the
          * device does not support the current media track.
          */
         public static final int SUBTEXT_TRACK_UNSUPPORTED = 7;
         /**
          * The corresponding route's subtext must be obtained from {@link
          * #getCustomSubtextMessage()}.
          *
          * <p>Applications should strongly prefer one of the other disable reasons (for the full
          * list, see {@link #getSubText()}) in order to guarantee correct localization and rendering
          * across all form factors.
          */
         public static final int SUBTEXT_CUSTOM = 10000;

         @NonNull
         public static final Creator<Item> CREATOR =
                 new Creator<>() {
                     @Override
                     public Item createFromParcel(Parcel in) {
                         return new Item(in);
                     }

                     @Override
                     public Item[] newArray(int size) {
                         return new Item[size];
                     }
                 };

         @NonNull private final String mRouteId;
         @SelectionBehavior private final int mSelectionBehavior;
         @Flags private final int mFlags;
         @SubText private final int mSubText;

         @Nullable private final CharSequence mCustomSubtextMessage;

         private Item(@NonNull Builder builder) {
             mRouteId = builder.mRouteId;
             mSelectionBehavior = builder.mSelectionBehavior;
             mFlags = builder.mFlags;
             mSubText = builder.mSubText;
             mCustomSubtextMessage = builder.mCustomSubtextMessage;
             validateCustomMessageSubtext();
         }

         private Item(Parcel in) {
             mRouteId = in.readString();
             Preconditions.checkArgument(!TextUtils.isEmpty(mRouteId));
             mSelectionBehavior = in.readInt();
             mFlags = in.readInt();
             mSubText = in.readInt();
             mCustomSubtextMessage = in.readCharSequence();
             validateCustomMessageSubtext();
         }

         /**
          * Returns the id of the route that corresponds to this route listing preference item.
          *
          * @see MediaRoute2Info#getId()
          */
         @NonNull
         public String getRouteId() {
             return mRouteId;
         }

         /**
          * Returns the behavior that the corresponding route has if the user selects it.
          *
          * @see #SELECTION_BEHAVIOR_NONE
          * @see #SELECTION_BEHAVIOR_TRANSFER
          * @see #SELECTION_BEHAVIOR_GO_TO_APP
          */
         public int getSelectionBehavior() {
             return mSelectionBehavior;
         }

         /**
          * Returns the flags associated to the route that corresponds to this item.
          *
          * @see #FLAG_ONGOING_SESSION
          * @see #FLAG_ONGOING_SESSION_MANAGED
          * @see #FLAG_SUGGESTED
          */
         @Flags
         public int getFlags() {
             return mFlags;
         }

         /**
          * Returns the type of subtext associated to this route.
          *
          * <p>Subtext types other than {@link #SUBTEXT_NONE} and {@link #SUBTEXT_CUSTOM} must not
          * have {@link #SELECTION_BEHAVIOR_TRANSFER}.
          *
          * <p>If this method returns {@link #SUBTEXT_CUSTOM}, then the subtext is obtained form
          * {@link #getCustomSubtextMessage()}.
          *
          * @see #SUBTEXT_NONE,
          * @see #SUBTEXT_ERROR_UNKNOWN,
          * @see #SUBTEXT_SUBSCRIPTION_REQUIRED,
          * @see #SUBTEXT_DOWNLOADED_CONTENT_ROUTING_DISALLOWED,
          * @see #SUBTEXT_AD_ROUTING_DISALLOWED,
          * @see #SUBTEXT_DEVICE_LOW_POWER,
          * @see #SUBTEXT_UNAUTHORIZED ,
          * @see #SUBTEXT_TRACK_UNSUPPORTED,
          * @see #SUBTEXT_CUSTOM
          */
         @SubText
         public int getSubText() {
             return mSubText;
         }

         /**
          * Returns a human-readable {@link CharSequence} providing the subtext for the corresponding
          * route.
          *
          * <p>This value is ignored if the {@link #getSubText() subtext} for this item is not {@link
          * #SUBTEXT_CUSTOM}..
          *
          * <p>Applications must provide a localized message that matches the system's locale. See
          * {@link Locale#getDefault()}.
          *
          * <p>Applications should avoid using custom messages (and instead use one of non-custom
          * subtexts listed in {@link #getSubText()} in order to guarantee correct visual
          * representation and localization on all form factors.
          */
         @Nullable
         public CharSequence getCustomSubtextMessage() {
             return mCustomSubtextMessage;
         }

         // Item Parcelable implementation.

         @Override
         public int describeContents() {
             return 0;
         }

         @Override
         public void writeToParcel(@NonNull Parcel dest, int flags) {
             dest.writeString(mRouteId);
             dest.writeInt(mSelectionBehavior);
             dest.writeInt(mFlags);
             dest.writeInt(mSubText);
             dest.writeCharSequence(mCustomSubtextMessage);
         }

         // Equals and hashCode.

         @Override
         public boolean equals(Object other) {
             if (this == other) {
                 return true;
             }
             if (!(other instanceof Item)) {
                 return false;
             }
             Item item = (Item) other;
             return mRouteId.equals(item.mRouteId)
                     && mSelectionBehavior == item.mSelectionBehavior
                     && mFlags == item.mFlags
                     && mSubText == item.mSubText
                     && TextUtils.equals(mCustomSubtextMessage, item.mCustomSubtextMessage);
         }

         @Override
         public int hashCode() {
             return Objects.hash(
                     mRouteId, mSelectionBehavior, mFlags, mSubText, mCustomSubtextMessage);
         }

         // Internal methods.

         private void validateCustomMessageSubtext() {
             Preconditions.checkArgument(
                     mSubText != SUBTEXT_CUSTOM || mCustomSubtextMessage != null,
                     "The custom subtext message cannot be null if subtext is SUBTEXT_CUSTOM.");
         }

         // Internal classes.

         /** Builder for {@link Item}. */
         public static final class Builder {

             private final String mRouteId;
             private int mSelectionBehavior;
             private int mFlags;
             private int mSubText;
             private CharSequence mCustomSubtextMessage;

             /**
              * Constructor.
              *
              * @param routeId See {@link Item#getRouteId()}.
              */
             public Builder(@NonNull String routeId) {
                 Preconditions.checkArgument(!TextUtils.isEmpty(routeId));
                 mRouteId = routeId;
                 mSelectionBehavior = SELECTION_BEHAVIOR_TRANSFER;
                 mSubText = SUBTEXT_NONE;
             }

             /**
              * See {@link Item#getSelectionBehavior()}.
              *
              * <p>The default value is {@link #ACTION_TRANSFER_MEDIA}.
              */
             @NonNull
             public Builder setSelectionBehavior(int selectionBehavior) {
                 mSelectionBehavior = selectionBehavior;
                 return this;
             }

             /**
              * See {@link Item#getFlags()}.
              *
              * <p>The default value is zero (no flags).
              */
             @NonNull
             public Builder setFlags(int flags) {
                 mFlags = flags;
                 return this;
             }

             /**
              * See {@link Item#getSubText()}.
              *
              * <p>The default value is {@link #SUBTEXT_NONE}.
              */
             @NonNull
             public Builder setSubText(int subText) {
                 mSubText = subText;
                 return this;
             }

             /**
              * See {@link Item#getCustomSubtextMessage()}.
              *
              * <p>The default value is {@code null}.
              */
             @NonNull
             public Builder setCustomSubtextMessage(@Nullable CharSequence customSubtextMessage) {
                 mCustomSubtextMessage = customSubtextMessage;
                 return this;
             }

             /** Creates and returns a new {@link Item} with the given parameters. */
             @NonNull
             public Item build() {
                 return new Item(this);
             }
         }
     }
 }
	/*
	* Copyright (C) 2022 The Android Open Source Project
	*
	* Licensed under the Apache License, Version 2.0 (the "License");
	* you may not use this file except in compliance with the License.
	* You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software
	* distributed under the License is distributed on an "AS IS" BASIS,
	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	* See the License for the specific language governing permissions and
	* limitations under the License.
	*/

	package android.media;

	import android.annotation.IntDef;
	import android.annotation.NonNull;
	import android.annotation.Nullable;
	import android.content.ComponentName;
	import android.content.Intent;
	import android.os.Parcel;
	import android.os.Parcelable;
	import android.text.TextUtils;

	import com.android.internal.util.Preconditions;

	import java.lang.annotation.Retention;
	import java.lang.annotation.RetentionPolicy;
	import java.util.ArrayList;
	import java.util.List;
	import java.util.Locale;
	import java.util.Objects;

	/**
	* Allows applications to customize the list of routes used for media routing (for example, in the
	* System UI Output Switcher).
	*
	* @see MediaRouter2#setRouteListingPreference
	* @see Item
	*/
	public final class RouteListingPreference implements Parcelable {

	/**
	* {@link Intent} action that the system uses to take the user the app when the user selects an
	* {@link Item} whose {@link Item#getSelectionBehavior() selection behavior} is {@link
	* Item#SELECTION_BEHAVIOR_GO_TO_APP}.
	*
	* <p>The launched intent will identify the selected item using the extra identified by {@link
	* #EXTRA_ROUTE_ID}.
	*
	* @see #getLinkedItemComponentName()
	* @see Item#SELECTION_BEHAVIOR_GO_TO_APP
	*/
	public static final String ACTION_TRANSFER_MEDIA = "android.media.action.TRANSFER_MEDIA";

	/**
	* {@link Intent} string extra key that contains the {@link Item#getRouteId() id} of the route
	* to transfer to, as part of an {@link #ACTION_TRANSFER_MEDIA} intent.
	*
	* @see #getLinkedItemComponentName()
	* @see Item#SELECTION_BEHAVIOR_GO_TO_APP
	*/
	public static final String EXTRA_ROUTE_ID = "android.media.extra.ROUTE_ID";

	@NonNull
	public static final Creator<RouteListingPreference> CREATOR =
	new Creator<>() {
	@Override
	public RouteListingPreference createFromParcel(Parcel in) {
	return new RouteListingPreference(in);
	}

	@Override
	public RouteListingPreference[] newArray(int size) {
	return new RouteListingPreference[size];
	}
	};

	@NonNull private final List<Item> mItems;
	private final boolean mUseSystemOrdering;
	@Nullable private final ComponentName mLinkedItemComponentName;

	private RouteListingPreference(Builder builder) {
	mItems = builder.mItems;
	mUseSystemOrdering = builder.mUseSystemOrdering;
	mLinkedItemComponentName = builder.mLinkedItemComponentName;
	}

	private RouteListingPreference(Parcel in) {
	List<Item> items =
	in.readParcelableList(new ArrayList<>(), Item.class.getClassLoader(), Item.class);
	mItems = List.copyOf(items);
	mUseSystemOrdering = in.readBoolean();
	mLinkedItemComponentName = ComponentName.readFromParcel(in);
	}

	/**
	* Returns an unmodifiable list containing the {@link Item items} that the app wants to be
	* listed for media routing.
	*/
	@NonNull
	public List<Item> getItems() {
	return mItems;
	}

	/**
	* Returns true if the application would like media route listing to use the system's ordering
	* strategy, or false if the application would like route listing to respect the ordering
	* obtained from {@link #getItems()}.
	*
	* <p>The system's ordering strategy is implementation-dependent, but may take into account each
	* route's recency or frequency of use in order to rank them.
	*/
	public boolean getUseSystemOrdering() {
	return mUseSystemOrdering;
	}

	/**
	* Returns a {@link ComponentName} for navigating to the application.
	*
	* <p>Must not be null if any of the {@link #getItems() items} of this route listing preference
	* has {@link Item#getSelectionBehavior() selection behavior} {@link
	* Item#SELECTION_BEHAVIOR_GO_TO_APP}.
	*
	* <p>The system navigates to the application when the user selects {@link Item} with {@link
	* Item#SELECTION_BEHAVIOR_GO_TO_APP} by launching an intent to the returned {@link
	* ComponentName}, using action {@link #ACTION_TRANSFER_MEDIA}, with the extra {@link
	* #EXTRA_ROUTE_ID}.
	*/
	@Nullable
	public ComponentName getLinkedItemComponentName() {
	return mLinkedItemComponentName;
	}

	// RouteListingPreference Parcelable implementation.

	@Override
	public int describeContents() {
	return 0;
	}

	@Override
	public void writeToParcel(@NonNull Parcel dest, int flags) {
	dest.writeParcelableList(mItems, flags);
	dest.writeBoolean(mUseSystemOrdering);
	ComponentName.writeToParcel(mLinkedItemComponentName, dest);
	}

	// Equals and hashCode.

	@Override
	public boolean equals(Object other) {
	if (this == other) {
	return true;
	}
	if (!(other instanceof RouteListingPreference)) {
	return false;
	}
	RouteListingPreference that = (RouteListingPreference) other;
	return mItems.equals(that.mItems)
	&& mUseSystemOrdering == that.mUseSystemOrdering
	&& Objects.equals(mLinkedItemComponentName, that.mLinkedItemComponentName);
	}

	@Override
	public int hashCode() {
	return Objects.hash(mItems, mUseSystemOrdering, mLinkedItemComponentName);
	}

	/** Builder for {@link RouteListingPreference}. */
	public static final class Builder {

	private List<Item> mItems;
	private boolean mUseSystemOrdering;
	private ComponentName mLinkedItemComponentName;

	/** Creates a new instance with default values (documented in the setters). */
	public Builder() {
	mItems = List.of();
	mUseSystemOrdering = true;
	}

	/**
	* See {@link #getItems()}
	*
	* <p>The default value is an empty list.
	*/
	@NonNull
	public Builder setItems(@NonNull List<Item> items) {
	mItems = List.copyOf(Objects.requireNonNull(items));
	return this;
	}

	/**
	* See {@link #getUseSystemOrdering()}
	*
	* <p>The default value is {@code true}.
	*/
	// Lint requires "isUseSystemOrdering", but "getUseSystemOrdering" is a better name.
	@SuppressWarnings("MissingGetterMatchingBuilder")
	@NonNull
	public Builder setUseSystemOrdering(boolean useSystemOrdering) {
	mUseSystemOrdering = useSystemOrdering;
	return this;
	}

	/**
	* See {@link #getLinkedItemComponentName()}.
	*
	* <p>The default value is {@code null}.
	*/
	@NonNull
	public Builder setLinkedItemComponentName(@Nullable ComponentName linkedItemComponentName) {
	mLinkedItemComponentName = linkedItemComponentName;
	return this;
	}

	/**
	* Creates and returns a new {@link RouteListingPreference} instance with the given
	* parameters.
	*/
	@NonNull
	public RouteListingPreference build() {
	return new RouteListingPreference(this);
	}
	}

	/** Holds preference information for a specific route in a {@link RouteListingPreference}. */
	public static final class Item implements Parcelable {

	/** @hide */
	@Retention(RetentionPolicy.SOURCE)
	@IntDef(
	prefix = {"SELECTION_BEHAVIOR_"},
	value = {
	SELECTION_BEHAVIOR_NONE,
	SELECTION_BEHAVIOR_TRANSFER,
	SELECTION_BEHAVIOR_GO_TO_APP
	})
	public @interface SelectionBehavior {}

	/** The corresponding route is not selectable by the user. */
	public static final int SELECTION_BEHAVIOR_NONE = 0;
	/** If the user selects the corresponding route, the media transfers to the said route. */
	public static final int SELECTION_BEHAVIOR_TRANSFER = 1;
	/**
	* If the user selects the corresponding route, the system takes the user to the
	* application.
	*
	* <p>The system uses {@link #getLinkedItemComponentName()} in order to navigate to the app.
	*/
	public static final int SELECTION_BEHAVIOR_GO_TO_APP = 2;

	/** @hide */
	@Retention(RetentionPolicy.SOURCE)
	@IntDef(
	flag = true,
	prefix = {"FLAG_"},
	value = {FLAG_ONGOING_SESSION, FLAG_ONGOING_SESSION_MANAGED, FLAG_SUGGESTED})
	public @interface Flags {}

	/**
	* The corresponding route is already hosting a session with the app that owns this listing
	* preference.
	*/
	public static final int FLAG_ONGOING_SESSION = 1;

	/**
	* Signals that the ongoing session on the corresponding route is managed by the current
	* user of the app.
	*
	* <p>The system can use this flag to provide visual indication that the route is not only
	* hosting a session, but also that the user has ownership over said session.
	*
	* <p>This flag is ignored if {@link #FLAG_ONGOING_SESSION} is not set, or if the
	* corresponding route is not currently selected.
	*
	* <p>This flag does not affect volume adjustment (see {@link VolumeProvider}, and {@link
	* MediaRoute2Info#getVolumeHandling()}), or any aspect other than the visual representation
	* of the corresponding item.
	*/
	public static final int FLAG_ONGOING_SESSION_MANAGED = 1 << 1;

	/**
	* The corresponding route is specially likely to be selected by the user.
	*
	* <p>A UI reflecting this preference may reserve a specific space for suggested routes,
	* making it more accessible to the user. If the number of suggested routes exceeds the
	* number supported by the UI, the routes listed first in {@link
	* RouteListingPreference#getItems()} will take priority.
	*/
	public static final int FLAG_SUGGESTED = 1 << 2;

	/** @hide */
	@Retention(RetentionPolicy.SOURCE)
	@IntDef(
	prefix = {"SUBTEXT_"},
	value = {
	SUBTEXT_NONE,
	SUBTEXT_ERROR_UNKNOWN,
	SUBTEXT_SUBSCRIPTION_REQUIRED,
	SUBTEXT_DOWNLOADED_CONTENT_ROUTING_DISALLOWED,
	SUBTEXT_AD_ROUTING_DISALLOWED,
	SUBTEXT_DEVICE_LOW_POWER,
	SUBTEXT_UNAUTHORIZED,
	SUBTEXT_TRACK_UNSUPPORTED,
	SUBTEXT_CUSTOM
	})
	public @interface SubText {}

	/** The corresponding route has no associated subtext. */
	public static final int SUBTEXT_NONE = 0;
	/**
	* The corresponding route's subtext must indicate that it is not available because of an
	* unknown error.
	*/
	public static final int SUBTEXT_ERROR_UNKNOWN = 1;
	/**
	* The corresponding route's subtext must indicate that it requires a special subscription
	* in order to be available for routing.
	*/
	public static final int SUBTEXT_SUBSCRIPTION_REQUIRED = 2;
	/**
	* The corresponding route's subtext must indicate that downloaded content cannot be routed
	* to it.
	*/
	public static final int SUBTEXT_DOWNLOADED_CONTENT_ROUTING_DISALLOWED = 3;
	/**
	* The corresponding route's subtext must indicate that it is not available because an ad is
	* in progress.
	*/
	public static final int SUBTEXT_AD_ROUTING_DISALLOWED = 4;
	/**
	* The corresponding route's subtext must indicate that it is not available because the
	* device is in low-power mode.
	*/
	public static final int SUBTEXT_DEVICE_LOW_POWER = 5;
	/**
	* The corresponding route's subtext must indicate that it is not available because the user
	* is not authorized to route to it.
	*/
	public static final int SUBTEXT_UNAUTHORIZED = 6;
	/**
	* The corresponding route's subtext must indicate that it is not available because the
	* device does not support the current media track.
	*/
	public static final int SUBTEXT_TRACK_UNSUPPORTED = 7;
	/**
	* The corresponding route's subtext must be obtained from {@link
	* #getCustomSubtextMessage()}.
	*
	* <p>Applications should strongly prefer one of the other disable reasons (for the full
	* list, see {@link #getSubText()}) in order to guarantee correct localization and rendering
	* across all form factors.
	*/
	public static final int SUBTEXT_CUSTOM = 10000;

	@NonNull
	public static final Creator<Item> CREATOR =
	new Creator<>() {
	@Override
	public Item createFromParcel(Parcel in) {
	return new Item(in);
	}

	@Override
	public Item[] newArray(int size) {
	return new Item[size];
	}
	};

	@NonNull private final String mRouteId;
	@SelectionBehavior private final int mSelectionBehavior;
	@Flags private final int mFlags;
	@SubText private final int mSubText;

	@Nullable private final CharSequence mCustomSubtextMessage;

	private Item(@NonNull Builder builder) {
	mRouteId = builder.mRouteId;
	mSelectionBehavior = builder.mSelectionBehavior;
	mFlags = builder.mFlags;
	mSubText = builder.mSubText;
	mCustomSubtextMessage = builder.mCustomSubtextMessage;
	validateCustomMessageSubtext();
	}

	private Item(Parcel in) {
	mRouteId = in.readString();
	Preconditions.checkArgument(!TextUtils.isEmpty(mRouteId));
	mSelectionBehavior = in.readInt();
	mFlags = in.readInt();
	mSubText = in.readInt();
	mCustomSubtextMessage = in.readCharSequence();
	validateCustomMessageSubtext();
	}

	/**
	* Returns the id of the route that corresponds to this route listing preference item.
	*
	* @see MediaRoute2Info#getId()
	*/
	@NonNull
	public String getRouteId() {
	return mRouteId;
	}

	/**
	* Returns the behavior that the corresponding route has if the user selects it.
	*
	* @see #SELECTION_BEHAVIOR_NONE
	* @see #SELECTION_BEHAVIOR_TRANSFER
	* @see #SELECTION_BEHAVIOR_GO_TO_APP
	*/
	public int getSelectionBehavior() {
	return mSelectionBehavior;
	}

	/**
	* Returns the flags associated to the route that corresponds to this item.
	*
	* @see #FLAG_ONGOING_SESSION
	* @see #FLAG_ONGOING_SESSION_MANAGED
	* @see #FLAG_SUGGESTED
	*/
	@Flags
	public int getFlags() {
	return mFlags;
	}

	/**
	* Returns the type of subtext associated to this route.
	*
	* <p>Subtext types other than {@link #SUBTEXT_NONE} and {@link #SUBTEXT_CUSTOM} must not
	* have {@link #SELECTION_BEHAVIOR_TRANSFER}.
	*
	* <p>If this method returns {@link #SUBTEXT_CUSTOM}, then the subtext is obtained form
	* {@link #getCustomSubtextMessage()}.
	*
	* @see #SUBTEXT_NONE,
	* @see #SUBTEXT_ERROR_UNKNOWN,
	* @see #SUBTEXT_SUBSCRIPTION_REQUIRED,
	* @see #SUBTEXT_DOWNLOADED_CONTENT_ROUTING_DISALLOWED,
	* @see #SUBTEXT_AD_ROUTING_DISALLOWED,
	* @see #SUBTEXT_DEVICE_LOW_POWER,
	* @see #SUBTEXT_UNAUTHORIZED ,
	* @see #SUBTEXT_TRACK_UNSUPPORTED,
	* @see #SUBTEXT_CUSTOM
	*/
	@SubText
	public int getSubText() {
	return mSubText;
	}

	/**
	* Returns a human-readable {@link CharSequence} providing the subtext for the corresponding
	* route.
	*
	* <p>This value is ignored if the {@link #getSubText() subtext} for this item is not {@link
	* #SUBTEXT_CUSTOM}..
	*
	* <p>Applications must provide a localized message that matches the system's locale. See
	* {@link Locale#getDefault()}.
	*
	* <p>Applications should avoid using custom messages (and instead use one of non-custom
	* subtexts listed in {@link #getSubText()} in order to guarantee correct visual
	* representation and localization on all form factors.
	*/
	@Nullable
	public CharSequence getCustomSubtextMessage() {
	return mCustomSubtextMessage;
	}

	// Item Parcelable implementation.

	@Override
	public int describeContents() {
	return 0;
	}

	@Override
	public void writeToParcel(@NonNull Parcel dest, int flags) {
	dest.writeString(mRouteId);
	dest.writeInt(mSelectionBehavior);
	dest.writeInt(mFlags);
	dest.writeInt(mSubText);
	dest.writeCharSequence(mCustomSubtextMessage);
	}

	// Equals and hashCode.

	@Override
	public boolean equals(Object other) {
	if (this == other) {
	return true;
	}
	if (!(other instanceof Item)) {
	return false;
	}
	Item item = (Item) other;
	return mRouteId.equals(item.mRouteId)
	&& mSelectionBehavior == item.mSelectionBehavior
	&& mFlags == item.mFlags
	&& mSubText == item.mSubText
	&& TextUtils.equals(mCustomSubtextMessage, item.mCustomSubtextMessage);
	}

	@Override
	public int hashCode() {
	return Objects.hash(
	mRouteId, mSelectionBehavior, mFlags, mSubText, mCustomSubtextMessage);
	}

	// Internal methods.

	private void validateCustomMessageSubtext() {
	Preconditions.checkArgument(
	mSubText != SUBTEXT_CUSTOM \|\| mCustomSubtextMessage != null,
	"The custom subtext message cannot be null if subtext is SUBTEXT_CUSTOM.");
	}

	// Internal classes.

	/** Builder for {@link Item}. */
	public static final class Builder {

	private final String mRouteId;
	private int mSelectionBehavior;
	private int mFlags;
	private int mSubText;
	private CharSequence mCustomSubtextMessage;

	/**
	* Constructor.
	*
	* @param routeId See {@link Item#getRouteId()}.
	*/
	public Builder(@NonNull String routeId) {
	Preconditions.checkArgument(!TextUtils.isEmpty(routeId));
	mRouteId = routeId;
	mSelectionBehavior = SELECTION_BEHAVIOR_TRANSFER;
	mSubText = SUBTEXT_NONE;
	}

	/**
	* See {@link Item#getSelectionBehavior()}.
	*
	* <p>The default value is {@link #ACTION_TRANSFER_MEDIA}.
	*/
	@NonNull
	public Builder setSelectionBehavior(int selectionBehavior) {
	mSelectionBehavior = selectionBehavior;
	return this;
	}

	/**
	* See {@link Item#getFlags()}.
	*
	* <p>The default value is zero (no flags).
	*/
	@NonNull
	public Builder setFlags(int flags) {
	mFlags = flags;
	return this;
	}

	/**
	* See {@link Item#getSubText()}.
	*
	* <p>The default value is {@link #SUBTEXT_NONE}.
	*/
	@NonNull
	public Builder setSubText(int subText) {
	mSubText = subText;
	return this;
	}

	/**
	* See {@link Item#getCustomSubtextMessage()}.
	*
	* <p>The default value is {@code null}.
	*/
	@NonNull
	public Builder setCustomSubtextMessage(@Nullable CharSequence customSubtextMessage) {
	mCustomSubtextMessage = customSubtextMessage;
	return this;
	}

	/** Creates and returns a new {@link Item} with the given parameters. */
	@NonNull
	public Item build() {
	return new Item(this);
	}
	}
	}
	}