public final class BluetoothGatt
extends Object implements BluetoothProfile
| java.lang.Object | |
| ↳ | android.bluetooth.BluetoothGatt |
蓝牙GATT配置文件的公共API。
该课程提供蓝牙GATT功能，以实现与蓝牙智能或智能就绪设备的通信。
要连接到远程外围设备，请创建一个BluetoothGattCallback并致电connectGatt(Context, boolean, BluetoothGattCallback)以获取此类的实例。 使用蓝牙设备发现或BLE扫描过程可以发现支持GATT的设备。
Constants |
|
|---|---|
int |
CONNECTION_PRIORITY_BALANCED 连接参数更新 - 使用Bluetooth SIG推荐的连接参数。 |
int |
CONNECTION_PRIORITY_HIGH 连接参数更新 - 请求高优先级，低延迟连接。 |
int |
CONNECTION_PRIORITY_LOW_POWER 连接参数更新 - 请求低功耗，降低数据速率连接参数。 |
int |
GATT_CONNECTION_CONGESTED 远程设备连接拥塞。 |
int |
GATT_FAILURE GATT操作失败，除上述以外的错误 |
int |
GATT_INSUFFICIENT_AUTHENTICATION 给定操作的认证不足 |
int |
GATT_INSUFFICIENT_ENCRYPTION 给定操作的加密不足 |
int |
GATT_INVALID_ATTRIBUTE_LENGTH 写操作超过了属性的最大长度 |
int |
GATT_INVALID_OFFSET 请求读取或写入操作的偏移量无效 |
int |
GATT_READ_NOT_PERMITTED GATT读取操作不被允许 |
int |
GATT_REQUEST_NOT_SUPPORTED 给定的请求不受支持 |
int |
GATT_SUCCESS GATT操作成功完成 |
int |
GATT_WRITE_NOT_PERMITTED GATT写入操作是不允许的 |
Inherited constants |
|---|
 From interface android.bluetooth.BluetoothProfile
|
Inherited methods |
|
|---|---|
From class java.lang.Object
|
|
From interface android.bluetooth.BluetoothProfile
|
|
int CONNECTION_PRIORITY_BALANCED
连接参数更新 - 使用Bluetooth SIG推荐的连接参数。 如果没有请求连接参数更新，这是默认值。
常量值：0（0x00000000）
int CONNECTION_PRIORITY_HIGH
连接参数更新 - 请求高优先级，低延迟连接。 应用程序只能请求高优先级的连接参数，以便快速通过LE传输大量数据。 一旦传输完成，应用程序应该请求CONNECTION_PRIORITY_BALANCED connectoin参数以减少能源使用。
常数值：1（0x00000001）
int CONNECTION_PRIORITY_LOW_POWER
连接参数更新 - 请求低功耗，降低数据速率连接参数。
常量值：2（0x00000002）
int GATT_CONNECTION_CONGESTED
远程设备连接拥塞。
常量值：143（0x0000008f）
int GATT_INSUFFICIENT_AUTHENTICATION
给定操作的认证不足
常量值：5（0x00000005）
int GATT_INSUFFICIENT_ENCRYPTION
给定操作的加密不足
常量值：15（0x0000000f）
int GATT_INVALID_ATTRIBUTE_LENGTH
写操作超过了属性的最大长度
常量值：13（0x0000000d）
int GATT_READ_NOT_PERMITTED
GATT读取操作不被允许
常量值：2（0x00000002）
int GATT_REQUEST_NOT_SUPPORTED
给定的请求不受支持
常数值：6（0x00000006）
int GATT_WRITE_NOT_PERMITTED
GATT写入操作是不允许的
常量值：3（0x00000003）
void abortReliableWrite (BluetoothDevice mDevice)
此方法在API级别19中已被弃用。
使用abortReliableWrite()
| Parameters | |
|---|---|
mDevice |
BluetoothDevice
|
void abortReliableWrite ()
取消给定设备的可靠写入事务。
调用此函数将放弃给定远程设备的所有排队特征写入操作。
需要 BLUETOOTH权限。
boolean beginReliableWrite ()
为给定的远程设备启动可靠的写入事务。
一旦启动了可靠的写入事务，所有对writeCharacteristic(BluetoothGattCharacteristic)调用都将被发送到远程设备进行验证并排队等候原子执行。 响应每writeCharacteristic(BluetoothGattCharacteristic)呼叫，应用程序将收到一个onCharacteristicWrite(BluetoothGatt, BluetoothGattCharacteristic, int)回叫，并负责验证该值是否已准确传送。
在所有特征排队并验证后， executeReliableWrite()将执行所有写操作。 如果特性写入不正确，调用abortReliableWrite()将取消当前事务，而不在远程设备上提交任何值。
需要 BLUETOOTH权限。
| Returns | |
|---|---|
boolean |
true, if the reliable write transaction has been initiated |
boolean connect ()
连接回远程设备。
在连接断开后，此方法用于重新连接到远程设备。 如果设备不在范围内，则一旦设备回到范围内，将会触发重新连接。
| Returns | |
|---|---|
boolean |
true, if the connection attempt was initiated successfully |
boolean discoverServices ()
发现远程设备提供的服务及其特征和描述符。
这是一个异步操作。 服务发现完成后，将触发onServicesDiscovered(BluetoothGatt, int)回调。 如果发现成功，则可以使用getServices()函数检索远程服务。
需要 BLUETOOTH权限。
| Returns | |
|---|---|
boolean |
true, if the remote service discovery has been started |
boolean executeReliableWrite ()
为给定的远程设备执行可靠的写入事务。
该功能将为给定的远程设备提交所有排队的特征写入操作。
调用 onReliableWriteCompleted(BluetoothGatt, int)回调以指示事务是否已正确执行。
需要 BLUETOOTH权限。
| Returns | |
|---|---|
boolean |
true, if the request to execute the transaction has been sent |
List<BluetoothDevice> getConnectedDevices ()
不支持 - 请使用 getConnectedDevices(int)和 GATT作为参数
| Returns | |
|---|---|
List<BluetoothDevice> |
List of devices. The list will be empty on error. |
| Throws | |
|---|---|
UnsupportedOperationException |
|
int getConnectionState (BluetoothDevice device)
不支持 - 请使用 getConnectedDevices(int)和 GATT作为参数
| Parameters | |
|---|---|
device |
BluetoothDevice: Remote bluetooth device. |
| Returns | |
|---|---|
int |
State of the profile connection. One of STATE_CONNECTED, STATE_CONNECTING, STATE_DISCONNECTED, STATE_DISCONNECTING |
| Throws | |
|---|---|
UnsupportedOperationException |
|
BluetoothDevice getDevice ()
返回此GATT客户端所针对的远程蓝牙设备
| Returns | |
|---|---|
BluetoothDevice |
remote bluetooth device |
List<BluetoothDevice> getDevicesMatchingConnectionStates (int[] states)
不支持 - 请使用 getDevicesMatchingConnectionStates(int, int[])和 GATT作为第一个参数
| Parameters | |
|---|---|
states |
int: Array of states. States can be one of STATE_CONNECTED, STATE_CONNECTING, STATE_DISCONNECTED, STATE_DISCONNECTING, |
| Returns | |
|---|---|
List<BluetoothDevice> |
List of devices. The list will be empty on error. |
| Throws | |
|---|---|
UnsupportedOperationException |
|
BluetoothGattService getService (UUID uuid)
如果请求的UUID被远程设备支持，则返回 BluetoothGattService 。
此功能要求已完成给定设备的服务发现。
如果存在同一服务的多个实例（由UUID标识），则返回服务的第一个实例。
需要 BLUETOOTH权限。
| Parameters | |
|---|---|
uuid |
UUID: UUID of the requested service |
| Returns | |
|---|---|
BluetoothGattService |
BluetoothGattService if supported, or null if the requested service is not offered by the remote device. |
List<BluetoothGattService> getServices ()
返回远程设备提供的GATT服务列表。
此功能要求已完成给定设备的服务发现。
需要 BLUETOOTH权限。
| Returns | |
|---|---|
List<BluetoothGattService> |
List of services on the remote device. Returns an empty list if service discovery has not yet been performed. |
boolean readCharacteristic (BluetoothGattCharacteristic characteristic)
从关联的远程设备读取请求的特征。
这是一个异步操作。 读取操作的结果由onCharacteristicRead(BluetoothGatt, BluetoothGattCharacteristic, int)回调报告。
需要 BLUETOOTH权限。
| Parameters | |
|---|---|
characteristic |
BluetoothGattCharacteristic: Characteristic to read from the remote device |
| Returns | |
|---|---|
boolean |
true, if the read operation was initiated successfully |
boolean readDescriptor (BluetoothGattDescriptor descriptor)
从关联的远程设备读取给定描述符的值。
一旦读取操作完成，触发 onDescriptorRead(BluetoothGatt, BluetoothGattDescriptor, int)回调，表示操作的结果。
需要 BLUETOOTH权限。
| Parameters | |
|---|---|
descriptor |
BluetoothGattDescriptor: Descriptor value to read from the remote device |
| Returns | |
|---|---|
boolean |
true, if the read operation was initiated successfully |
boolean readRemoteRssi ()
读取连接的远程设备的RSSI。
当RSSI值被读取时， onReadRemoteRssi(BluetoothGatt, int, int)回调将被调用。
需要 BLUETOOTH权限。
| Returns | |
|---|---|
boolean |
true, if the RSSI value has been requested successfully |
boolean requestConnectionPriority (int connectionPriority)
请求连接参数更新。
该功能将向远程设备发送连接参数更新请求。
| Parameters | |
|---|---|
connectionPriority |
int: Request a specific connection priority. Must be one of CONNECTION_PRIORITY_BALANCED, CONNECTION_PRIORITY_HIGH or CONNECTION_PRIORITY_LOW_POWER. |
| Returns | |
|---|---|
boolean |
|
| Throws | |
|---|---|
IllegalArgumentException |
If the parameters are outside of their specified range. |
boolean requestMtu (int mtu)
请求用于给定连接的MTU大小。
当执行写入请求操作（无响应写入）时，发送的数据被截断为MTU大小。 该功能可用于请求更大的MTU大小以便能够一次发送更多数据。
onMtuChanged(BluetoothGatt, int, int)回调将指示此操作是否成功。
需要 BLUETOOTH权限。
| Parameters | |
|---|---|
mtu |
int
|
| Returns | |
|---|---|
boolean |
true, if the new MTU value has been requested successfully |
boolean setCharacteristicNotification (BluetoothGattCharacteristic characteristic, boolean enable)
启用或禁用给定特征的通知/指示。
一旦为特征启用通知，如果远程设备指示给定特征已更改，则将触发 onCharacteristicChanged(BluetoothGatt, BluetoothGattCharacteristic)回调。
需要 BLUETOOTH权限。
| Parameters | |
|---|---|
characteristic |
BluetoothGattCharacteristic: The characteristic for which to enable notifications |
enable |
boolean: Set to true to enable notifications/indications |
| Returns | |
|---|---|
boolean |
true, if the requested notification status was set successfully |
boolean writeCharacteristic (BluetoothGattCharacteristic characteristic)
将给定的特性及其值写入关联的远程设备。
一旦写入操作完成，将调用 onCharacteristicWrite(BluetoothGatt, BluetoothGattCharacteristic, int)回调函数，报告操作的结果。
需要 BLUETOOTH权限。
| Parameters | |
|---|---|
characteristic |
BluetoothGattCharacteristic: Characteristic to write on the remote device |
| Returns | |
|---|---|
boolean |
true, if the write operation was initiated successfully |
boolean writeDescriptor (BluetoothGattDescriptor descriptor)
将给定描述符的值写入关联的远程设备。
触发一个 onDescriptorWrite(BluetoothGatt, BluetoothGattDescriptor, int)回调来报告写入操作的结果。
需要 BLUETOOTH权限。
| Parameters | |
|---|---|
descriptor |
BluetoothGattDescriptor: Descriptor to write to the associated remote device |
| Returns | |
|---|---|
boolean |
true, if the write operation was initiated successfully |
Android开发手册