1 /* 2 * Copyright (C) 2017 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package android.bluetooth.le; 18 19 import android.bluetooth.BluetoothAdapter; 20 import android.bluetooth.IBluetoothGatt; 21 import android.bluetooth.IBluetoothManager; 22 import android.os.RemoteException; 23 import android.util.Log; 24 25 /** 26 * This class provides a way to control single Bluetooth LE advertising instance. 27 * <p> 28 * To get an instance of {@link AdvertisingSet}, call the 29 * {@link BluetoothLeAdvertiser#startAdvertisingSet} method. 30 * <p> 31 * <b>Note:</b> Most of the methods here require {@link android.Manifest.permission#BLUETOOTH_ADMIN} 32 * permission. 33 * 34 * @see AdvertiseData 35 */ 36 public final class AdvertisingSet { 37 private static final String TAG = "AdvertisingSet"; 38 39 private final IBluetoothGatt mGatt; 40 private int mAdvertiserId; 41 42 /* package */ AdvertisingSet(int advertiserId, 43 IBluetoothManager bluetoothManager) { 44 mAdvertiserId = advertiserId; 45 46 try { 47 mGatt = bluetoothManager.getBluetoothGatt(); 48 } catch (RemoteException e) { 49 Log.e(TAG, "Failed to get Bluetooth gatt - ", e); 50 throw new IllegalStateException("Failed to get Bluetooth"); 51 } 52 } 53 54 /* package */ void setAdvertiserId(int advertiserId) { 55 mAdvertiserId = advertiserId; 56 } 57 58 /** 59 * Enables Advertising. This method returns immediately, the operation status is 60 * delivered through {@code callback.onAdvertisingEnabled()}. 61 * <p> 62 * Requires {@link android.Manifest.permission#BLUETOOTH_ADMIN} 63 * 64 * @param enable whether the advertising should be enabled (true), or disabled (false) 65 * @param duration advertising duration, in 10ms unit. Valid range is from 1 (10ms) to 65535 66 * (655,350 ms) 67 * @param maxExtendedAdvertisingEvents maximum number of extended advertising events the 68 * controller shall attempt to send prior to terminating the extended advertising, even if the 69 * duration has not expired. Valid range is from 1 to 255. 70 */ 71 public void enableAdvertising(boolean enable, int duration, 72 int maxExtendedAdvertisingEvents) { 73 try { 74 mGatt.enableAdvertisingSet(mAdvertiserId, enable, duration, 75 maxExtendedAdvertisingEvents); 76 } catch (RemoteException e) { 77 Log.e(TAG, "remote exception - ", e); 78 } 79 } 80 81 /** 82 * Set/update data being Advertised. Make sure that data doesn't exceed the size limit for 83 * specified AdvertisingSetParameters. This method returns immediately, the operation status is 84 * delivered through {@code callback.onAdvertisingDataSet()}. 85 * <p> 86 * Advertising data must be empty if non-legacy scannable advertising is used. 87 * 88 * @param advertiseData Advertisement data to be broadcasted. Size must not exceed {@link 89 * BluetoothAdapter#getLeMaximumAdvertisingDataLength}. If the advertisement is connectable, 90 * three bytes will be added for flags. If the update takes place when the advertising set is 91 * enabled, the data can be maximum 251 bytes long. 92 */ 93 public void setAdvertisingData(AdvertiseData advertiseData) { 94 try { 95 mGatt.setAdvertisingData(mAdvertiserId, advertiseData); 96 } catch (RemoteException e) { 97 Log.e(TAG, "remote exception - ", e); 98 } 99 } 100 101 /** 102 * Set/update scan response data. Make sure that data doesn't exceed the size limit for 103 * specified AdvertisingSetParameters. This method returns immediately, the operation status 104 * is delivered through {@code callback.onScanResponseDataSet()}. 105 * 106 * @param scanResponse Scan response associated with the advertisement data. Size must not 107 * exceed {@link BluetoothAdapter#getLeMaximumAdvertisingDataLength}. If the update takes place 108 * when the advertising set is enabled, the data can be maximum 251 bytes long. 109 */ 110 public void setScanResponseData(AdvertiseData scanResponse) { 111 try { 112 mGatt.setScanResponseData(mAdvertiserId, scanResponse); 113 } catch (RemoteException e) { 114 Log.e(TAG, "remote exception - ", e); 115 } 116 } 117 118 /** 119 * Update advertising parameters associated with this AdvertisingSet. Must be called when 120 * advertising is not active. This method returns immediately, the operation status is delivered 121 * through {@code callback.onAdvertisingParametersUpdated}. 122 * 123 * @param parameters advertising set parameters. 124 */ 125 public void setAdvertisingParameters(AdvertisingSetParameters parameters) { 126 try { 127 mGatt.setAdvertisingParameters(mAdvertiserId, parameters); 128 } catch (RemoteException e) { 129 Log.e(TAG, "remote exception - ", e); 130 } 131 } 132 133 /** 134 * Update periodic advertising parameters associated with this set. Must be called when 135 * periodic advertising is not enabled. This method returns immediately, the operation 136 * status is delivered through {@code callback.onPeriodicAdvertisingParametersUpdated()}. 137 */ 138 public void setPeriodicAdvertisingParameters(PeriodicAdvertisingParameters parameters) { 139 try { 140 mGatt.setPeriodicAdvertisingParameters(mAdvertiserId, parameters); 141 } catch (RemoteException e) { 142 Log.e(TAG, "remote exception - ", e); 143 } 144 } 145 146 /** 147 * Used to set periodic advertising data, must be called after setPeriodicAdvertisingParameters, 148 * or after advertising was started with periodic advertising data set. This method returns 149 * immediately, the operation status is delivered through 150 * {@code callback.onPeriodicAdvertisingDataSet()}. 151 * 152 * @param periodicData Periodic advertising data. Size must not exceed {@link 153 * BluetoothAdapter#getLeMaximumAdvertisingDataLength}. If the update takes place when the 154 * periodic advertising is enabled for this set, the data can be maximum 251 bytes long. 155 */ 156 public void setPeriodicAdvertisingData(AdvertiseData periodicData) { 157 try { 158 mGatt.setPeriodicAdvertisingData(mAdvertiserId, periodicData); 159 } catch (RemoteException e) { 160 Log.e(TAG, "remote exception - ", e); 161 } 162 } 163 164 /** 165 * Used to enable/disable periodic advertising. This method returns immediately, the operation 166 * status is delivered through {@code callback.onPeriodicAdvertisingEnable()}. 167 * 168 * @param enable whether the periodic advertising should be enabled (true), or disabled 169 * (false). 170 */ 171 public void setPeriodicAdvertisingEnabled(boolean enable) { 172 try { 173 mGatt.setPeriodicAdvertisingEnable(mAdvertiserId, enable); 174 } catch (RemoteException e) { 175 Log.e(TAG, "remote exception - ", e); 176 } 177 } 178 179 /** 180 * Returns address associated with this advertising set. 181 * This method is exposed only for Bluetooth PTS tests, no app or system service 182 * should ever use it. 183 * 184 * This method requires {@link android.Manifest.permission#BLUETOOTH_PRIVILEGED} permission. 185 * 186 * @hide 187 */ 188 public void getOwnAddress() { 189 try { 190 mGatt.getOwnAddress(mAdvertiserId); 191 } catch (RemoteException e) { 192 Log.e(TAG, "remote exception - ", e); 193 } 194 } 195 196 /** 197 * Returns advertiserId associated with this advertising set. 198 * 199 * @hide 200 */ 201 public int getAdvertiserId() { 202 return mAdvertiserId; 203 } 204 } 205