861 lines
31 KiB
Java
861 lines
31 KiB
Java
/**
|
||
* Copyright (C) 2017 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.hardware.radio;
|
||
|
||
import android.annotation.FlaggedApi;
|
||
import android.annotation.IntDef;
|
||
import android.annotation.IntRange;
|
||
import android.annotation.NonNull;
|
||
import android.annotation.Nullable;
|
||
import android.annotation.SystemApi;
|
||
import android.os.Parcel;
|
||
import android.os.Parcelable;
|
||
|
||
import java.lang.annotation.Retention;
|
||
import java.lang.annotation.RetentionPolicy;
|
||
import java.util.ArrayList;
|
||
import java.util.Arrays;
|
||
import java.util.List;
|
||
import java.util.Objects;
|
||
import java.util.stream.Stream;
|
||
|
||
/**
|
||
* A set of identifiers necessary to tune to a given station.
|
||
*
|
||
* <p>This can hold various identifiers, like
|
||
* <ui>
|
||
* <li>AM/FM frequency</li>
|
||
* <li>HD Radio subchannel</li>
|
||
* <li>DAB channel info</li>
|
||
* </ui>
|
||
*
|
||
* <p>The primary ID uniquely identifies a station and can be used for equality
|
||
* check. The secondary IDs are supplementary and can speed up tuning process,
|
||
* but the primary ID is sufficient (ie. after a full band scan).
|
||
*
|
||
* <p>Two selectors with different secondary IDs, but the same primary ID are
|
||
* considered equal. In particular, secondary IDs vector may get updated for
|
||
* an entry on the program list (ie. when a better frequency for a given
|
||
* station is found).
|
||
*
|
||
* <p>The primaryId of a given programType MUST be of a specific type:
|
||
* <ui>
|
||
* <li>AM, FM: RDS_PI if the station broadcasts RDS, AMFM_FREQUENCY otherwise;</li>
|
||
* <li>AM_HD, FM_HD: HD_STATION_ID_EXT;</li>
|
||
* <li>DAB: DAB_SIDECC;</li>
|
||
* <li>DRMO: DRMO_SERVICE_ID;</li>
|
||
* <li>SXM: SXM_SERVICE_ID;</li>
|
||
* <li>VENDOR: VENDOR_PRIMARY.</li>
|
||
* </ui>
|
||
* @hide
|
||
*/
|
||
@SystemApi
|
||
public final class ProgramSelector implements Parcelable {
|
||
/** Invalid program type.
|
||
* @deprecated use {@link IdentifierType} instead
|
||
*/
|
||
@Deprecated
|
||
public static final int PROGRAM_TYPE_INVALID = 0;
|
||
/** Analog AM radio (with or without RDS).
|
||
* @deprecated use {@link IdentifierType} instead
|
||
*/
|
||
@Deprecated
|
||
public static final int PROGRAM_TYPE_AM = 1;
|
||
/** analog FM radio (with or without RDS).
|
||
* @deprecated use {@link IdentifierType} instead
|
||
*/
|
||
@Deprecated
|
||
public static final int PROGRAM_TYPE_FM = 2;
|
||
/** AM HD Radio.
|
||
* @deprecated use {@link Identifier} instead
|
||
*/
|
||
@Deprecated
|
||
public static final int PROGRAM_TYPE_AM_HD = 3;
|
||
/** FM HD Radio.
|
||
* @deprecated use {@link Identifier} instead
|
||
*/
|
||
@Deprecated
|
||
public static final int PROGRAM_TYPE_FM_HD = 4;
|
||
/** Digital audio broadcasting.
|
||
* @deprecated use {@link Identifier} instead
|
||
*/
|
||
@Deprecated
|
||
public static final int PROGRAM_TYPE_DAB = 5;
|
||
/** Digital Radio Mondiale.
|
||
* @deprecated use {@link Identifier} instead
|
||
*/
|
||
@Deprecated
|
||
public static final int PROGRAM_TYPE_DRMO = 6;
|
||
/** SiriusXM Satellite Radio.
|
||
* @deprecated use {@link Identifier} instead
|
||
*/
|
||
@Deprecated
|
||
public static final int PROGRAM_TYPE_SXM = 7;
|
||
/** Vendor-specific, not synced across devices.
|
||
* @deprecated use {@link Identifier} instead
|
||
*/
|
||
@Deprecated
|
||
public static final int PROGRAM_TYPE_VENDOR_START = 1000;
|
||
/** @deprecated use {@link Identifier} instead */
|
||
@Deprecated
|
||
public static final int PROGRAM_TYPE_VENDOR_END = 1999;
|
||
/**
|
||
* @deprecated use {@link Identifier} instead
|
||
* @removed mistakenly exposed previously
|
||
*/
|
||
@Deprecated
|
||
@IntDef(prefix = { "PROGRAM_TYPE_" }, value = {
|
||
PROGRAM_TYPE_INVALID,
|
||
PROGRAM_TYPE_AM,
|
||
PROGRAM_TYPE_FM,
|
||
PROGRAM_TYPE_AM_HD,
|
||
PROGRAM_TYPE_FM_HD,
|
||
PROGRAM_TYPE_DAB,
|
||
PROGRAM_TYPE_DRMO,
|
||
PROGRAM_TYPE_SXM,
|
||
})
|
||
@IntRange(from = PROGRAM_TYPE_VENDOR_START, to = PROGRAM_TYPE_VENDOR_END)
|
||
@Retention(RetentionPolicy.SOURCE)
|
||
public @interface ProgramType {}
|
||
|
||
/**
|
||
* Bitmask for HD radio subchannel 1
|
||
*
|
||
* <p>There are at most 8 HD radio subchannels of 1-based om HD radio standard. It is
|
||
* converted to 0-based index. 0 is the index of main program service (MPS). 1 to 7 are
|
||
* indexes of additional supplemental program services (SPS).
|
||
*/
|
||
@FlaggedApi(Flags.FLAG_HD_RADIO_IMPROVED)
|
||
public static final int SUB_CHANNEL_HD_1 = 1 << 0;
|
||
|
||
/**
|
||
* Bitmask for HD radio subchannel 2
|
||
*
|
||
* <p>For further reference, see {@link #SUB_CHANNEL_HD_1}
|
||
*/
|
||
@FlaggedApi(Flags.FLAG_HD_RADIO_IMPROVED)
|
||
public static final int SUB_CHANNEL_HD_2 = 1 << 1;
|
||
|
||
/**
|
||
* Bitmask for HD radio subchannel 3
|
||
*
|
||
* <p>For further reference, see {@link #SUB_CHANNEL_HD_1}
|
||
*/
|
||
@FlaggedApi(Flags.FLAG_HD_RADIO_IMPROVED)
|
||
public static final int SUB_CHANNEL_HD_3 = 1 << 2;
|
||
|
||
/**
|
||
* Bitmask for HD radio subchannel 4
|
||
*
|
||
* <p>For further reference, see {@link #SUB_CHANNEL_HD_1}
|
||
*/
|
||
@FlaggedApi(Flags.FLAG_HD_RADIO_IMPROVED)
|
||
public static final int SUB_CHANNEL_HD_4 = 1 << 3;
|
||
|
||
/**
|
||
* Bitmask for HD radio subchannel 5
|
||
*
|
||
* <p>For further reference, see {@link #SUB_CHANNEL_HD_1}
|
||
*/
|
||
@FlaggedApi(Flags.FLAG_HD_RADIO_IMPROVED)
|
||
public static final int SUB_CHANNEL_HD_5 = 1 << 4;
|
||
|
||
/**
|
||
* Bitmask for HD radio subchannel 6
|
||
*
|
||
* <p>For further reference, see {@link #SUB_CHANNEL_HD_1}
|
||
*/
|
||
@FlaggedApi(Flags.FLAG_HD_RADIO_IMPROVED)
|
||
public static final int SUB_CHANNEL_HD_6 = 1 << 5;
|
||
|
||
/**
|
||
* Bitmask for HD radio subchannel 7
|
||
*
|
||
* <p>For further reference, see {@link #SUB_CHANNEL_HD_1}
|
||
*/
|
||
@FlaggedApi(Flags.FLAG_HD_RADIO_IMPROVED)
|
||
public static final int SUB_CHANNEL_HD_7 = 1 << 6;
|
||
|
||
/**
|
||
* Bitmask for HD radio subchannel 8
|
||
*
|
||
* <p>For further reference, see {@link #SUB_CHANNEL_HD_1}
|
||
*/
|
||
@FlaggedApi(Flags.FLAG_HD_RADIO_IMPROVED)
|
||
public static final int SUB_CHANNEL_HD_8 = 1 << 7;
|
||
|
||
/** @hide */
|
||
@IntDef(prefix = { "SUB_CHANNEL_HD_" }, value = {
|
||
SUB_CHANNEL_HD_1,
|
||
SUB_CHANNEL_HD_2,
|
||
SUB_CHANNEL_HD_3,
|
||
SUB_CHANNEL_HD_4,
|
||
SUB_CHANNEL_HD_5,
|
||
SUB_CHANNEL_HD_6,
|
||
SUB_CHANNEL_HD_7,
|
||
SUB_CHANNEL_HD_8,
|
||
})
|
||
@Retention(RetentionPolicy.SOURCE)
|
||
public @interface HdSubChannel {}
|
||
|
||
public static final int IDENTIFIER_TYPE_INVALID = 0;
|
||
/**
|
||
* Primary identifier for analog (without RDS) AM/FM stations:
|
||
* frequency in kHz.
|
||
*
|
||
* <p>This identifier also contains band information:
|
||
* <li>
|
||
* <ul><500kHz: AM LW.
|
||
* <ul>500kHz - 1705kHz: AM MW.
|
||
* <ul>1.71MHz - 30MHz: AM SW.
|
||
* <ul>>60MHz: FM.
|
||
* </li>
|
||
*/
|
||
public static final int IDENTIFIER_TYPE_AMFM_FREQUENCY = 1;
|
||
/**
|
||
* 16bit primary identifier for FM RDS station.
|
||
*/
|
||
public static final int IDENTIFIER_TYPE_RDS_PI = 2;
|
||
/**
|
||
* 64bit compound primary identifier for HD Radio.
|
||
*
|
||
* <p>Consists of (from the LSB):
|
||
* <li>
|
||
* <ul>32bit: Station ID number.</ul>
|
||
* <ul>4bit: HD subchannel, see {@link #SUB_CHANNEL_HD_1}.</ul>
|
||
* <ul>18bit: AMFM_FREQUENCY.</ul>
|
||
* </li>
|
||
*
|
||
* <p>While station ID number should be unique globally, it sometimes gets
|
||
* abused by broadcasters (i.e. not being set at all). To ensure local
|
||
* uniqueness, AMFM_FREQUENCY_KHZ was added here. Global uniqueness is
|
||
* a best-effort - see {@link #IDENTIFIER_TYPE_HD_STATION_NAME}.
|
||
*
|
||
* <p>The remaining bits should be set to zeros when writing on the chip side
|
||
* and ignored when read.
|
||
*/
|
||
public static final int IDENTIFIER_TYPE_HD_STATION_ID_EXT = 3;
|
||
/**
|
||
* HD Radio subchannel - a value in range of 0-7.
|
||
*
|
||
* <p>The subchannel index is 0-based (where 0 is MPS and 1..7 are SPS),
|
||
* as opposed to HD Radio standard (where it's 1-based).
|
||
*
|
||
* @deprecated use IDENTIFIER_TYPE_HD_STATION_ID_EXT instead
|
||
*/
|
||
@Deprecated
|
||
public static final int IDENTIFIER_TYPE_HD_SUBCHANNEL = 4;
|
||
/**
|
||
* 64bit additional identifier for HD Radio.
|
||
*
|
||
* <p>Due to Station ID abuse, some {@link #IDENTIFIER_TYPE_HD_STATION_ID_EXT}
|
||
* identifiers may be not globally unique. To provide a best-effort solution, a
|
||
* short version of station name may be carried as additional identifier and
|
||
* may be used by the tuner hardware to double-check tuning.
|
||
*
|
||
* <p>The name is limited to the first 8 A-Z0-9 characters (lowercase
|
||
* letters must be converted to uppercase). Encoded in little-endian
|
||
* ASCII: the first character of the name is the LSB.
|
||
*
|
||
* <p>For example: "Abc" is encoded as 0x434241.
|
||
*/
|
||
public static final int IDENTIFIER_TYPE_HD_STATION_NAME = 10004;
|
||
/**
|
||
* @see #IDENTIFIER_TYPE_DAB_SID_EXT
|
||
*
|
||
* @deprecated use {@link #IDENTIFIER_TYPE_DAB_DMB_SID_EXT} instead
|
||
*/
|
||
@Deprecated
|
||
public static final int IDENTIFIER_TYPE_DAB_SIDECC = 5;
|
||
/**
|
||
* 28bit compound primary identifier for Digital Audio Broadcasting.
|
||
*
|
||
* <p>Consists of (from the LSB):
|
||
* <li>
|
||
* <ul>16bit: SId.</ul>
|
||
* <ul>8bit: ECC code.</ul>
|
||
* <ul>4bit: SCIdS.</ul>
|
||
* </li>
|
||
*
|
||
* <p>SCIdS (Service Component Identifier within the Service) value
|
||
* of 0 represents the main service, while 1 and above represents
|
||
* secondary services.
|
||
*
|
||
* <p>The remaining bits should be set to zeros when writing on the chip
|
||
* side and ignored when read.
|
||
*
|
||
* @deprecated use {@link #IDENTIFIER_TYPE_DAB_DMB_SID_EXT} instead
|
||
*/
|
||
@Deprecated
|
||
public static final int IDENTIFIER_TYPE_DAB_SID_EXT = IDENTIFIER_TYPE_DAB_SIDECC;
|
||
/** 16bit */
|
||
public static final int IDENTIFIER_TYPE_DAB_ENSEMBLE = 6;
|
||
/** 12bit */
|
||
public static final int IDENTIFIER_TYPE_DAB_SCID = 7;
|
||
/** kHz */
|
||
public static final int IDENTIFIER_TYPE_DAB_FREQUENCY = 8;
|
||
/**
|
||
* 24bit primary identifier for Digital Radio Mondiale.
|
||
*/
|
||
public static final int IDENTIFIER_TYPE_DRMO_SERVICE_ID = 9;
|
||
/** kHz */
|
||
public static final int IDENTIFIER_TYPE_DRMO_FREQUENCY = 10;
|
||
/**
|
||
* 1: AM, 2:FM
|
||
* @deprecated use {@link #IDENTIFIER_TYPE_DRMO_FREQUENCY} instead
|
||
*/
|
||
@Deprecated
|
||
public static final int IDENTIFIER_TYPE_DRMO_MODULATION = 11;
|
||
/**
|
||
* 32bit primary identifier for SiriusXM Satellite Radio.
|
||
*
|
||
* @deprecated SiriusXM Satellite Radio is not supported
|
||
*/
|
||
@Deprecated
|
||
public static final int IDENTIFIER_TYPE_SXM_SERVICE_ID = 12;
|
||
/**
|
||
* 0-999 range
|
||
*
|
||
* @deprecated SiriusXM Satellite Radio is not supported
|
||
*/
|
||
@Deprecated
|
||
public static final int IDENTIFIER_TYPE_SXM_CHANNEL = 13;
|
||
/**
|
||
* 44bit compound primary identifier for Digital Audio Broadcasting and
|
||
* Digital Multimedia Broadcasting.
|
||
*
|
||
* <p>Consists of (from the LSB):
|
||
* <li>
|
||
* <ul>32bit: SId;</ul>
|
||
* <ul>8bit: ECC code;</ul>
|
||
* <ul>4bit: SCIdS.</ul>
|
||
* </li>
|
||
*
|
||
* <p>SCIdS (Service Component Identifier within the Service) value
|
||
* of 0 represents the main service, while 1 and above represents
|
||
* secondary services.
|
||
*
|
||
* <p>The remaining bits should be set to zeros when writing on the chip
|
||
* side and ignored when read.
|
||
*/
|
||
public static final int IDENTIFIER_TYPE_DAB_DMB_SID_EXT = 14;
|
||
/**
|
||
* 64bit additional identifier for HD Radio representing station location.
|
||
*
|
||
* <p>Consists of (from the LSB):
|
||
* <li>
|
||
* <ul>4 bit: Bits 0:3 of altitude</ul>
|
||
* <ul>13 bit: Fractional bits of longitude</ul>
|
||
* <ul>8 bit: Integer bits of longitude</ul>
|
||
* <ul>1 bit: 0 for east and 1 for west for longitude</ul>
|
||
* <ul>1 bit: 0, representing longitude</ul>
|
||
* <ul>5 bit: pad of zeros separating longitude and latitude</ul>
|
||
* <ul>4 bit: Bits 4:7 of altitude</ul>
|
||
* <ul>13 bit: Fractional bits of latitude</ul>
|
||
* <ul>8 bit: Integer bits of latitude</ul>
|
||
* <ul>1 bit: 0 for north and 1 for south for latitude</ul>
|
||
* <ul>1 bit: 1, representing latitude</ul>
|
||
* <ul>5 bit: pad of zeros</ul>
|
||
* </li>
|
||
*
|
||
* <p>This format is defined in NRSC-5-C document: SY_IDD_1020s.
|
||
*
|
||
* <p>Due to Station ID abuse, some
|
||
* {@link #IDENTIFIER_TYPE_HD_STATION_ID_EXT} identifiers may be not
|
||
* globally unique. To provide a best-effort solution, the station’s
|
||
* broadcast antenna containing the latitude and longitude may be
|
||
* carried as additional identifier and may be used by the tuner hardware
|
||
* to double-check tuning.
|
||
*/
|
||
@FlaggedApi(Flags.FLAG_HD_RADIO_IMPROVED)
|
||
public static final int IDENTIFIER_TYPE_HD_STATION_LOCATION = 15;
|
||
/**
|
||
* Primary identifier for vendor-specific radio technology.
|
||
* The value format is determined by a vendor.
|
||
*
|
||
* <p>It must not be used in any other programType than corresponding VENDOR
|
||
* type between VENDOR_START and VENDOR_END (e.g. identifier type 1015 must
|
||
* not be used in any program type other than 1015).
|
||
*/
|
||
public static final int IDENTIFIER_TYPE_VENDOR_START = PROGRAM_TYPE_VENDOR_START;
|
||
/**
|
||
* @see #IDENTIFIER_TYPE_VENDOR_START
|
||
*/
|
||
public static final int IDENTIFIER_TYPE_VENDOR_END = PROGRAM_TYPE_VENDOR_END;
|
||
/**
|
||
* @deprecated use {@link #IDENTIFIER_TYPE_VENDOR_START} instead
|
||
*/
|
||
@Deprecated
|
||
public static final int IDENTIFIER_TYPE_VENDOR_PRIMARY_START = IDENTIFIER_TYPE_VENDOR_START;
|
||
/**
|
||
* @deprecated use {@link #IDENTIFIER_TYPE_VENDOR_END} instead
|
||
*/
|
||
@Deprecated
|
||
public static final int IDENTIFIER_TYPE_VENDOR_PRIMARY_END = IDENTIFIER_TYPE_VENDOR_END;
|
||
/** @removed mistakenly exposed previously */
|
||
@IntDef(prefix = { "IDENTIFIER_TYPE_" }, value = {
|
||
IDENTIFIER_TYPE_INVALID,
|
||
IDENTIFIER_TYPE_AMFM_FREQUENCY,
|
||
IDENTIFIER_TYPE_RDS_PI,
|
||
IDENTIFIER_TYPE_HD_STATION_ID_EXT,
|
||
IDENTIFIER_TYPE_HD_SUBCHANNEL,
|
||
IDENTIFIER_TYPE_HD_STATION_NAME,
|
||
IDENTIFIER_TYPE_DAB_SID_EXT,
|
||
IDENTIFIER_TYPE_DAB_SIDECC,
|
||
IDENTIFIER_TYPE_DAB_ENSEMBLE,
|
||
IDENTIFIER_TYPE_DAB_SCID,
|
||
IDENTIFIER_TYPE_DAB_FREQUENCY,
|
||
IDENTIFIER_TYPE_DRMO_SERVICE_ID,
|
||
IDENTIFIER_TYPE_DRMO_FREQUENCY,
|
||
IDENTIFIER_TYPE_DRMO_MODULATION,
|
||
IDENTIFIER_TYPE_SXM_SERVICE_ID,
|
||
IDENTIFIER_TYPE_SXM_CHANNEL,
|
||
IDENTIFIER_TYPE_DAB_DMB_SID_EXT,
|
||
IDENTIFIER_TYPE_HD_STATION_LOCATION,
|
||
})
|
||
@IntRange(from = IDENTIFIER_TYPE_VENDOR_START, to = IDENTIFIER_TYPE_VENDOR_END)
|
||
@Retention(RetentionPolicy.SOURCE)
|
||
public @interface IdentifierType {}
|
||
|
||
private final @ProgramType int mProgramType;
|
||
private final @NonNull Identifier mPrimaryId;
|
||
private final @NonNull Identifier[] mSecondaryIds;
|
||
private final @NonNull long[] mVendorIds;
|
||
|
||
/**
|
||
* Constructor for ProgramSelector.
|
||
*
|
||
* <p>It's not desired to modify selector objects, so all its fields are initialized at
|
||
* creation.
|
||
*
|
||
* <p>Identifier lists must not contain any nulls, but can itself be null to be interpreted
|
||
* as empty list at object creation.
|
||
*
|
||
* @param programType type of a radio technology.
|
||
* @param primaryId primary program identifier.
|
||
* @param secondaryIds list of secondary program identifiers.
|
||
* @param vendorIds list of vendor-specific program identifiers.
|
||
*/
|
||
public ProgramSelector(@ProgramType int programType, @NonNull Identifier primaryId,
|
||
@Nullable Identifier[] secondaryIds, @Nullable long[] vendorIds) {
|
||
if (secondaryIds == null) secondaryIds = new Identifier[0];
|
||
if (vendorIds == null) vendorIds = new long[0];
|
||
if (Stream.of(secondaryIds).anyMatch(id -> id == null)) {
|
||
throw new IllegalArgumentException("secondaryIds list must not contain nulls");
|
||
}
|
||
mProgramType = programType;
|
||
mPrimaryId = Objects.requireNonNull(primaryId);
|
||
mSecondaryIds = secondaryIds;
|
||
mVendorIds = vendorIds;
|
||
}
|
||
|
||
/**
|
||
* Type of a radio technology.
|
||
*
|
||
* @return program type.
|
||
* @deprecated use {@link #getPrimaryId} instead
|
||
*/
|
||
@Deprecated
|
||
public @ProgramType int getProgramType() {
|
||
return mProgramType;
|
||
}
|
||
|
||
/**
|
||
* Primary program identifier uniquely identifies a station and is used to
|
||
* determine equality between two ProgramSelectors.
|
||
*
|
||
* @return primary identifier.
|
||
*/
|
||
public @NonNull Identifier getPrimaryId() {
|
||
return mPrimaryId;
|
||
}
|
||
|
||
/**
|
||
* Secondary program identifier is not required for tuning, but may make it
|
||
* faster or more reliable.
|
||
*
|
||
* @return secondary identifier list, must not be modified.
|
||
*/
|
||
public @NonNull Identifier[] getSecondaryIds() {
|
||
return mSecondaryIds;
|
||
}
|
||
|
||
/**
|
||
* Looks up an identifier of a given type (either primary or secondary).
|
||
*
|
||
* <p>If there are multiple identifiers if a given type, then first in order (where primary id
|
||
* is before any secondary) is selected.
|
||
*
|
||
* @param type type of identifier.
|
||
* @return identifier value, if found.
|
||
* @throws IllegalArgumentException, if not found.
|
||
*/
|
||
public long getFirstId(@IdentifierType int type) {
|
||
if (mPrimaryId.getType() == type) return mPrimaryId.getValue();
|
||
for (Identifier id : mSecondaryIds) {
|
||
if (id.getType() == type) return id.getValue();
|
||
}
|
||
throw new IllegalArgumentException("Identifier " + type + " not found");
|
||
}
|
||
|
||
/**
|
||
* Looks up all identifier of a given type (either primary or secondary).
|
||
*
|
||
* <p>Some identifiers may be provided multiple times, for example
|
||
* {@link #IDENTIFIER_TYPE_AMFM_FREQUENCY} for FM Alternate Frequencies.
|
||
*
|
||
* @param type type of identifier.
|
||
* @return an array of identifiers, generated on each call. May be modified.
|
||
*/
|
||
public @NonNull Identifier[] getAllIds(@IdentifierType int type) {
|
||
List<Identifier> out = new ArrayList<>();
|
||
|
||
if (mPrimaryId.getType() == type) out.add(mPrimaryId);
|
||
for (Identifier id : mSecondaryIds) {
|
||
if (id.getType() == type) out.add(id);
|
||
}
|
||
|
||
return out.toArray(new Identifier[out.size()]);
|
||
}
|
||
|
||
/**
|
||
* Vendor identifiers are passed as-is to the HAL implementation,
|
||
* preserving elements order.
|
||
*
|
||
* @return an array of vendor identifiers, must not be modified.
|
||
* @deprecated for HAL 1.x compatibility;
|
||
* HAL 2.x uses standard primary/secondary lists for vendor IDs
|
||
*/
|
||
@Deprecated
|
||
public @NonNull long[] getVendorIds() {
|
||
return mVendorIds;
|
||
}
|
||
|
||
/**
|
||
* Creates an equivalent ProgramSelector with a given secondary identifier preferred.
|
||
*
|
||
* <p>Used to point to a specific physical identifier for technologies that may broadcast the
|
||
* same program on different channels. For example, with a DAB program broadcasted over multiple
|
||
* ensembles, the radio hardware may select the one with the strongest signal. The UI may select
|
||
* preferred ensemble though, so the radio hardware may try to use it in the first place.
|
||
*
|
||
* <p>This is a best-effort hint for the tuner, not a guaranteed behavior.
|
||
*
|
||
* <p>Setting the given secondary identifier as preferred means filtering out other secondary
|
||
* identifiers of its type and adding it to the list.
|
||
*
|
||
* @param preferred preferred secondary identifier
|
||
* @return a new ProgramSelector with a given secondary identifier preferred
|
||
*/
|
||
public @NonNull ProgramSelector withSecondaryPreferred(@NonNull Identifier preferred) {
|
||
int preferredType = preferred.getType();
|
||
Identifier[] secondaryIds = Stream.concat(
|
||
// remove other identifiers of that type
|
||
Arrays.stream(mSecondaryIds).filter(id -> id.getType() != preferredType),
|
||
// add preferred identifier instead
|
||
Stream.of(preferred)).toArray(Identifier[]::new);
|
||
|
||
return new ProgramSelector(
|
||
mProgramType,
|
||
mPrimaryId,
|
||
secondaryIds,
|
||
mVendorIds
|
||
);
|
||
}
|
||
|
||
/**
|
||
* Builds new ProgramSelector for AM/FM frequency.
|
||
*
|
||
* @param band the band.
|
||
* @param frequencyKhz the frequency in kHz.
|
||
* @return new {@link ProgramSelector} object representing given frequency.
|
||
* @throws IllegalArgumentException if provided frequency is out of bounds.
|
||
*/
|
||
public static @NonNull ProgramSelector createAmFmSelector(
|
||
@RadioManager.Band int band, int frequencyKhz) {
|
||
return createAmFmSelector(band, frequencyKhz, 0);
|
||
}
|
||
|
||
/**
|
||
* Checks, if a given AM/FM frequency is roughly valid and in correct unit.
|
||
*
|
||
* <p>It does not check the range precisely: it may provide false positives, but not false
|
||
* negatives. In particular, it may be way off for certain regions.
|
||
* The main purpose is to avoid passing improper units, ie. MHz instead of kHz.
|
||
*
|
||
* @param isAm true, if AM, false if FM.
|
||
* @param frequencyKhz the frequency in kHz.
|
||
* @return true, if the frequency is roughly valid.
|
||
*/
|
||
private static boolean isValidAmFmFrequency(boolean isAm, int frequencyKhz) {
|
||
if (isAm) {
|
||
return frequencyKhz > 150 && frequencyKhz <= 30000;
|
||
} else {
|
||
return frequencyKhz > 60000 && frequencyKhz < 110000;
|
||
}
|
||
}
|
||
|
||
/**
|
||
* Builds new ProgramSelector for AM/FM frequency.
|
||
*
|
||
* <p>This method variant supports HD Radio subchannels, but it's undesirable to
|
||
* select them manually. Instead, the value should be retrieved from program list.
|
||
*
|
||
* @param band the band.
|
||
* @param frequencyKhz the frequency in kHz.
|
||
* @param subChannel 1-based HD Radio subchannel.
|
||
* @return new ProgramSelector object representing given frequency.
|
||
* @throws IllegalArgumentException if provided frequency is out of bounds,
|
||
* or tried setting a subchannel for analog AM/FM.
|
||
*/
|
||
public static @NonNull ProgramSelector createAmFmSelector(
|
||
@RadioManager.Band int band, int frequencyKhz, int subChannel) {
|
||
if (band == RadioManager.BAND_INVALID) {
|
||
// 50MHz is a rough boundary between AM (<30MHz) and FM (>60MHz).
|
||
if (frequencyKhz < 50000) {
|
||
band = (subChannel <= 0) ? RadioManager.BAND_AM : RadioManager.BAND_AM_HD;
|
||
} else {
|
||
band = (subChannel <= 0) ? RadioManager.BAND_FM : RadioManager.BAND_FM_HD;
|
||
}
|
||
}
|
||
|
||
boolean isAm = (band == RadioManager.BAND_AM || band == RadioManager.BAND_AM_HD);
|
||
boolean isDigital = (band == RadioManager.BAND_AM_HD || band == RadioManager.BAND_FM_HD);
|
||
if (!isAm && !isDigital && band != RadioManager.BAND_FM) {
|
||
throw new IllegalArgumentException("Unknown band: " + band);
|
||
}
|
||
if (subChannel < 0 || subChannel > 8) {
|
||
throw new IllegalArgumentException("Invalid subchannel: " + subChannel);
|
||
}
|
||
if (subChannel > 0 && !isDigital) {
|
||
throw new IllegalArgumentException("Subchannels are not supported for non-HD radio");
|
||
}
|
||
if (!isValidAmFmFrequency(isAm, frequencyKhz)) {
|
||
throw new IllegalArgumentException("Provided value is not a valid AM/FM frequency: "
|
||
+ frequencyKhz);
|
||
}
|
||
|
||
// We can't use AM_HD or FM_HD, because we don't know HD station ID.
|
||
@ProgramType int programType = isAm ? PROGRAM_TYPE_AM : PROGRAM_TYPE_FM;
|
||
Identifier primary = new Identifier(IDENTIFIER_TYPE_AMFM_FREQUENCY, frequencyKhz);
|
||
|
||
Identifier[] secondary = null;
|
||
if (subChannel > 0) {
|
||
/* Stating sub channel for non-HD AM/FM does not give any guarantees,
|
||
* but we can't do much more without HD station ID.
|
||
*
|
||
* The legacy APIs had 1-based subChannels, while ProgramSelector is 0-based.
|
||
*/
|
||
secondary = new Identifier[]{
|
||
new Identifier(IDENTIFIER_TYPE_HD_SUBCHANNEL, subChannel - 1)};
|
||
}
|
||
|
||
return new ProgramSelector(programType, primary, secondary, null);
|
||
}
|
||
|
||
@NonNull
|
||
@Override
|
||
public String toString() {
|
||
StringBuilder sb = new StringBuilder("ProgramSelector(type=").append(mProgramType)
|
||
.append(", primary=").append(mPrimaryId);
|
||
if (mSecondaryIds.length > 0) {
|
||
sb.append(", secondary=").append(Arrays.toString(mSecondaryIds));
|
||
}
|
||
if (mVendorIds.length > 0) {
|
||
sb.append(", vendor=").append(Arrays.toString(mVendorIds));
|
||
}
|
||
sb.append(")");
|
||
return sb.toString();
|
||
}
|
||
|
||
@Override
|
||
public int hashCode() {
|
||
// secondaryIds and vendorIds are ignored for equality/hashing
|
||
return mPrimaryId.hashCode();
|
||
}
|
||
|
||
@Override
|
||
public boolean equals(@Nullable Object obj) {
|
||
if (this == obj) return true;
|
||
if (!(obj instanceof ProgramSelector)) return false;
|
||
ProgramSelector other = (ProgramSelector) obj;
|
||
// secondaryIds and vendorIds are ignored for equality/hashing
|
||
// programType can be inferred from primaryId, thus not checked
|
||
return mPrimaryId.equals(other.getPrimaryId());
|
||
}
|
||
|
||
/** @hide */
|
||
public boolean strictEquals(@Nullable Object obj) {
|
||
if (this == obj) return true;
|
||
if (!(obj instanceof ProgramSelector)) return false;
|
||
ProgramSelector other = (ProgramSelector) obj;
|
||
// vendorIds are ignored for equality
|
||
// programType can be inferred from primaryId, thus not checked
|
||
return mPrimaryId.equals(other.getPrimaryId())
|
||
&& mSecondaryIds.length == other.mSecondaryIds.length
|
||
&& Arrays.asList(mSecondaryIds).containsAll(
|
||
Arrays.asList(other.mSecondaryIds));
|
||
}
|
||
|
||
private ProgramSelector(Parcel in) {
|
||
mProgramType = in.readInt();
|
||
mPrimaryId = in.readTypedObject(Identifier.CREATOR);
|
||
mSecondaryIds = in.createTypedArray(Identifier.CREATOR);
|
||
if (Stream.of(mSecondaryIds).anyMatch(id -> id == null)) {
|
||
throw new IllegalArgumentException("secondaryIds list must not contain nulls");
|
||
}
|
||
mVendorIds = in.createLongArray();
|
||
}
|
||
|
||
@Override
|
||
public void writeToParcel(Parcel dest, int flags) {
|
||
dest.writeInt(mProgramType);
|
||
dest.writeTypedObject(mPrimaryId, 0);
|
||
dest.writeTypedArray(mSecondaryIds, 0);
|
||
dest.writeLongArray(mVendorIds);
|
||
}
|
||
|
||
@Override
|
||
public int describeContents() {
|
||
return 0;
|
||
}
|
||
|
||
public static final @android.annotation.NonNull Parcelable.Creator<ProgramSelector> CREATOR =
|
||
new Parcelable.Creator<ProgramSelector>() {
|
||
public ProgramSelector createFromParcel(Parcel in) {
|
||
return new ProgramSelector(in);
|
||
}
|
||
|
||
public ProgramSelector[] newArray(int size) {
|
||
return new ProgramSelector[size];
|
||
}
|
||
};
|
||
|
||
/**
|
||
* A single program identifier component, e.g. frequency or channel ID.
|
||
*
|
||
* <p>The long value field holds the value in format described in comments for
|
||
* IdentifierType constants.
|
||
*/
|
||
public static final class Identifier implements Parcelable {
|
||
private final @IdentifierType int mType;
|
||
private final long mValue;
|
||
|
||
public Identifier(@IdentifierType int type, long value) {
|
||
if (type == IDENTIFIER_TYPE_HD_STATION_NAME) {
|
||
// see getType
|
||
type = IDENTIFIER_TYPE_HD_SUBCHANNEL;
|
||
}
|
||
mType = type;
|
||
mValue = value;
|
||
}
|
||
|
||
/**
|
||
* Type of an identifier.
|
||
*
|
||
* @return type of an identifier.
|
||
*/
|
||
public @IdentifierType int getType() {
|
||
if (mType == IDENTIFIER_TYPE_HD_SUBCHANNEL && mValue > 10) {
|
||
/* HD_SUBCHANNEL and HD_STATION_NAME use the same identifier type, but they differ
|
||
* in possible values: sub channel is 0-7, station name is greater than ASCII space
|
||
* code (32).
|
||
*/
|
||
return IDENTIFIER_TYPE_HD_STATION_NAME;
|
||
}
|
||
return mType;
|
||
}
|
||
|
||
/**
|
||
* Returns whether this identifier's type is considered a category when filtering
|
||
* ProgramLists for category entries.
|
||
*
|
||
* @see ProgramList.Filter#areCategoriesIncluded
|
||
* @return False if this identifier's type is not tunable (e.g. DAB ensemble or
|
||
* vendor-specified type). True otherwise.
|
||
*/
|
||
public boolean isCategoryType() {
|
||
return (mType >= IDENTIFIER_TYPE_VENDOR_START && mType <= IDENTIFIER_TYPE_VENDOR_END)
|
||
|| mType == IDENTIFIER_TYPE_DAB_ENSEMBLE;
|
||
}
|
||
|
||
/**
|
||
* Value of an identifier.
|
||
*
|
||
* <p>Its meaning depends on identifier type, ie. for
|
||
* {@link #IDENTIFIER_TYPE_AMFM_FREQUENCY} type, the value is a frequency in kHz.
|
||
*
|
||
* <p>The range of a value depends on its type; it does not always require the whole long
|
||
* range. Casting to necessary type (ie. int) without range checking is correct in front-end
|
||
* code - any range violations are either errors in the framework or in the
|
||
* HAL implementation. For example, {@link #IDENTIFIER_TYPE_AMFM_FREQUENCY} always fits in
|
||
* int, as {@link Integer#MAX_VALUE} would mean 2.1THz.
|
||
*
|
||
* @return value of an identifier.
|
||
*/
|
||
public long getValue() {
|
||
return mValue;
|
||
}
|
||
|
||
@NonNull
|
||
@Override
|
||
public String toString() {
|
||
return "Identifier(" + mType + ", " + mValue + ")";
|
||
}
|
||
|
||
@Override
|
||
public int hashCode() {
|
||
return Objects.hash(mType, mValue);
|
||
}
|
||
|
||
@Override
|
||
public boolean equals(@Nullable Object obj) {
|
||
if (this == obj) return true;
|
||
if (!(obj instanceof Identifier)) return false;
|
||
Identifier other = (Identifier) obj;
|
||
return other.getType() == mType && other.getValue() == mValue;
|
||
}
|
||
|
||
private Identifier(Parcel in) {
|
||
mType = in.readInt();
|
||
mValue = in.readLong();
|
||
}
|
||
|
||
@Override
|
||
public void writeToParcel(Parcel dest, int flags) {
|
||
dest.writeInt(mType);
|
||
dest.writeLong(mValue);
|
||
}
|
||
|
||
@Override
|
||
public int describeContents() {
|
||
return 0;
|
||
}
|
||
|
||
public static final @android.annotation.NonNull Parcelable.Creator<Identifier> CREATOR =
|
||
new Parcelable.Creator<Identifier>() {
|
||
public Identifier createFromParcel(Parcel in) {
|
||
return new Identifier(in);
|
||
}
|
||
|
||
public Identifier[] newArray(int size) {
|
||
return new Identifier[size];
|
||
}
|
||
};
|
||
}
|
||
}
|