1 /* 2 * Copyright (C) 2022 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package android.media; 18 19 import android.annotation.IntDef; 20 import android.annotation.NonNull; 21 import android.annotation.SystemApi; 22 import android.os.Parcel; 23 import android.os.Parcelable; 24 25 import java.lang.annotation.Retention; 26 import java.lang.annotation.RetentionPolicy; 27 import java.util.Arrays; 28 import java.util.List; 29 30 /** 31 * A parcelable representing a nearby device that can be used for media transfer. 32 * <p> 33 * This class includes: 34 * <ul> 35 * <li>an ID identifying the media route.</li> 36 * <li>a range zone specifying how far away this device is from the device with the media route. 37 * </li> 38 * </ul> 39 * 40 * @hide 41 */ 42 @SystemApi 43 public final class NearbyDevice implements Parcelable { 44 /** 45 * Unknown distance range. 46 */ 47 public static final int RANGE_UNKNOWN = 0; 48 49 /** 50 * Distance is very far away from the peer device. 51 */ 52 public static final int RANGE_FAR = 1; 53 54 /** 55 * Distance is relatively long from the peer device, typically a few meters. 56 */ 57 public static final int RANGE_LONG = 2; 58 59 /** 60 * Distance is close to the peer device, typically with one or two meter. 61 */ 62 public static final int RANGE_CLOSE = 3; 63 64 /** 65 * Distance is very close to the peer device, typically within one meter or less. 66 */ 67 public static final int RANGE_WITHIN_REACH = 4; 68 69 /** 70 * The various range zones a device can be in, in relation to the current device. 71 * 72 * @hide 73 */ 74 @IntDef(prefix = {"RANGE_"}, value = { 75 RANGE_UNKNOWN, 76 RANGE_FAR, 77 RANGE_LONG, 78 RANGE_CLOSE, 79 RANGE_WITHIN_REACH 80 }) 81 @Retention(RetentionPolicy.SOURCE) 82 public @interface RangeZone { 83 } 84 85 /** 86 * Gets a human-readable string of the range zone. 87 * 88 * @hide 89 */ 90 @NonNull rangeZoneToString(@angeZone int rangeZone)91 public static String rangeZoneToString(@RangeZone int rangeZone) { 92 switch (rangeZone) { 93 case RANGE_UNKNOWN: 94 return "UNKNOWN"; 95 case RANGE_FAR: 96 return "FAR"; 97 case RANGE_LONG: 98 return "LONG"; 99 case RANGE_CLOSE: 100 return "CLOSE"; 101 case RANGE_WITHIN_REACH: 102 return "WITHIN_REACH"; 103 default: 104 return "Invalid"; 105 } 106 } 107 108 /** 109 * A list stores all the range and list from far to close, used for range comparison. 110 */ 111 private static final List<Integer> RANGE_WEIGHT_LIST = 112 Arrays.asList(RANGE_UNKNOWN, 113 RANGE_FAR, RANGE_LONG, RANGE_CLOSE, RANGE_WITHIN_REACH); 114 115 @NonNull 116 private final String mMediaRoute2Id; 117 @RangeZone 118 private final int mRangeZone; 119 120 /** Creates a device object with the given ID and range zone. */ NearbyDevice(@onNull String mediaRoute2Id, @RangeZone int rangeZone)121 public NearbyDevice(@NonNull String mediaRoute2Id, @RangeZone int rangeZone) { 122 mMediaRoute2Id = mediaRoute2Id; 123 mRangeZone = rangeZone; 124 } 125 NearbyDevice(@onNull Parcel in)126 private NearbyDevice(@NonNull Parcel in) { 127 mMediaRoute2Id = in.readString8(); 128 mRangeZone = in.readInt(); 129 } 130 131 @NonNull 132 public static final Creator<NearbyDevice> CREATOR = new Creator<NearbyDevice>() { 133 @Override 134 public NearbyDevice createFromParcel(@NonNull Parcel in) { 135 return new NearbyDevice(in); 136 } 137 138 @Override 139 public NearbyDevice[] newArray(int size) { 140 return new NearbyDevice[size]; 141 } 142 }; 143 144 /** 145 * Compares two ranges and return result. 146 * 147 * @return 0 means two ranges are the same, -1 means first range is closer, 1 means farther 148 * 149 * @hide 150 */ compareRangeZones(@angeZone int rangeZone, @RangeZone int anotherRangeZone)151 public static int compareRangeZones(@RangeZone int rangeZone, @RangeZone int anotherRangeZone) { 152 if (rangeZone == anotherRangeZone) { 153 return 0; 154 } else { 155 return RANGE_WEIGHT_LIST.indexOf(rangeZone) > RANGE_WEIGHT_LIST.indexOf( 156 anotherRangeZone) ? -1 : 1; 157 } 158 } 159 160 @Override describeContents()161 public int describeContents() { 162 return 0; 163 } 164 165 @Override toString()166 public String toString() { 167 return "NearbyDevice{mediaRoute2Id=" + mMediaRoute2Id 168 + " rangeZone=" + rangeZoneToString(mRangeZone) + "}"; 169 } 170 171 @Override writeToParcel(@onNull Parcel dest, int flags)172 public void writeToParcel(@NonNull Parcel dest, int flags) { 173 dest.writeString8(mMediaRoute2Id); 174 dest.writeInt(mRangeZone); 175 } 176 177 /** 178 * Returns the ID of the media route associated with the device. 179 * 180 * @see MediaRoute2Info#getId 181 */ 182 @NonNull getMediaRoute2Id()183 public String getMediaRoute2Id() { 184 return mMediaRoute2Id; 185 } 186 187 /** Returns the range that the device is currently in. */ 188 @RangeZone getRangeZone()189 public int getRangeZone() { 190 return mRangeZone; 191 } 192 } 193