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 server-role
19 * features.
20 */
21interface IBluetoothGattServer {
22  /**
23   * Registers a client application with this interface. This creates a unique
24   * GATT server instance for the application that will contain the GATT
25   * services belonging to the calling application. A special interface ID will
26   * be returned in a callback to the application that can be used to perform
27   * GATT server operations. Returns false in case of an error.
28   */
29  boolean registerServer(in IBluetoothGattServerCallback callback);
30
31  /**
32   * Unregisters a previously registered server with interface ID |server_if|.
33   */
34  void unregisterServer(in int server_if);
35
36  /**
37   * Unregisters all previously registered servers.
38   */
39  void unregisterAll();
40
41  /**
42   * Begins a new GATT service declaration. This will execute synchronously and
43   * create a new service range. This can be followed by calls to populate the
44   * service range with attributes. The started service won't be published and
45   * made discoverable to remote devices until a successful call to
46   * endServiceDeclaration.
47   *
48   * The created service will be assigned a unique identifier that can be used
49   * by the caller to distinguish between different services. This will be
50   * returned in |out_id| in case of success. Returns false in case of failure,
51   * e.g. a service declaration is already in progress.
52   */
53  boolean beginServiceDeclaration(in int server_if, in boolean is_primary,
54                                  in ParcelUuid uuid,
55                                  out GattIdentifier out_id);
56
57  /**
58   * Adds a characteristic entry to a previously started service declaration.
59   * Returns false in case of failure, e.g. if no service declaration was
60   * started. Returns the uniquely assigned characteristic identifier in
61   * |out_id| in the case of success.
62   */
63  boolean addCharacteristic(in int server_if, in ParcelUuid uuid,
64                            in int properties, in int permissions,
65                            out GattIdentifier out_id);
66
67  /**
68   * Adds a characteristic descriptor entry to a previously started service
69   * declaration. Returns false in case of failure, e.g. if no service
70   * declaration was started or if the declaration does not contain a
71   * characteristic that can own this descriptor. Returns the uniquely assigned
72   * descriptor identifier in |out_id| in the case of success.
73   */
74  boolean addDescriptor(in int server_if, in ParcelUuid uuid,
75                        in int permissions,
76                        out GattIdentifier out_id);
77
78  /**
79   * Ends a previously started service declaration and asynchronously publishes
80   * the service in the underlying attribute database. Returns false in case of
81   * an asynchronous failure, e.g. if no service declaration was started or
82   * there is a pending call to endServiceDeclaration. Otherwise returns true
83   * and reports the result of the operation asynchronously in
84   * IBluetoothGattServerCallback.onServiceAdded.
85   */
86  boolean endServiceDeclaration(in int server_if);
87
88  /**
89   * Sends a response to a currently pending read or write request. The request
90   * will be propagated to the application via IBluetoothGattServerCallback with
91   * a unique |request_id| which must be passed to this method along with the
92   * |device_address| of the device that the request originated from.
93   *
94   * The |status| field should contain the result of the operation. In the case
95   * of success, the application should pass in "0". Otherwise this should
96   * contain an ATT protocol error code.
97   */
98  boolean sendResponse(in int server_if, in String device_address,
99                       in int request_id, in int status,
100                       in int offset, in byte[] value);
101
102  /**
103   * Sends a handle-value notification or indication to the device with the
104   * given address for the characteristic with the given identifier. |confirm|
105   * should be set to true, if a handle-value indication should be sent, which
106   * will remain pending until the remote device sends a handle-value
107   * confirmation. Returns false if a call to this method is pending. Otherwise
108   * reports the result asynchronously in
109   * IBluetoothGattServerCallback.onNotificationSent.
110   */
111  boolean sendNotification(in int server_if, in String device_address,
112                           in GattIdentifier characteristic_id,
113                           in boolean confirm, in byte[] value);
114}
115