1 /* 2 * Copyright 2015, 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 /** 18 * Binder IPC interface for interacting with Bluetooth GATT client-role 19 * features. 20 * TODO(armansito): Not yet supported. 21 */ 22 interface IBluetoothGattClient { 23 /** 24 * Registers a client application with this interface. This creates a unique 25 * GATT client instance for the application. Returns true on success; false 26 * otherwise. If successful, the caller will be assigned a "client_id" which 27 * will be reported asynchronously via 28 * IBluetoothGattClientCallback.onRegistered. This ID is required to make 29 * calls to the functions defined below. 30 */ 31 boolean registerClient(in IBluetoothGattClientCallback callback); 32 33 /** 34 * Unregisters a previously registered client with interface ID |client_id|. 35 */ 36 void unregisterClient(in int client_id); 37 38 /** 39 * Unregisters all previously registered clients. 40 */ 41 void unregisterAll(); 42 43 /** 44 * Refreshes the local client-side attribute cache that mirrors the attribute 45 * database of remote device with address |device_address|. Returns false in 46 * case of an error. |client_id| is the identifier obtained via 47 * registerClient. 48 */ 49 boolean refreshDevice(in int client_id, in String device_address); 50 51 /** 52 * Returns the GATT services, characteristics, and descriptors on the remote 53 * device with address |device_address| asynchronously via the corresponding 54 * IBluetoothGattClientCallback callbacks. Based on the current connection and 55 * bonding state, either GATT service discovery will be initiated or the 56 * results will be returned from the attribute cache. Returns false in case of 57 * an error. |client_id| is the identifier obtained via registerClient. 58 */ 59 boolean discoverServices(in int client_id, in String device_address); 60 61 /** 62 * Initiate a read request for the remote characteristic with identifier 63 * |characteristic_id|. The result will be asynchronously reported in 64 * IBluetoothGattClientCallback.onCharacteristicRead. Returns false if the 65 * request cannot be started, e.g. if a read is already pending on this remote 66 * device. If the read request fails due to characteristic permissions, 67 * this function will try to raise the connection security level based on the 68 * characteristic's permission requirements. If that operation fails, then the 69 * |status| parameter of the onCharacteristicRead callback will contain the 70 * appropriate ATT protocol error code. |client_id| is obtained via 71 * registerClient. 72 */ 73 boolean readCharacteristic(in int client_id, 74 in GattIdentifier characteristic_id); 75 76 /** 77 * Initiate a write request for the remote characteristic with identifier 78 * |characteristic_id| with the value |value|. The |write_type| parameter 79 * indicates which of the following GATT write procedure should be used: 80 * 81 * - WRITE_TYPE_DEFAULT (0x02): Regular Write Procedure 82 * - WRITE_TYPE_NO_RESPONSE (0x01): Write Without Response procedure 83 * - WRITE_TYPE_SIGNED (0x04): Signed Write Without Response procedure. 84 * 85 * The result will be asynchronously reported in 86 * IBluetoothGattClientCallback.onCharacteristicWrite. Returns false if the 87 * request cannot be started. If the write request fails due to attribute 88 * permissions, this function will try to raise the connection security level 89 * based on the characteristic's permission requirements. If that operation 90 * fails, then the |status| parameter of the onCharacteristicWrite callback 91 * will contain the appropriate ATT protocol error code. |client_id| is 92 * obtained via registerClient. 93 */ 94 boolean writeCharacteristic(in int client_id, 95 in GattIdentifier characteristic_id, 96 in int write_type, 97 in byte[] value); 98 99 /** 100 * Initiate a read request for the remote descriptor with identifier 101 * |descriptor_id|. The result will be asynchronously reported in 102 * IBluetoothGattClientCallback.onDescriptorRead. Returns false if the 103 * request cannot be started, e.g. if a read is already pending on this remote 104 * device. If the read request fails due to descriptor permissions, 105 * this function will try to raise the connection security level based on the 106 * descriptor's permission requirements. If that operation fails, then the 107 * |status| parameter of the onDescriptorRead callback will contain the 108 * appropriate ATT protocol error code. |client_id| is obtained via 109 * registerClient. 110 */ 111 boolean readDescriptor(in int client_id, 112 in GattIdentifier descriptor_id); 113 114 /** 115 * Initiate a write request for the remote descriptor with identifier 116 * |descriptor_id| with the value |value|. The |write_type| parameter 117 * indicates which of the following GATT write procedure should be used: 118 * 119 * - WRITE_TYPE_DEFAULT (0x02): Regular write procedure 120 * - WRITE_TYPE_NO_RESPONSE (0x01): Write without response procedure 121 * - WRITE_TYPE_SIGNED (0x04): Authenticated-signed write procedure 122 * 123 * The result will be asynchronously reported in 124 * IBluetoothGattClientCallback.onDescriptorWrite. Returns false if the 125 * request cannot be started. If the write request fails due to attribute 126 * permissions, this function will try to raise the connection security level 127 * based on the descriptor's permission requirements. If that operation fails, 128 * then the |status| parameter of the onDescriptorWrite callback will contain 129 * the appropriate ATT protocol error code. |client_id| is obtained via 130 * registerClient. 131 */ 132 boolean writeDescriptor(in int client_id, 133 in GattIdentifier descriptor_id, 134 in int write_type, 135 in byte[] value); 136 137 /** 138 * Enables handle-value notifications from the remote characteristic with ID 139 * |characteristic_id|. If successful, notifications will be signaled via 140 * IBluetoothGattClientCallback.onNotify. Returns false if the request cannot 141 * be initiated. |client_id| is obtained via registerClient. 142 */ 143 boolean registerForNotifications(in int client_id, 144 in GattIdentifier characteristic_id); 145 146 /** 147 * Disables handle-value notifications from the remote characteristic with ID 148 * |characteristic_id|. Returns false if the request cannot be initiated, e.g. 149 * if notifications from this characteristic have not been enabled. 150 * |client_id| is obtained via registerClient. 151 */ 152 boolean unregisterForNotifications(in int client_id, 153 in GattIdentifier characteristic_id); 154 155 /** 156 * Initiates a reliable write procedure for the remote device with address 157 * |device_address|. Once a reliable write transaction has been initiated, all 158 * calls to writeCharacteristic are sent to the remote device for verification 159 * and queued up for atomic execution. The application can verify each write 160 * payload using the IBluetoothGattClientCallback.onCharacteristicWrite 161 * callback and abort reliable write in case of a mismatch. The queued writes 162 * will be processed atomically by the remote device after calling 163 * endReliableWrite. Returns false if the procedure cannot be started, e.g. if 164 * it has already been started earlier. |client_id| is obtained via 165 * registerClient. 166 */ 167 boolean beginReliableWrite(in int client_id, in String device_address); 168 169 /** 170 * Ends a previously started reliable write procedure for the remote device 171 * with address |device_address|. If |execute| is true, then a request will be 172 * sent to execute the queued writes, else a request will be sent to abort the 173 * queued writes. Returns false in case of a failure, e.g. if a reliable write 174 * procedure was not started. IBluetoothGattClientCallback.onExecuteWrite will 175 * be used to asynchronously report the result of the execute write request. 176 * |client_id| is obtained via registerClient. 177 */ 178 boolean endReliableWrite(in int client_id, in String device_address, 179 in boolean execute); 180 } 181
