/**
 * 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];
            }
        };
    }
}