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; 18 19 import android.annotation.NonNull; 20 21 /** This abstract class is used to implement {@link BluetoothGatt} callbacks. */ 22 public abstract class BluetoothGattCallback { 23 24 /** 25 * Callback triggered as result of {@link BluetoothGatt#setPreferredPhy}, or as a result of 26 * remote device changing the PHY. 27 * 28 * @param gatt GATT client 29 * @param txPhy the transmitter PHY in use. One of {@link BluetoothDevice#PHY_LE_1M}, {@link 30 * BluetoothDevice#PHY_LE_2M}, and {@link BluetoothDevice#PHY_LE_CODED}. 31 * @param rxPhy the receiver PHY in use. One of {@link BluetoothDevice#PHY_LE_1M}, {@link 32 * BluetoothDevice#PHY_LE_2M}, and {@link BluetoothDevice#PHY_LE_CODED}. 33 * @param status Status of the PHY update operation. {@link BluetoothGatt#GATT_SUCCESS} if the 34 * operation succeeds. 35 */ onPhyUpdate(BluetoothGatt gatt, int txPhy, int rxPhy, int status)36 public void onPhyUpdate(BluetoothGatt gatt, int txPhy, int rxPhy, int status) {} 37 38 /** 39 * Callback triggered as result of {@link BluetoothGatt#readPhy} 40 * 41 * @param gatt GATT client 42 * @param txPhy the transmitter PHY in use. One of {@link BluetoothDevice#PHY_LE_1M}, {@link 43 * BluetoothDevice#PHY_LE_2M}, and {@link BluetoothDevice#PHY_LE_CODED}. 44 * @param rxPhy the receiver PHY in use. One of {@link BluetoothDevice#PHY_LE_1M}, {@link 45 * BluetoothDevice#PHY_LE_2M}, and {@link BluetoothDevice#PHY_LE_CODED}. 46 * @param status Status of the PHY read operation. {@link BluetoothGatt#GATT_SUCCESS} if the 47 * operation succeeds. 48 */ onPhyRead(BluetoothGatt gatt, int txPhy, int rxPhy, int status)49 public void onPhyRead(BluetoothGatt gatt, int txPhy, int rxPhy, int status) {} 50 51 /** 52 * Callback indicating when GATT client has connected/disconnected to/from a remote GATT server. 53 * 54 * @param gatt GATT client 55 * @param status Status of the connect or disconnect operation. {@link 56 * BluetoothGatt#GATT_SUCCESS} if the operation succeeds. 57 * @param newState Returns the new connection state. Can be one of {@link 58 * BluetoothProfile#STATE_DISCONNECTED} or {@link BluetoothProfile#STATE_CONNECTED} 59 */ onConnectionStateChange(BluetoothGatt gatt, int status, int newState)60 public void onConnectionStateChange(BluetoothGatt gatt, int status, int newState) {} 61 62 /** 63 * Callback invoked when the list of remote services, characteristics and descriptors for the 64 * remote device have been updated, ie new services have been discovered. 65 * 66 * @param gatt GATT client invoked {@link BluetoothGatt#discoverServices} 67 * @param status {@link BluetoothGatt#GATT_SUCCESS} if the remote device has been explored 68 * successfully. 69 */ onServicesDiscovered(BluetoothGatt gatt, int status)70 public void onServicesDiscovered(BluetoothGatt gatt, int status) {} 71 72 /** 73 * Callback reporting the result of a characteristic read operation. 74 * 75 * @param gatt GATT client invoked {@link 76 * BluetoothGatt#readCharacteristic(BluetoothGattCharacteristic)} 77 * @param characteristic Characteristic that was read from the associated remote device. 78 * @param status {@link BluetoothGatt#GATT_SUCCESS} if the read operation was completed 79 * successfully. 80 * @deprecated Use {@link BluetoothGattCallback#onCharacteristicRead(BluetoothGatt, 81 * BluetoothGattCharacteristic, byte[], int)} as it is memory safe 82 */ 83 @Deprecated onCharacteristicRead( BluetoothGatt gatt, BluetoothGattCharacteristic characteristic, int status)84 public void onCharacteristicRead( 85 BluetoothGatt gatt, BluetoothGattCharacteristic characteristic, int status) {} 86 87 /** 88 * Callback reporting the result of a characteristic read operation. 89 * 90 * @param gatt GATT client invoked {@link 91 * BluetoothGatt#readCharacteristic(BluetoothGattCharacteristic)} 92 * @param characteristic Characteristic that was read from the associated remote device. 93 * @param value the value of the characteristic 94 * @param status {@link BluetoothGatt#GATT_SUCCESS} if the read operation was completed 95 * successfully. 96 */ onCharacteristicRead( @onNull BluetoothGatt gatt, @NonNull BluetoothGattCharacteristic characteristic, @NonNull byte[] value, int status)97 public void onCharacteristicRead( 98 @NonNull BluetoothGatt gatt, 99 @NonNull BluetoothGattCharacteristic characteristic, 100 @NonNull byte[] value, 101 int status) { 102 onCharacteristicRead(gatt, characteristic, status); 103 } 104 105 /** 106 * Callback indicating the result of a characteristic write operation. 107 * 108 * <p>If this callback is invoked while a reliable write transaction is in progress, the value 109 * of the characteristic represents the value reported by the remote device. An application 110 * should compare this value to the desired value to be written. If the values don't match, the 111 * application must abort the reliable write transaction. 112 * 113 * @param gatt GATT client that invoked {@link 114 * BluetoothGatt#writeCharacteristic(BluetoothGattCharacteristic, byte[], int)} 115 * @param characteristic Characteristic that was written to the associated remote device. 116 * @param status The result of the write operation {@link BluetoothGatt#GATT_SUCCESS} if the 117 * operation succeeds. 118 */ onCharacteristicWrite( BluetoothGatt gatt, BluetoothGattCharacteristic characteristic, int status)119 public void onCharacteristicWrite( 120 BluetoothGatt gatt, BluetoothGattCharacteristic characteristic, int status) {} 121 122 /** 123 * Callback triggered as a result of a remote characteristic notification. 124 * 125 * @param gatt GATT client the characteristic is associated with 126 * @param characteristic Characteristic that has been updated as a result of a remote 127 * notification event. 128 * @deprecated Use {@link BluetoothGattCallback#onCharacteristicChanged(BluetoothGatt, 129 * BluetoothGattCharacteristic, byte[])} as it is memory safe by providing the 130 * characteristic value at the time of notification. 131 */ 132 @Deprecated onCharacteristicChanged( BluetoothGatt gatt, BluetoothGattCharacteristic characteristic)133 public void onCharacteristicChanged( 134 BluetoothGatt gatt, BluetoothGattCharacteristic characteristic) {} 135 136 /** 137 * Callback triggered as a result of a remote characteristic notification. Note that the value 138 * within the characteristic object may have changed since receiving the remote characteristic 139 * notification, so check the parameter value for the value at the time of notification. 140 * 141 * @param gatt GATT client the characteristic is associated with 142 * @param characteristic Characteristic that has been updated as a result of a remote 143 * notification event. 144 * @param value notified characteristic value 145 */ onCharacteristicChanged( @onNull BluetoothGatt gatt, @NonNull BluetoothGattCharacteristic characteristic, @NonNull byte[] value)146 public void onCharacteristicChanged( 147 @NonNull BluetoothGatt gatt, 148 @NonNull BluetoothGattCharacteristic characteristic, 149 @NonNull byte[] value) { 150 onCharacteristicChanged(gatt, characteristic); 151 } 152 153 /** 154 * Callback reporting the result of a descriptor read operation. 155 * 156 * @param gatt GATT client invoked {@link BluetoothGatt#readDescriptor} 157 * @param descriptor Descriptor that was read from the associated remote device. 158 * @param status {@link BluetoothGatt#GATT_SUCCESS} if the read operation was completed 159 * successfully 160 * @deprecated Use {@link BluetoothGattCallback#onDescriptorRead(BluetoothGatt, 161 * BluetoothGattDescriptor, int, byte[])} as it is memory safe by providing the descriptor 162 * value at the time it was read. 163 */ 164 @Deprecated onDescriptorRead( BluetoothGatt gatt, BluetoothGattDescriptor descriptor, int status)165 public void onDescriptorRead( 166 BluetoothGatt gatt, BluetoothGattDescriptor descriptor, int status) {} 167 168 /** 169 * Callback reporting the result of a descriptor read operation. 170 * 171 * @param gatt GATT client invoked {@link BluetoothGatt#readDescriptor} 172 * @param descriptor Descriptor that was read from the associated remote device. 173 * @param status {@link BluetoothGatt#GATT_SUCCESS} if the read operation was completed 174 * successfully 175 * @param value the descriptor value at the time of the read operation 176 */ onDescriptorRead( @onNull BluetoothGatt gatt, @NonNull BluetoothGattDescriptor descriptor, int status, @NonNull byte[] value)177 public void onDescriptorRead( 178 @NonNull BluetoothGatt gatt, 179 @NonNull BluetoothGattDescriptor descriptor, 180 int status, 181 @NonNull byte[] value) { 182 onDescriptorRead(gatt, descriptor, status); 183 } 184 185 /** 186 * Callback indicating the result of a descriptor write operation. 187 * 188 * @param gatt GATT client invoked {@link BluetoothGatt#writeDescriptor} 189 * @param descriptor Descriptor that was written to the associated remote device. 190 * @param status The result of the write operation {@link BluetoothGatt#GATT_SUCCESS} if the 191 * operation succeeds. 192 */ onDescriptorWrite( BluetoothGatt gatt, BluetoothGattDescriptor descriptor, int status)193 public void onDescriptorWrite( 194 BluetoothGatt gatt, BluetoothGattDescriptor descriptor, int status) {} 195 196 /** 197 * Callback invoked when a reliable write transaction has been completed. 198 * 199 * @param gatt GATT client invoked {@link BluetoothGatt#executeReliableWrite} 200 * @param status {@link BluetoothGatt#GATT_SUCCESS} if the reliable write transaction was 201 * executed successfully 202 */ onReliableWriteCompleted(BluetoothGatt gatt, int status)203 public void onReliableWriteCompleted(BluetoothGatt gatt, int status) {} 204 205 /** 206 * Callback reporting the RSSI for a remote device connection. 207 * 208 * <p>This callback is triggered in response to the {@link BluetoothGatt#readRemoteRssi} 209 * function. 210 * 211 * @param gatt GATT client invoked {@link BluetoothGatt#readRemoteRssi} 212 * @param rssi The RSSI value for the remote device 213 * @param status {@link BluetoothGatt#GATT_SUCCESS} if the RSSI was read successfully 214 */ onReadRemoteRssi(BluetoothGatt gatt, int rssi, int status)215 public void onReadRemoteRssi(BluetoothGatt gatt, int rssi, int status) {} 216 217 /** 218 * Callback indicating the MTU for a given device connection has changed. 219 * 220 * <p>This callback is triggered in response to the {@link BluetoothGatt#requestMtu} function, 221 * or in response to a connection event. 222 * 223 * @param gatt GATT client invoked {@link BluetoothGatt#requestMtu} 224 * @param mtu The new MTU size 225 * @param status {@link BluetoothGatt#GATT_SUCCESS} if the MTU has been changed successfully 226 */ onMtuChanged(BluetoothGatt gatt, int mtu, int status)227 public void onMtuChanged(BluetoothGatt gatt, int mtu, int status) {} 228 229 /** 230 * Callback indicating the connection parameters were updated. 231 * 232 * @param gatt GATT client involved 233 * @param interval Connection interval used on this connection, 1.25ms unit. Valid range is from 234 * 6 (7.5ms) to 3200 (4000ms). 235 * @param latency Worker latency for the connection in number of connection events. Valid range 236 * is from 0 to 499 237 * @param timeout Supervision timeout for this connection, in 10ms unit. Valid range is from 10 238 * (0.1s) to 3200 (32s) 239 * @param status {@link BluetoothGatt#GATT_SUCCESS} if the connection has been updated 240 * successfully 241 * @hide 242 */ onConnectionUpdated( BluetoothGatt gatt, int interval, int latency, int timeout, int status)243 public void onConnectionUpdated( 244 BluetoothGatt gatt, int interval, int latency, int timeout, int status) {} 245 246 /** 247 * Callback indicating service changed event is received 248 * 249 * <p>Receiving this event means that the GATT database is out of sync with the remote device. 250 * {@link BluetoothGatt#discoverServices} should be called to re-discover the services. 251 * 252 * @param gatt GATT client involved 253 */ onServiceChanged(@onNull BluetoothGatt gatt)254 public void onServiceChanged(@NonNull BluetoothGatt gatt) {} 255 256 /** 257 * Callback indicating LE connection's subrate parameters have changed. 258 * 259 * @param gatt GATT client involved 260 * @param subrateFactor for the LE connection. 261 * @param latency Worker latency for the connection in number of connection events. Valid range 262 * is from 0 to 499 263 * @param contNum Valid range is from 0 to 499. 264 * @param timeout Supervision timeout for this connection, in 10ms unit. Valid range is from 10 265 * (0.1s) to 3200 (32s) 266 * @param status {@link BluetoothGatt#GATT_SUCCESS} if LE connection subrating has been changed 267 * successfully. 268 * @hide 269 */ onSubrateChange( BluetoothGatt gatt, int subrateFactor, int latency, int contNum, int timeout, int status)270 public void onSubrateChange( 271 BluetoothGatt gatt, 272 int subrateFactor, 273 int latency, 274 int contNum, 275 int timeout, 276 int status) {} 277 } 278