/* * Copyright (C) 2015, 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. */ /** * Binder IPC interface for interacting with Bluetooth GATT client-role * features. * TODO(armansito): Not yet supported. */ interface IBluetoothGattClient { /** * Registers a client application with this interface. This creates a unique * GATT client instance for the application. Returns true on success; false * otherwise. If successful, the caller will be assigned a "client_id" which * will be reported asynchronously via * IBluetoothGattClientCallback.onRegistered. This ID is required to make * calls to the functions defined below. */ boolean registerClient(in IBluetoothGattClientCallback callback); /** * Unregisters a previously registered client with interface ID |client_id|. */ void unregisterClient(in int client_id); /** * Unregisters all previously registered clients. */ void unregisterAll(); /** * Refreshes the local client-side attribute cache that mirrors the attribute * database of remote device with address |device_address|. Returns false in * case of an error. |client_id| is the identifier obtained via * registerClient. */ boolean refreshDevice(in int client_id, in String device_address); /** * Returns the GATT services, characteristics, and descriptors on the remote * device with address |device_address| asynchronously via the corresponding * IBluetoothGattClientCallback callbacks. Based on the current connection and * bonding state, either GATT service discovery will be initiated or the * results will be returned from the attribute cache. Returns false in case of * an error. |client_id| is the identifier obtained via registerClient. */ boolean discoverServices(in int client_id, in String device_address); /** * Initiate a read request for the remote characteristic with identifier * |characteristic_id|. The result will be asynchronously reported in * IBluetoothGattClientCallback.onCharacteristicRead. Returns false if the * request cannot be started, e.g. if a read is already pending on this remote * device. If the read request fails due to characteristic permissions, * this function will try to raise the connection security level based on the * characteristic's permission requirements. If that operation fails, then the * |status| parameter of the onCharacteristicRead callback will contain the * appropriate ATT protocol error code. |client_id| is obtained via * registerClient. */ boolean readCharacteristic(in int client_id, in GattIdentifier characteristic_id); /** * Initiate a write request for the remote characteristic with identifier * |characteristic_id| with the value |value|. The |write_type| parameter * indicates which of the following GATT write procedure should be used: * * - WRITE_TYPE_DEFAULT (0x02): Regular Write Procedure * - WRITE_TYPE_NO_RESPONSE (0x01): Write Without Response procedure * - WRITE_TYPE_SIGNED (0x04): Signed Write Without Response procedure. * * The result will be asynchronously reported in * IBluetoothGattClientCallback.onCharacteristicWrite. Returns false if the * request cannot be started. If the write request fails due to attribute * permissions, this function will try to raise the connection security level * based on the characteristic's permission requirements. If that operation * fails, then the |status| parameter of the onCharacteristicWrite callback * will contain the appropriate ATT protocol error code. |client_id| is * obtained via registerClient. */ boolean writeCharacteristic(in int client_id, in GattIdentifier characteristic_id, in int write_type, in byte[] value); /** * Initiate a read request for the remote descriptor with identifier * |descriptor_id|. The result will be asynchronously reported in * IBluetoothGattClientCallback.onDescriptorRead. Returns false if the * request cannot be started, e.g. if a read is already pending on this remote * device. If the read request fails due to descriptor permissions, * this function will try to raise the connection security level based on the * descriptor's permission requirements. If that operation fails, then the * |status| parameter of the onDescriptorRead callback will contain the * appropriate ATT protocol error code. |client_id| is obtained via * registerClient. */ boolean readDescriptor(in int client_id, in GattIdentifier descriptor_id); /** * Initiate a write request for the remote descriptor with identifier * |descriptor_id| with the value |value|. The |write_type| parameter * indicates which of the following GATT write procedure should be used: * * - WRITE_TYPE_DEFAULT (0x02): Regular write procedure * - WRITE_TYPE_NO_RESPONSE (0x01): Write without response procedure * - WRITE_TYPE_SIGNED (0x04): Authenticated-signed write procedure * * The result will be asynchronously reported in * IBluetoothGattClientCallback.onDescriptorWrite. Returns false if the * request cannot be started. If the write request fails due to attribute * permissions, this function will try to raise the connection security level * based on the descriptor's permission requirements. If that operation fails, * then the |status| parameter of the onDescriptorWrite callback will contain * the appropriate ATT protocol error code. |client_id| is obtained via * registerClient. */ boolean writeDescriptor(in int client_id, in GattIdentifier descriptor_id, in int write_type, in byte[] value); /** * Enables handle-value notifications from the remote characteristic with ID * |characteristic_id|. If successful, notifications will be signaled via * IBluetoothGattClientCallback.onNotify. Returns false if the request cannot * be initiated. |client_id| is obtained via registerClient. */ boolean registerForNotifications(in int client_id, in GattIdentifier characteristic_id); /** * Disables handle-value notifications from the remote characteristic with ID * |characteristic_id|. Returns false if the request cannot be initiated, e.g. * if notifications from this characteristic have not been enabled. * |client_id| is obtained via registerClient. */ boolean unregisterForNotifications(in int client_id, in GattIdentifier characteristic_id); /** * Initiates a reliable write procedure for the remote device with address * |device_address|. Once a reliable write transaction has been initiated, all * calls to writeCharacteristic are sent to the remote device for verification * and queued up for atomic execution. The application can verify each write * payload using the IBluetoothGattClientCallback.onCharacteristicWrite * callback and abort reliable write in case of a mismatch. The queued writes * will be processed atomically by the remote device after calling * endReliableWrite. Returns false if the procedure cannot be started, e.g. if * it has already been started earlier. |client_id| is obtained via * registerClient. */ boolean beginReliableWrite(in int client_id, in String device_address); /** * Ends a previously started reliable write procedure for the remote device * with address |device_address|. If |execute| is true, then a request will be * sent to execute the queued writes, else a request will be sent to abort the * queued writes. Returns false in case of a failure, e.g. if a reliable write * procedure was not started. IBluetoothGattClientCallback.onExecuteWrite will * be used to asynchronously report the result of the execute write request. * |client_id| is obtained via registerClient. */ boolean endReliableWrite(in int client_id, in String device_address, in boolean execute); }