Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 53142512 authored by Weilin Xu's avatar Weilin Xu
Browse files

Fix javadoc in broadcast radio service and API

Bug: 310029333
Test: atest BroadcastRadioTests
Change-Id: Ida5e487c07b2d899057b17a0920cc98eb8bb3dba
parent 7328ecc1
Loading
Loading
Loading
Loading
+1 −1
Original line number Diff line number Diff line
@@ -71,7 +71,7 @@ public final class Announcement implements Parcelable {
        /**
         * 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
         */
+9 −12
Original line number Diff line number Diff line
@@ -357,7 +357,7 @@ public final class ProgramList implements AutoCloseable {
        /**
         * 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()
@@ -438,12 +438,11 @@ public final class ProgramList implements AutoCloseable {
        /**
         * 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;
@@ -452,12 +451,10 @@ public final class ProgramList implements AutoCloseable {
        /**
         * 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;
@@ -476,7 +473,7 @@ public final class ProgramList implements AutoCloseable {
        /**
         * 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.
         */
+48 −43
Original line number Diff line number Diff line
@@ -36,27 +36,31 @@ import java.util.stream.Stream;
/**
 * 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
@@ -258,10 +262,10 @@ public final class ProgramSelector implements Parcelable {
    /**
     * 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
@@ -384,7 +388,7 @@ public final class ProgramSelector implements Parcelable {
     * 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;
@@ -435,9 +439,10 @@ public final class ProgramSelector implements Parcelable {
    /**
     * 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.
@@ -492,8 +497,8 @@ public final class ProgramSelector implements Parcelable {
    /**
     * 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.
@@ -510,11 +515,11 @@ public final class ProgramSelector implements Parcelable {
    /**
     * 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<>();
@@ -543,14 +548,14 @@ public final class ProgramSelector implements Parcelable {
    /**
     * 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
@@ -577,7 +582,7 @@ public final class ProgramSelector implements Parcelable {
     *
     * @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(
@@ -588,13 +593,13 @@ public final class ProgramSelector implements Parcelable {
    /**
     * 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) {
@@ -607,7 +612,7 @@ public final class ProgramSelector implements Parcelable {
    /**
     * 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.
@@ -741,9 +746,9 @@ public final class ProgramSelector implements Parcelable {
    };

    /**
     * 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 {
@@ -776,11 +781,11 @@ public final class ProgramSelector 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() {
@@ -791,14 +796,14 @@ public final class ProgramSelector implements Parcelable {
        /**
         * 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.
         */
+180 −111

File changed.

Preview size limit exceeded, changes collapsed.

+24 −24
Original line number Diff line number Diff line
@@ -291,7 +291,7 @@ public final class RadioMetadata implements Parcelable {
    /**
     * 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
@@ -493,13 +493,13 @@ public final class RadioMetadata implements Parcelable {
    /**
     * 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>
Loading