1/*
2 * Copyright (C) 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 */
22interface 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