bluetooth/le/AdvertisingSetParameters.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.bluetooth.le;

import android.bluetooth.BluetoothAdapter;
import android.bluetooth.BluetoothDevice;
import android.os.Parcel;
import android.os.Parcelable;

/**
 * The {@link AdvertisingSetParameters} provide a way to adjust advertising
 * preferences for each
 * Bluetooth LE advertising set. Use {@link AdvertisingSetParameters.Builder} to
 * create an
 * instance of this class.
 */
public final class AdvertisingSetParameters implements Parcelable {

    /**
    * Advertise on low frequency, around every 1000ms. This is the default and
    * preferred advertising mode as it consumes the least power.
    */
    public static final int INTERVAL_HIGH = 1600;

    /**
     * Advertise on medium frequency, around every 250ms. This is balanced
     * between advertising frequency and power consumption.
     */
    public static final int INTERVAL_MEDIUM = 400;

    /**
     * Perform high frequency, low latency advertising, around every 100ms. This
     * has the highest power consumption and should not be used for continuous
     * background advertising.
     */
    public static final int INTERVAL_LOW = 160;

    /**
     * Minimum value for advertising interval.
     */
    public static final int INTERVAL_MIN = 160;

    /**
     * Maximum value for advertising interval.
     */
    public static final int INTERVAL_MAX = 16777215;

    /**
     * Advertise using the lowest transmission (TX) power level. Low transmission
     * power can be used to restrict the visibility range of advertising packets.
     */
    public static final int TX_POWER_ULTRA_LOW = -21;

    /**
     * Advertise using low TX power level.
     */
    public static final int TX_POWER_LOW = -15;

    /**
     * Advertise using medium TX power level.
     */
    public static final int TX_POWER_MEDIUM = -7;

    /**
     * Advertise using high TX power level. This corresponds to largest visibility
     * range of the advertising packet.
     */
    public static final int TX_POWER_HIGH = 1;

    /**
     * Minimum value for TX power.
     */
    public static final int TX_POWER_MIN = -127;

    /**
     * Maximum value for TX power.
     */
    public static final int TX_POWER_MAX = 1;

    /**
     * The maximum limited advertisement duration as specified by the Bluetooth
     * SIG
     */
    private static final int LIMITED_ADVERTISING_MAX_MILLIS = 180 * 1000;

    private final boolean isLegacy;
    private final boolean isAnonymous;
    private final boolean includeTxPower;
    private final int primaryPhy;
    private final int secondaryPhy;
    private final boolean connectable;
    private final boolean scannable;
    private final int interval;
    private final int txPowerLevel;

    private AdvertisingSetParameters(boolean connectable, boolean scannable, boolean isLegacy,
                                     boolean isAnonymous, boolean includeTxPower,
                                     int primaryPhy, int secondaryPhy,
                                     int interval, int txPowerLevel) {
        this.connectable = connectable;
        this.scannable = scannable;
        this.isLegacy = isLegacy;
        this.isAnonymous = isAnonymous;
        this.includeTxPower = includeTxPower;
        this.primaryPhy = primaryPhy;
        this.secondaryPhy = secondaryPhy;
        this.interval = interval;
        this.txPowerLevel = txPowerLevel;
    }

    private AdvertisingSetParameters(Parcel in) {
        connectable = in.readInt() != 0 ? true : false;
        scannable = in.readInt() != 0 ? true : false;
        isLegacy = in.readInt() != 0 ? true : false;
        isAnonymous = in.readInt() != 0 ? true : false;
        includeTxPower = in.readInt() != 0 ? true : false;
        primaryPhy = in.readInt();
        secondaryPhy = in.readInt();
        interval = in.readInt();
        txPowerLevel = in.readInt();
    }

    /**
     * Returns whether the advertisement will be connectable.
     */
    public boolean isConnectable() { return connectable; }

    /**
     * Returns whether the advertisement will be scannable.
     */
    public boolean isScannable() { return scannable; }

    /**
     * Returns whether the legacy advertisement will be used.
     */
    public boolean isLegacy() { return isLegacy; }

    /**
     * Returns whether the advertisement will be anonymous.
     */
    public boolean isAnonymous() { return isAnonymous; }

    /**
     * Returns whether the TX Power will be included.
     */
    public boolean includeTxPower() { return includeTxPower; }

    /**
     * Returns the primary advertising phy.
     */
    public int getPrimaryPhy() { return primaryPhy; }

    /**
     * Returns the secondary advertising phy.
     */
    public int getSecondaryPhy() { return secondaryPhy; }

    /**
     * Returns the advertising interval.
     */
    public int getInterval() { return interval; }

    /**
     * Returns the TX power level for advertising.
     */
    public int getTxPowerLevel() { return txPowerLevel; }

    @Override
    public String toString() {
        return "AdvertisingSetParameters [connectable=" + connectable
             + ", isLegacy=" + isLegacy
             + ", isAnonymous=" + isAnonymous
             + ", includeTxPower=" + includeTxPower
             + ", primaryPhy=" + primaryPhy
             + ", secondaryPhy=" + secondaryPhy
             + ", interval=" + interval
             + ", txPowerLevel=" + txPowerLevel + "]";
    }

    @Override
    public int describeContents() {
       return 0;
    }

    @Override
    public void writeToParcel(Parcel dest, int flags) {
        dest.writeInt(connectable ? 1 : 0);
        dest.writeInt(scannable ? 1 : 0);
        dest.writeInt(isLegacy ? 1 : 0);
        dest.writeInt(isAnonymous ? 1 : 0);
        dest.writeInt(includeTxPower ? 1 : 0);
        dest.writeInt(primaryPhy);
        dest.writeInt(secondaryPhy);
        dest.writeInt(interval);
        dest.writeInt(txPowerLevel);
    }

    public static final Parcelable.Creator<AdvertisingSetParameters> CREATOR =
        new Creator<AdvertisingSetParameters>() {
          @Override
          public AdvertisingSetParameters[] newArray(int size) {
            return new AdvertisingSetParameters[size];
          }

          @Override
          public AdvertisingSetParameters createFromParcel(Parcel in) {
            return new AdvertisingSetParameters(in);
          }
        };

    /**
     * Builder class for {@link AdvertisingSetParameters}.
     */
    public static final class Builder {

        private boolean connectable = false;
        private boolean scannable = false;
        private boolean isLegacy = false;
        private boolean isAnonymous = false;
        private boolean includeTxPower = false;
        private int primaryPhy = BluetoothDevice.PHY_LE_1M;
        private int secondaryPhy = BluetoothDevice.PHY_LE_1M;
        private int interval = INTERVAL_LOW;
        private int txPowerLevel = TX_POWER_MEDIUM;

        /**
         * Set whether the advertisement type should be connectable or
         * non-connectable.
         * Legacy advertisements can be both connectable and scannable. Non-legacy
         * advertisements can be only scannable or only connectable.
         * @param connectable Controls whether the advertisement type will be
         * connectable (true) or non-connectable (false).
         */
        public Builder setConnectable(boolean connectable) {
            this.connectable = connectable;
            return this;
        }

        /**
         * Set whether the advertisement type should be scannable.
         * Legacy advertisements can be both connectable and scannable. Non-legacy
         * advertisements can be only scannable or only connectable.
         * @param scannable Controls whether the advertisement type will be
         * scannable (true) or non-scannable (false).
         */
        public Builder setScannable(boolean scannable) {
            this.scannable = scannable;
            return this;
        }

        /**
         * When set to true, advertising set will advertise 4.x Spec compliant
         * advertisements.
         *
         * @param isLegacy whether legacy advertising mode should be used.
         */
        public Builder setLegacyMode(boolean isLegacy) {
            this.isLegacy = isLegacy;
            return this;
        }

        /**
         * Set whether advertiser address should be ommited from all packets. If this
         * mode is used, periodic advertising can't be enabled for this set.
         *
         * This is used only if legacy mode is not used.
         *
         * @param isAnonymous whether anonymous advertising should be used.
         */
        public Builder setAnonymous(boolean isAnonymous) {
            this.isAnonymous = isAnonymous;
            return this;
        }

        /**
         * Set whether TX power should be included in the extended header.
         *
         * This is used only if legacy mode is not used.
         *
         * @param includeTxPower whether TX power should be included in extended
         *            header
         */
        public Builder setIncludeTxPower(boolean includeTxPower) {
            this.includeTxPower = includeTxPower;
            return this;
        }

        /**
         * Set the primary physical channel used for this advertising set.
         *
         * This is used only if legacy mode is not used.
         *
         * Use {@link BluetoothAdapter#isLeCodedPhySupported} to determine if LE Coded PHY is
         * supported on this device.
         * @param primaryPhy Primary advertising physical channel, can only be
         *            {@link BluetoothDevice#PHY_LE_1M} or
         *            {@link BluetoothDevice#PHY_LE_CODED}.
         * @throws IllegalArgumentException If the primaryPhy is invalid.
         */
        public Builder setPrimaryPhy(int primaryPhy) {
            if (primaryPhy != BluetoothDevice.PHY_LE_1M &&
                primaryPhy != BluetoothDevice.PHY_LE_CODED) {
               throw new IllegalArgumentException("bad primaryPhy " + primaryPhy);
            }
            this.primaryPhy = primaryPhy;
            return this;
        }

        /**
         * Set the secondary physical channel used for this advertising set.
         *
         * This is used only if legacy mode is not used.
         *
         * Use {@link BluetoothAdapter#isLeCodedPhySupported} and
         * {@link BluetoothAdapter#isLe2MPhySupported} to determine if LE Coded PHY or 2M PHY is
         * supported on this device.
         *
         * @param secondaryPhy Secondary advertising physical channel, can only be
         *            one of {@link BluetoothDevice#PHY_LE_1M},
         *            {@link BluetoothDevice#PHY_LE_2M} or
         *            {@link BluetoothDevice#PHY_LE_CODED}.
         * @throws IllegalArgumentException If the secondaryPhy is invalid.
         */
        public Builder setSecondaryPhy(int secondaryPhy) {
            if (secondaryPhy != BluetoothDevice.PHY_LE_1M &&
                secondaryPhy != BluetoothDevice.PHY_LE_2M &&
                secondaryPhy != BluetoothDevice.PHY_LE_CODED) {
               throw new IllegalArgumentException("bad secondaryPhy " + secondaryPhy);
            }
            this.secondaryPhy = secondaryPhy;
            return this;
        }

        /**
         * Set advertising interval.
         *
         * @param interval Bluetooth LE Advertising interval, in 0.625ms unit. Valid
         *            range is from 160 (100ms) to 16777215 (10,485.759375 s).
         *            Recommended values are:
         *            {@link AdvertisingSetParameters#INTERVAL_LOW},
         *            {@link AdvertisingSetParameters#INTERVAL_MEDIUM}, or
         *            {@link AdvertisingSetParameters#INTERVAL_HIGH}.
         * @throws IllegalArgumentException If the interval is invalid.
         */
        public Builder setInterval(int interval) {
            if (interval < INTERVAL_MIN || interval > INTERVAL_MAX) {
               throw new IllegalArgumentException("unknown interval " + interval);
            }
            this.interval = interval;
            return this;
        }

        /**
         * Set the transmission power level for the advertising.
         * @param txPowerLevel Transmission power of Bluetooth LE Advertising, in
         *             dBm. The valid range is [-127, 1] Recommended values are:
         *             {@link AdvertisingSetParameters#TX_POWER_ULTRA_LOW},
         *             {@link AdvertisingSetParameters#TX_POWER_LOW},
         *             {@link AdvertisingSetParameters#TX_POWER_MEDIUM}, or
         *             {@link AdvertisingSetParameters#TX_POWER_HIGH}.
         *
         * @throws IllegalArgumentException If the {@code txPowerLevel} is invalid.
         */
        public Builder setTxPowerLevel(int txPowerLevel) {
            if (txPowerLevel < TX_POWER_MIN || txPowerLevel > TX_POWER_MAX) {
                throw new IllegalArgumentException("unknown txPowerLevel " +
                                                   txPowerLevel);
            }
            this.txPowerLevel = txPowerLevel;
            return this;
        }

        /**
         * Build the {@link AdvertisingSetParameters} object.
         * @throws IllegalStateException if invalid combination of parameters is used.
         */
        public AdvertisingSetParameters build() {
            if (isLegacy) {
                if (isAnonymous) {
                    throw new IllegalArgumentException("Legacy advertising can't be anonymous");
                }

                if (connectable == true && scannable == false) {
                    throw new IllegalStateException(
                        "Legacy advertisement can't be connectable and non-scannable");
                }

                if (includeTxPower) {
                    throw new IllegalStateException(
                        "Legacy advertising can't include TX power level in header");
                }
            } else {
                if (connectable && scannable) {
                    throw new IllegalStateException(
                        "Advertising can't be both connectable and scannable");
                }

                if (isAnonymous && connectable) {
                    throw new IllegalStateException(
                        "Advertising can't be both connectable and anonymous");
                }
            }

            return new AdvertisingSetParameters(connectable, scannable, isLegacy, isAnonymous,
                                                includeTxPower, primaryPhy,
                                                secondaryPhy, interval, txPowerLevel);
        }
    }
}