547 lines
20 KiB
Java
547 lines
20 KiB
Java
/*
|
||
* Copyright 2022 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;
|
||
|
||
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.util.ArrayList;
|
||
import java.util.Arrays;
|
||
import java.util.List;
|
||
import java.util.Objects;
|
||
|
||
/**
|
||
* This class represents a Broadcast Source group and the associated information that is needed
|
||
* by Broadcast Audio Scan Service (BASS) to set up a Broadcast Sink.
|
||
*
|
||
* <p>For example, an LE Audio Broadcast Sink can use the information contained within an instance
|
||
* of this class to synchronize with an LE Audio Broadcast group in order to listen to audio from
|
||
* Broadcast subgroup using one or more Broadcast Channels.
|
||
*
|
||
* @hide
|
||
*/
|
||
@SystemApi
|
||
public final class BluetoothLeBroadcastMetadata implements Parcelable {
|
||
// Information needed for adding broadcast Source
|
||
|
||
// Optional: Identity address type
|
||
private final @BluetoothDevice.AddressType int mSourceAddressType;
|
||
// Optional: Must use identity address
|
||
private final BluetoothDevice mSourceDevice;
|
||
private final int mSourceAdvertisingSid;
|
||
private final int mBroadcastId;
|
||
private final int mPaSyncInterval;
|
||
private final boolean mIsEncrypted;
|
||
private final byte[] mBroadcastCode;
|
||
|
||
// BASE structure
|
||
|
||
// See Section 7 for description. Range: 0x000000 – 0xFFFFFF Units: μs
|
||
//All other values: RFU
|
||
private final int mPresentationDelayMicros;
|
||
// Number of subgroups used to group BISes present in the BIG
|
||
//Shall be at least 1, as defined by Rule 1
|
||
// Sub group info numSubGroup = mSubGroups.length
|
||
private final List<BluetoothLeBroadcastSubgroup> mSubgroups;
|
||
|
||
private BluetoothLeBroadcastMetadata(int sourceAddressType,
|
||
BluetoothDevice sourceDevice, int sourceAdvertisingSid, int broadcastId,
|
||
int paSyncInterval, boolean isEncrypted, byte[] broadcastCode, int presentationDelay,
|
||
List<BluetoothLeBroadcastSubgroup> subgroups) {
|
||
mSourceAddressType = sourceAddressType;
|
||
mSourceDevice = sourceDevice;
|
||
mSourceAdvertisingSid = sourceAdvertisingSid;
|
||
mBroadcastId = broadcastId;
|
||
mPaSyncInterval = paSyncInterval;
|
||
mIsEncrypted = isEncrypted;
|
||
mBroadcastCode = broadcastCode;
|
||
mPresentationDelayMicros = presentationDelay;
|
||
mSubgroups = subgroups;
|
||
}
|
||
|
||
@Override
|
||
public boolean equals(@Nullable Object o) {
|
||
if (!(o instanceof BluetoothLeBroadcastMetadata)) {
|
||
return false;
|
||
}
|
||
final BluetoothLeBroadcastMetadata other = (BluetoothLeBroadcastMetadata) o;
|
||
return mSourceAddressType == other.getSourceAddressType()
|
||
&& mSourceDevice.equals(other.getSourceDevice())
|
||
&& mSourceAdvertisingSid == other.getSourceAdvertisingSid()
|
||
&& mBroadcastId == other.getBroadcastId()
|
||
&& mPaSyncInterval == other.getPaSyncInterval()
|
||
&& mIsEncrypted == other.isEncrypted()
|
||
&& Arrays.equals(mBroadcastCode, other.getBroadcastCode())
|
||
&& mPresentationDelayMicros == other.getPresentationDelayMicros()
|
||
&& mSubgroups.equals(other.getSubgroups());
|
||
}
|
||
|
||
@Override
|
||
public int hashCode() {
|
||
return Objects.hash(mSourceAddressType, mSourceDevice, mSourceAdvertisingSid,
|
||
mBroadcastId, mPaSyncInterval, mIsEncrypted, Arrays.hashCode(mBroadcastCode),
|
||
mPresentationDelayMicros, mSubgroups);
|
||
}
|
||
|
||
/**
|
||
* Get the address type of the Broadcast Source.
|
||
*
|
||
* Can be either {@link BluetoothDevice#ADDRESS_TYPE_PUBLIC},
|
||
* {@link BluetoothDevice#ADDRESS_TYPE_RANDOM}
|
||
*
|
||
* @return address type of the Broadcast Source
|
||
* @hide
|
||
*/
|
||
@SystemApi
|
||
public @BluetoothDevice.AddressType int getSourceAddressType() {
|
||
return mSourceAddressType;
|
||
}
|
||
|
||
/**
|
||
* Get the MAC address of the Broadcast Source, which can be Public Device Address,
|
||
* Random Device Address, Public Identity Address or Random (static) Identity Address.
|
||
*
|
||
* @return MAC address of the Broadcast Source
|
||
* @hide
|
||
*/
|
||
@SystemApi
|
||
public @NonNull BluetoothDevice getSourceDevice() {
|
||
return mSourceDevice;
|
||
}
|
||
|
||
/**
|
||
* Get Advertising_SID subfield of the ADI field of the AUX_ADV_IND PDU or the
|
||
* LL_PERIODIC_SYNC_IND containing the SyncInfo that points to the PA transmitted by the
|
||
* Broadcast Source.
|
||
*
|
||
* @return 1-byte long Advertising_SID of the Broadcast Source
|
||
* @hide
|
||
*/
|
||
@SystemApi
|
||
public int getSourceAdvertisingSid() {
|
||
return mSourceAdvertisingSid;
|
||
}
|
||
|
||
/**
|
||
* Broadcast_ID of the Broadcast Source.
|
||
*
|
||
* @return 3-byte long Broadcast_ID of the Broadcast Source
|
||
* @hide
|
||
*/
|
||
@SystemApi
|
||
public int getBroadcastId() {
|
||
return mBroadcastId;
|
||
}
|
||
|
||
/**
|
||
* Indicated that Periodic Advertising Sync interval is unknown.
|
||
* @hide
|
||
*/
|
||
@SystemApi
|
||
public static final int PA_SYNC_INTERVAL_UNKNOWN = 0xFFFF;
|
||
|
||
/**
|
||
* Get Periodic Advertising Sync interval of the broadcast Source.
|
||
*
|
||
* @return Periodic Advertising Sync interval of the broadcast Source,
|
||
* {@link #PA_SYNC_INTERVAL_UNKNOWN} if unknown
|
||
* @hide
|
||
*/
|
||
@SystemApi
|
||
public int getPaSyncInterval() {
|
||
return mPaSyncInterval;
|
||
}
|
||
|
||
/**
|
||
* Return true if the Broadcast Source is encrypted.
|
||
*
|
||
* @return true if the Broadcast Source is encrypted
|
||
* @hide
|
||
*/
|
||
@SystemApi
|
||
public boolean isEncrypted() {
|
||
return mIsEncrypted;
|
||
}
|
||
|
||
/**
|
||
* Get the Broadcast Code currently set for this Broadcast Source.
|
||
*
|
||
* Only needed when encryption is enabled
|
||
*
|
||
* <p>As defined in Volume 3, Part C, Section 3.2.6 of Bluetooth Core Specification, Version
|
||
* 5.3, Broadcast Code is used to encrypt a broadcast audio stream.
|
||
* <p>It must be a UTF-8 string that has at least 4 octets and should not exceed 16 octets.
|
||
*
|
||
* @return Broadcast Code currently set for this Broadcast Source, null if code is not required
|
||
* or code is currently unknown
|
||
* @hide
|
||
*/
|
||
@SystemApi
|
||
public @Nullable byte[] getBroadcastCode() {
|
||
return mBroadcastCode;
|
||
}
|
||
|
||
/**
|
||
* Get the overall presentation delay in microseconds of this Broadcast Source.
|
||
*
|
||
* Presentation delay is defined in Section 7 of the Basic Audio Profile.
|
||
*
|
||
* @return presentation delay of this Broadcast Source in microseconds
|
||
* @hide
|
||
*/
|
||
@SystemApi
|
||
public @IntRange(from = 0, to = 0xFFFFFF) int getPresentationDelayMicros() {
|
||
return mPresentationDelayMicros;
|
||
}
|
||
|
||
/**
|
||
* Get available subgroups in this broadcast source.
|
||
*
|
||
* @return list of subgroups in this broadcast source, which should contain at least one
|
||
* subgroup for each Broadcast Source
|
||
* @hide
|
||
*/
|
||
@SystemApi
|
||
public @NonNull List<BluetoothLeBroadcastSubgroup> getSubgroups() {
|
||
return mSubgroups;
|
||
}
|
||
|
||
/**
|
||
* {@inheritDoc}
|
||
* @hide
|
||
*/
|
||
@Override
|
||
public int describeContents() {
|
||
return 0;
|
||
}
|
||
|
||
/**
|
||
* {@inheritDoc}
|
||
* @hide
|
||
*/
|
||
@Override
|
||
public void writeToParcel(Parcel out, int flags) {
|
||
out.writeInt(mSourceAddressType);
|
||
if (mSourceDevice != null) {
|
||
out.writeInt(1);
|
||
out.writeTypedObject(mSourceDevice, 0);
|
||
} else {
|
||
// zero indicates missing mSourceDevice
|
||
out.writeInt(0);
|
||
}
|
||
out.writeInt(mSourceAdvertisingSid);
|
||
out.writeInt(mBroadcastId);
|
||
out.writeInt(mPaSyncInterval);
|
||
out.writeBoolean(mIsEncrypted);
|
||
if (mBroadcastCode != null) {
|
||
out.writeInt(mBroadcastCode.length);
|
||
out.writeByteArray(mBroadcastCode);
|
||
} else {
|
||
// -1 indicates missing broadcast code
|
||
out.writeInt(-1);
|
||
}
|
||
out.writeInt(mPresentationDelayMicros);
|
||
out.writeTypedList(mSubgroups);
|
||
}
|
||
|
||
/**
|
||
* A {@link Parcelable.Creator} to create {@link BluetoothLeBroadcastMetadata} from parcel.
|
||
* @hide
|
||
*/
|
||
@SystemApi
|
||
public static final @NonNull Parcelable.Creator<BluetoothLeBroadcastMetadata> CREATOR =
|
||
new Parcelable.Creator<BluetoothLeBroadcastMetadata>() {
|
||
public @NonNull BluetoothLeBroadcastMetadata createFromParcel(@NonNull Parcel in) {
|
||
Builder builder = new Builder();
|
||
final int sourceAddressType = in.readInt();
|
||
final int deviceExist = in.readInt();
|
||
BluetoothDevice sourceDevice = null;
|
||
if (deviceExist == 1) {
|
||
sourceDevice = in.readTypedObject(BluetoothDevice.CREATOR);
|
||
}
|
||
builder.setSourceDevice(sourceDevice, sourceAddressType);
|
||
builder.setSourceAdvertisingSid(in.readInt());
|
||
builder.setBroadcastId(in.readInt());
|
||
builder.setPaSyncInterval(in.readInt());
|
||
builder.setEncrypted(in.readBoolean());
|
||
final int codeLen = in.readInt();
|
||
byte[] broadcastCode = null;
|
||
if (codeLen != -1) {
|
||
broadcastCode = new byte[codeLen];
|
||
if (codeLen > 0) {
|
||
in.readByteArray(broadcastCode);
|
||
}
|
||
}
|
||
builder.setBroadcastCode(broadcastCode);
|
||
builder.setPresentationDelayMicros(in.readInt());
|
||
final List<BluetoothLeBroadcastSubgroup> subgroups = new ArrayList<>();
|
||
in.readTypedList(subgroups, BluetoothLeBroadcastSubgroup.CREATOR);
|
||
for (BluetoothLeBroadcastSubgroup subgroup : subgroups) {
|
||
builder.addSubgroup(subgroup);
|
||
}
|
||
return builder.build();
|
||
}
|
||
|
||
public @NonNull BluetoothLeBroadcastMetadata[] newArray(int size) {
|
||
return new BluetoothLeBroadcastMetadata[size];
|
||
}
|
||
};
|
||
|
||
private static final int UNKNOWN_VALUE_PLACEHOLDER = -1;
|
||
|
||
/**
|
||
* Builder for {@link BluetoothLeBroadcastMetadata}.
|
||
* @hide
|
||
*/
|
||
@SystemApi
|
||
public static final class Builder {
|
||
private @BluetoothDevice.AddressType int mSourceAddressType =
|
||
BluetoothDevice.ADDRESS_TYPE_UNKNOWN;
|
||
private BluetoothDevice mSourceDevice = null;
|
||
private int mSourceAdvertisingSid = UNKNOWN_VALUE_PLACEHOLDER;
|
||
private int mBroadcastId = UNKNOWN_VALUE_PLACEHOLDER;
|
||
private int mPaSyncInterval = UNKNOWN_VALUE_PLACEHOLDER;
|
||
private boolean mIsEncrypted = false;
|
||
private byte[] mBroadcastCode = null;
|
||
private int mPresentationDelayMicros = UNKNOWN_VALUE_PLACEHOLDER;
|
||
private List<BluetoothLeBroadcastSubgroup> mSubgroups = new ArrayList<>();
|
||
|
||
/**
|
||
* Create an empty builder.
|
||
*
|
||
* @hide
|
||
*/
|
||
@SystemApi
|
||
public Builder() {}
|
||
|
||
/**
|
||
* Create a builder with copies of information from original object.
|
||
*
|
||
* @param original original object
|
||
* @hide
|
||
*/
|
||
@SystemApi
|
||
public Builder(@NonNull BluetoothLeBroadcastMetadata original) {
|
||
mSourceAddressType = original.getSourceAddressType();
|
||
mSourceDevice = original.getSourceDevice();
|
||
mSourceAdvertisingSid = original.getSourceAdvertisingSid();
|
||
mBroadcastId = original.getBroadcastId();
|
||
mPaSyncInterval = original.getPaSyncInterval();
|
||
mIsEncrypted = original.isEncrypted();
|
||
mBroadcastCode = original.getBroadcastCode();
|
||
mPresentationDelayMicros = original.getPresentationDelayMicros();
|
||
mSubgroups = original.getSubgroups();
|
||
}
|
||
|
||
|
||
/**
|
||
* Set the address type and MAC address of the Broadcast Source.
|
||
*
|
||
* Address type can be either {@link BluetoothDevice#ADDRESS_TYPE_PUBLIC},
|
||
* {@link BluetoothDevice#ADDRESS_TYPE_RANDOM}
|
||
*
|
||
* MAC address can be Public Device Address, Random Device Address, Public Identity Address
|
||
* or Random (static) Identity Address
|
||
*
|
||
* @param sourceDevice source advertiser address
|
||
* @param sourceAddressType source advertiser address type
|
||
* @throws IllegalArgumentException if sourceAddressType is invalid
|
||
* @throws NullPointerException if sourceDevice is null
|
||
* @return this builder
|
||
* @hide
|
||
*/
|
||
@SystemApi
|
||
public @NonNull Builder setSourceDevice(@NonNull BluetoothDevice sourceDevice,
|
||
@BluetoothDevice.AddressType int sourceAddressType) {
|
||
if (sourceAddressType == BluetoothDevice.ADDRESS_TYPE_UNKNOWN) {
|
||
throw new IllegalArgumentException(
|
||
"sourceAddressType cannot be ADDRESS_TYPE_UNKNOWN");
|
||
}
|
||
if (sourceAddressType != BluetoothDevice.ADDRESS_TYPE_RANDOM
|
||
&& sourceAddressType != BluetoothDevice.ADDRESS_TYPE_PUBLIC) {
|
||
throw new IllegalArgumentException("sourceAddressType " + sourceAddressType
|
||
+ " is invalid");
|
||
}
|
||
Objects.requireNonNull(sourceDevice, "sourceDevice cannot be null");
|
||
mSourceAddressType = sourceAddressType;
|
||
mSourceDevice = sourceDevice;
|
||
return this;
|
||
}
|
||
|
||
/**
|
||
* Set Advertising_SID that is a subfield of the ADI field of the AUX_ADV_IND PDU or the
|
||
* LL_PERIODIC_SYNC_IND containing the SyncInfo that points to the PA transmitted by the
|
||
* Broadcast Source.
|
||
*
|
||
* @param sourceAdvertisingSid 1-byte long Advertising_SID of the Broadcast Source
|
||
* @return this builder
|
||
* @hide
|
||
*/
|
||
@SystemApi
|
||
public @NonNull Builder setSourceAdvertisingSid(int sourceAdvertisingSid) {
|
||
mSourceAdvertisingSid = sourceAdvertisingSid;
|
||
return this;
|
||
}
|
||
|
||
/**
|
||
* Set the Broadcast_ID of the Broadcast Source.
|
||
*
|
||
* @param broadcastId 3-byte long Broadcast_ID of the Broadcast Source
|
||
* @return this builder
|
||
* @hide
|
||
*/
|
||
@SystemApi
|
||
public @NonNull Builder setBroadcastId(int broadcastId) {
|
||
mBroadcastId = broadcastId;
|
||
return this;
|
||
}
|
||
|
||
/**
|
||
* Set Periodic Advertising Sync interval of the broadcast Source.
|
||
*
|
||
* @param paSyncInterval Periodic Advertising Sync interval of the broadcast Source,
|
||
* {@link #PA_SYNC_INTERVAL_UNKNOWN} if unknown
|
||
* @return this builder
|
||
* @hide
|
||
*/
|
||
@SystemApi
|
||
public @NonNull Builder setPaSyncInterval(int paSyncInterval) {
|
||
mPaSyncInterval = paSyncInterval;
|
||
return this;
|
||
}
|
||
|
||
/**
|
||
* Set whether the Broadcast Source should be encrypted.
|
||
*
|
||
* When setting up a Broadcast Source, if <var>isEncrypted</var> is true while
|
||
* <var>broadcastCode</var> is null, the implementation will automatically generate
|
||
* a Broadcast Code
|
||
*
|
||
* @param isEncrypted whether the Broadcast Source is encrypted
|
||
* @return this builder
|
||
* @hide
|
||
*/
|
||
@SystemApi
|
||
public @NonNull Builder setEncrypted(boolean isEncrypted) {
|
||
mIsEncrypted = isEncrypted;
|
||
return this;
|
||
}
|
||
|
||
/**
|
||
* Set the Broadcast Code currently set for this Broadcast Source.
|
||
*
|
||
* Only needed when encryption is enabled
|
||
*
|
||
* <p>As defined in Volume 3, Part C, Section 3.2.6 of Bluetooth Core Specification, Version
|
||
* 5.3, Broadcast Code is used to encrypt a broadcast audio stream.
|
||
* <p>It must be a UTF-8 string that has at least 4 octets and should not exceed 16 octets.
|
||
*
|
||
* @param broadcastCode Broadcast Code for this Broadcast Source, null if code is not
|
||
* required
|
||
* @return this builder
|
||
* @hide
|
||
*/
|
||
@SystemApi
|
||
public @NonNull Builder setBroadcastCode(@Nullable byte[] broadcastCode) {
|
||
mBroadcastCode = broadcastCode;
|
||
return this;
|
||
}
|
||
|
||
/**
|
||
* Set the overall presentation delay in microseconds of this Broadcast Source.
|
||
*
|
||
* Presentation delay is defined in Section 7 of the Basic Audio Profile.
|
||
*
|
||
* @param presentationDelayMicros presentation delay of this Broadcast Source in
|
||
* microseconds
|
||
* @throws IllegalArgumentException if presentationDelayMicros does not fall in
|
||
* [0, 0xFFFFFF]
|
||
* @return this builder
|
||
* @hide
|
||
*/
|
||
@SystemApi
|
||
public @NonNull Builder setPresentationDelayMicros(
|
||
@IntRange(from = 0, to = 0xFFFFFF) int presentationDelayMicros) {
|
||
if (presentationDelayMicros < 0 || presentationDelayMicros >= 0xFFFFFF) {
|
||
throw new IllegalArgumentException("presentationDelayMicros "
|
||
+ presentationDelayMicros + " does not fall in [0, 0xFFFFFF]");
|
||
}
|
||
mPresentationDelayMicros = presentationDelayMicros;
|
||
return this;
|
||
}
|
||
|
||
/**
|
||
* Add a subgroup to this broadcast source.
|
||
*
|
||
* @param subgroup {@link BluetoothLeBroadcastSubgroup} that contains a subgroup's metadata
|
||
* @throws NullPointerException if subgroup is null
|
||
* @return this builder
|
||
* @hide
|
||
*/
|
||
@SystemApi
|
||
public @NonNull Builder addSubgroup(@NonNull BluetoothLeBroadcastSubgroup subgroup) {
|
||
Objects.requireNonNull(subgroup, "subgroup cannot be null");
|
||
mSubgroups.add(subgroup);
|
||
return this;
|
||
}
|
||
|
||
/**
|
||
* Clear subgroup list so that one can reset the builder after create it from an existing
|
||
* object.
|
||
*
|
||
* @return this builder
|
||
* @hide
|
||
*/
|
||
@SystemApi
|
||
public @NonNull Builder clearSubgroup() {
|
||
mSubgroups.clear();
|
||
return this;
|
||
}
|
||
|
||
/**
|
||
* Build {@link BluetoothLeBroadcastMetadata}.
|
||
*
|
||
* @return {@link BluetoothLeBroadcastMetadata}
|
||
* @throws IllegalArgumentException if the object cannot be built
|
||
* @throws NullPointerException if {@link NonNull} items are null
|
||
* @hide
|
||
*/
|
||
@SystemApi
|
||
public @NonNull BluetoothLeBroadcastMetadata build() {
|
||
if (mSourceAddressType == BluetoothDevice.ADDRESS_TYPE_UNKNOWN) {
|
||
throw new IllegalArgumentException("SourceAddressTyp cannot be unknown");
|
||
}
|
||
if (mSourceAddressType != BluetoothDevice.ADDRESS_TYPE_RANDOM
|
||
&& mSourceAddressType != BluetoothDevice.ADDRESS_TYPE_PUBLIC) {
|
||
throw new IllegalArgumentException("sourceAddressType " + mSourceAddressType
|
||
+ " is invalid");
|
||
}
|
||
Objects.requireNonNull(mSourceDevice, "mSourceDevice cannot be null");
|
||
if (mSubgroups.isEmpty()) {
|
||
throw new IllegalArgumentException("Must contain at least one subgroup");
|
||
}
|
||
return new BluetoothLeBroadcastMetadata(mSourceAddressType, mSourceDevice,
|
||
mSourceAdvertisingSid, mBroadcastId, mPaSyncInterval, mIsEncrypted,
|
||
mBroadcastCode, mPresentationDelayMicros, mSubgroups);
|
||
}
|
||
}
|
||
}
|