| /* |
| * Copyright (C) 2014 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.os.Parcel; |
| import android.os.Parcelable; |
| |
| /** |
| * The {@link AdvertiseSettings} provide a way to adjust advertising preferences for each |
| * Bluetooth LE advertisement instance. Use {@link AdvertiseSettings.Builder} to create an |
| * instance of this class. |
| */ |
| public final class AdvertiseSettings implements Parcelable { |
| /** |
| * Perform Bluetooth LE advertising in low power mode. This is the default and preferred |
| * advertising mode as it consumes the least power. |
| */ |
| public static final int ADVERTISE_MODE_LOW_POWER = 0; |
| |
| /** |
| * Perform Bluetooth LE advertising in balanced power mode. This is balanced between advertising |
| * frequency and power consumption. |
| */ |
| public static final int ADVERTISE_MODE_BALANCED = 1; |
| |
| /** |
| * Perform Bluetooth LE advertising in low latency, high power mode. This has the highest power |
| * consumption and should not be used for continuous background advertising. |
| */ |
| public static final int ADVERTISE_MODE_LOW_LATENCY = 2; |
| |
| /** |
| * 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 ADVERTISE_TX_POWER_ULTRA_LOW = 0; |
| |
| /** |
| * Advertise using low TX power level. |
| */ |
| public static final int ADVERTISE_TX_POWER_LOW = 1; |
| |
| /** |
| * Advertise using medium TX power level. |
| */ |
| public static final int ADVERTISE_TX_POWER_MEDIUM = 2; |
| |
| /** |
| * Advertise using high TX power level. This corresponds to largest visibility range of the |
| * advertising packet. |
| */ |
| public static final int ADVERTISE_TX_POWER_HIGH = 3; |
| |
| /** |
| * The maximum limited advertisement duration as specified by the Bluetooth SIG |
| */ |
| private static final int LIMITED_ADVERTISING_MAX_MILLIS = 180 * 1000; |
| |
| private final int mAdvertiseMode; |
| private final int mAdvertiseTxPowerLevel; |
| private final int mAdvertiseTimeoutMillis; |
| private final boolean mAdvertiseConnectable; |
| |
| private AdvertiseSettings(int advertiseMode, int advertiseTxPowerLevel, |
| boolean advertiseConnectable, int advertiseTimeout) { |
| mAdvertiseMode = advertiseMode; |
| mAdvertiseTxPowerLevel = advertiseTxPowerLevel; |
| mAdvertiseConnectable = advertiseConnectable; |
| mAdvertiseTimeoutMillis = advertiseTimeout; |
| } |
| |
| private AdvertiseSettings(Parcel in) { |
| mAdvertiseMode = in.readInt(); |
| mAdvertiseTxPowerLevel = in.readInt(); |
| mAdvertiseConnectable = in.readInt() != 0; |
| mAdvertiseTimeoutMillis = in.readInt(); |
| } |
| |
| /** |
| * Returns the advertise mode. |
| */ |
| public int getMode() { |
| return mAdvertiseMode; |
| } |
| |
| /** |
| * Returns the TX power level for advertising. |
| */ |
| public int getTxPowerLevel() { |
| return mAdvertiseTxPowerLevel; |
| } |
| |
| /** |
| * Returns whether the advertisement will indicate connectable. |
| */ |
| public boolean isConnectable() { |
| return mAdvertiseConnectable; |
| } |
| |
| /** |
| * Returns the advertising time limit in milliseconds. |
| */ |
| public int getTimeout() { |
| return mAdvertiseTimeoutMillis; |
| } |
| |
| @Override |
| public String toString() { |
| return "Settings [mAdvertiseMode=" + mAdvertiseMode |
| + ", mAdvertiseTxPowerLevel=" + mAdvertiseTxPowerLevel |
| + ", mAdvertiseConnectable=" + mAdvertiseConnectable |
| + ", mAdvertiseTimeoutMillis=" + mAdvertiseTimeoutMillis + "]"; |
| } |
| |
| @Override |
| public int describeContents() { |
| return 0; |
| } |
| |
| @Override |
| public void writeToParcel(Parcel dest, int flags) { |
| dest.writeInt(mAdvertiseMode); |
| dest.writeInt(mAdvertiseTxPowerLevel); |
| dest.writeInt(mAdvertiseConnectable ? 1 : 0); |
| dest.writeInt(mAdvertiseTimeoutMillis); |
| } |
| |
| public static final Parcelable.Creator<AdvertiseSettings> CREATOR = |
| new Creator<AdvertiseSettings>() { |
| @Override |
| public AdvertiseSettings[] newArray(int size) { |
| return new AdvertiseSettings[size]; |
| } |
| |
| @Override |
| public AdvertiseSettings createFromParcel(Parcel in) { |
| return new AdvertiseSettings(in); |
| } |
| }; |
| |
| /** |
| * Builder class for {@link AdvertiseSettings}. |
| */ |
| public static final class Builder { |
| private int mMode = ADVERTISE_MODE_LOW_POWER; |
| private int mTxPowerLevel = ADVERTISE_TX_POWER_MEDIUM; |
| private int mTimeoutMillis = 0; |
| private boolean mConnectable = true; |
| |
| /** |
| * Set advertise mode to control the advertising power and latency. |
| * |
| * @param advertiseMode Bluetooth LE Advertising mode, can only be one of {@link |
| * AdvertiseSettings#ADVERTISE_MODE_LOW_POWER}, |
| * {@link AdvertiseSettings#ADVERTISE_MODE_BALANCED}, |
| * or {@link AdvertiseSettings#ADVERTISE_MODE_LOW_LATENCY}. |
| * @throws IllegalArgumentException If the advertiseMode is invalid. |
| */ |
| public Builder setAdvertiseMode(int advertiseMode) { |
| if (advertiseMode < ADVERTISE_MODE_LOW_POWER |
| || advertiseMode > ADVERTISE_MODE_LOW_LATENCY) { |
| throw new IllegalArgumentException("unknown mode " + advertiseMode); |
| } |
| mMode = advertiseMode; |
| return this; |
| } |
| |
| /** |
| * Set advertise TX power level to control the transmission power level for the advertising. |
| * |
| * @param txPowerLevel Transmission power of Bluetooth LE Advertising, can only be one of |
| * {@link AdvertiseSettings#ADVERTISE_TX_POWER_ULTRA_LOW}, {@link |
| * AdvertiseSettings#ADVERTISE_TX_POWER_LOW}, |
| * {@link AdvertiseSettings#ADVERTISE_TX_POWER_MEDIUM} |
| * or {@link AdvertiseSettings#ADVERTISE_TX_POWER_HIGH}. |
| * @throws IllegalArgumentException If the {@code txPowerLevel} is invalid. |
| */ |
| public Builder setTxPowerLevel(int txPowerLevel) { |
| if (txPowerLevel < ADVERTISE_TX_POWER_ULTRA_LOW |
| || txPowerLevel > ADVERTISE_TX_POWER_HIGH) { |
| throw new IllegalArgumentException("unknown tx power level " + txPowerLevel); |
| } |
| mTxPowerLevel = txPowerLevel; |
| return this; |
| } |
| |
| /** |
| * Set whether the advertisement type should be connectable or non-connectable. |
| * |
| * @param connectable Controls whether the advertisment type will be connectable (true) or |
| * non-connectable (false). |
| */ |
| public Builder setConnectable(boolean connectable) { |
| mConnectable = connectable; |
| return this; |
| } |
| |
| /** |
| * Limit advertising to a given amount of time. |
| * |
| * @param timeoutMillis Advertising time limit. May not exceed 180000 milliseconds. A value |
| * of 0 will disable the time limit. |
| * @throws IllegalArgumentException If the provided timeout is over 180000 ms. |
| */ |
| public Builder setTimeout(int timeoutMillis) { |
| if (timeoutMillis < 0 || timeoutMillis > LIMITED_ADVERTISING_MAX_MILLIS) { |
| throw new IllegalArgumentException("timeoutMillis invalid (must be 0-" |
| + LIMITED_ADVERTISING_MAX_MILLIS + " milliseconds)"); |
| } |
| mTimeoutMillis = timeoutMillis; |
| return this; |
| } |
| |
| /** |
| * Build the {@link AdvertiseSettings} object. |
| */ |
| public AdvertiseSettings build() { |
| return new AdvertiseSettings(mMode, mTxPowerLevel, mConnectable, mTimeoutMillis); |
| } |
| } |
| } |