Merge "Fix javadoc in broadcast radio service and API" into main

        /**

         * An event called whenever a list of active announcements change.

         *

         * The entire list is sent each time a new announcement appears or any ends broadcasting.

         * <p>The entire list is sent each time a new announcement appears or any ends broadcasting.

         *

         * @param activeAnnouncements a full list of active announcements

         */

        /**

         * Constructor of program list filter.

         *

         * Arrays passed to this constructor become owned by this object, do not modify them later.

         * <p>Arrays passed to this constructor will be owned by this object, do not modify them.

         *

         * @param identifierTypes see getIdentifierTypes()

         * @param identifiers see getIdentifiers()

        /**

         * Returns the list of identifier types that satisfy the filter.

         *

         * If the program list entry contains at least one identifier of the type

         * listed, it satisfies this condition.

         * <p>If the program list entry contains at least one identifier of the type

         * listed, it satisfies this condition. Empty list means no filtering on

         * identifier type.

         *

         * Empty list means no filtering on identifier type.

         *

         * @return the list of accepted identifier types, must not be modified

         * @return the set of accepted identifier types, must not be modified

         */

        public @NonNull Set<Integer> getIdentifierTypes() {

            return mIdentifierTypes;

        /**

         * Returns the list of identifiers that satisfy the filter.

         *

         * If the program list entry contains at least one listed identifier,

         * it satisfies this condition.

         *

         * Empty list means no filtering on identifier.

         * <p>If the program list entry contains at least one listed identifier,

         * it satisfies this condition. Empty list means no filtering on identifier.

         *

         * @return the list of accepted identifiers, must not be modified

         * @return the set of accepted identifiers, must not be modified

         */

        public @NonNull Set<ProgramSelector.Identifier> getIdentifiers() {

            return mIdentifiers;

        /**

         * Checks, if updates on entry modifications should be disabled.

         *

         * If true, 'modified' vector of ProgramListChunk must contain list

         * <p>If true, 'modified' vector of ProgramListChunk must contain list

         * additions only. Once the program is added to the list, it's not

         * updated anymore.

         */

/**

 * A set of identifiers necessary to tune to a given station.

 *

 * This can hold various identifiers, like

 * - AM/FM frequency

 * - HD Radio subchannel

 * - DAB channel info

 *

 * The primary ID uniquely identifies a station and can be used for equality

 * <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).

 *

 * Two selectors with different secondary IDs, but the same primary ID are

 * <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).

 *

 * The primaryId of a given programType MUST be of a specific type:

 * - AM, FM: RDS_PI if the station broadcasts RDS, AMFM_FREQUENCY otherwise;

 * - AM_HD, FM_HD: HD_STATION_ID_EXT;

 * - DAB: DAB_SIDECC;

 * - DRMO: DRMO_SERVICE_ID;

 * - SXM: SXM_SERVICE_ID;

 * - VENDOR: VENDOR_PRIMARY.

 * <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

    /**

     * 64bit additional identifier for HD Radio.

     *

     * <p>Due to Station ID abuse, some 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>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

     * 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 (eg. identifier type 1015 must

     * 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;

    /**

     * Constructor for ProgramSelector.

     *

     * It's not desired to modify selector objects, so all its fields are initialized at creation.

     * <p>It's not desired to modify selector objects, so all its fields are initialized at

     * creation.

     *

     * Identifier lists must not contain any nulls, but can itself be null to be interpreted

     * <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.

    /**

     * Looks up an identifier of a given type (either primary or secondary).

     *

     * If there are multiple identifiers if a given type, then first in order (where primary id is

     * before any secondary) is selected.

     * <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.

    /**

     * Looks up all identifier of a given type (either primary or secondary).

     *

     * Some identifiers may be provided multiple times, for example

     * IDENTIFIER_TYPE_AMFM_FREQUENCY for FM Alternate Frequencies.

     * <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 a list of identifiers, generated on each call. May be modified.

     * @return an array of identifiers, generated on each call. May be modified.

     */

    public @NonNull Identifier[] getAllIds(@IdentifierType int type) {

        List<Identifier> out = new ArrayList<>();

    /**

     * Creates an equivalent ProgramSelector with a given secondary identifier preferred.

     *

     * 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

     * <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.

     *

     * This is a best-effort hint for the tuner, not a guaranteed behavior.

     * <p>This is a best-effort hint for the tuner, not a guaranteed behavior.

     *

     * Setting the given secondary identifier as preferred means filtering out other secondary

     * <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

     *

     * @param band the band.

     * @param frequencyKhz the frequency in kHz.

     * @return new ProgramSelector object representing given frequency.

     * @return new {@link ProgramSelector} object representing given frequency.

     * @throws IllegalArgumentException if provided frequency is out of bounds.

     */

    public static @NonNull ProgramSelector createAmFmSelector(

    /**

     * Checks, if a given AM/FM frequency is roughly valid and in correct unit.

     *

     * It does not check the range precisely: it may provide false positives, but not false

     * <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 inproper units, ie. MHz instead of kHz.

     * 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 rougly valid.

     * @return true, if the frequency is roughly valid.

     */

    private static boolean isValidAmFmFrequency(boolean isAm, int frequencyKhz) {

        if (isAm) {

    /**

     * Builds new ProgramSelector for AM/FM frequency.

     *

     * This method variant supports HD Radio subchannels, but it's undesirable to

     * <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.

    };

    /**

     * A single program identifier component, eg. frequency or channel ID.

     * A single program identifier component, e.g. frequency or channel ID.

     *

     * The long value field holds the value in format described in comments for

     * <p>The long value field holds the value in format described in comments for

     * IdentifierType constants.

     */

    public static final class Identifier implements Parcelable {

        }

        /**

         * Returns whether this Identifier's type is considered a category when filtering

         * 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 tuneable (e.g. DAB ensemble or

         * @return False if this identifier's type is not tunable (e.g. DAB ensemble or

         *         vendor-specified type). True otherwise.

         */

        public boolean isCategoryType() {

        /**

         * Value of an identifier.

         *

         * Its meaning depends on identifier type, ie. for IDENTIFIER_TYPE_AMFM_FREQUENCY type,

         * the value is a frequency in kHz.

         * <p>Its meaning depends on identifier type, ie. for

         * {@link #IDENTIFIER_TYPE_AMFM_FREQUENCY} type, the value is a frequency in kHz.

         *

         * The range of a value depends on its type; it does not always require the whole long

         * <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, IDENTIFIER_TYPE_AMFM_FREQUENCY always fits in int,

         * as Integer.MAX_VALUE would mean 2.1THz.

         * 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.

         */

    /**

     * Provides a Clock that can be used to describe time as provided by the Radio.

     *

     * The clock is defined by the seconds since epoch at the UTC + 0 timezone

     * <p>The clock time is defined by the seconds since epoch at the UTC + 0 timezone

     * and timezone offset from UTC + 0 represented in number of minutes.

     *

     * @hide

    /**

     * Retrieves an identifier for a bitmap.

     *

     * The format of an identifier is opaque to the application,

     * <p>The format of an identifier is opaque to the application,

     * with a special case of value 0 being invalid.

     * An identifier for a given image-tuner pair is unique, so an application

     * may cache images and determine if there is a necessity to fetch them

     * again - if identifier changes, it means the image has changed.

     *

     * Only bitmap keys may be used with this method:

     * <p>Only bitmap keys may be used with this method:

     * <ul>

     *     <li>{@link #METADATA_KEY_ICON}</li>

     *     <li>{@link #METADATA_KEY_ART}</li>