service: Added Binder API documentation
Added the service/doc directory with documentation for the
currently supported Binder interfaces in AIDL format.
Change-Id: I81bec12b7da7fbee110b1df0ffafcc3dc7d6eec3
diff --git a/system/service/doc/IBluetooth.txt b/system/service/doc/IBluetooth.txt
new file mode 100644
index 0000000..a3691a8
--- /dev/null
+++ b/system/service/doc/IBluetooth.txt
@@ -0,0 +1,113 @@
+/*
+ * 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 API for talking with the Bluetooth service and perform high-level
+ * operations on the adapter.
+ */
+interface IBluetooth {
+ /**
+ * Returns true if the Bluetooth adapter is powered and ready to use. This
+ * is equivalent to "getState() == ADAPTER_STATE_ON".
+ */
+ boolean isEnabled();
+
+ /**
+ * Returns the current Bluetooth adapter state. The return value can be one of
+ * the following:
+ *
+ * - ADAPTER_STATE_OFF = 10
+ * - ADAPTER_STATE_TURNING_ON = 11
+ * - ADAPTER_STATE_ON = 12
+ * - ADAPTER_STATE_TURNING_OFF = 13
+ */
+ int getState();
+
+ /**
+ * Turns on the Bluetooth radio. This function initiates the procedure to
+ * bring the adapter state from ADAPTER_STATE_OFF to ADAPTER_STATE_ON. Returns
+ * false, if the state is not ADAPTER_STATE_OFF or if there is an error while
+ * initiating the operation. On success, the adapter state will be
+ * asynchronously updated to ADAPTER_STATE_TURNING_ON and eventually to
+ * ADAPTER_STATE_ON. Callers can monitor the status of this call by observing
+ * the IBluetoothCallback.onBluetoothStateChange callback.
+ */
+ boolean enable();
+
+ /**
+ * Turns off the Bluetooth radio. This function initiates the procedure to
+ * bring the adapter state from ADAPTER_STATE_ON to ADAPTER_STATE_OFF. Returns
+ * false, if the state is not ADAPTER_STATE_ON or if there is an error while
+ * initiating the operation. On success, the adapter state will be
+ * asynchronously updated to ADAPTER_STATE_TURNING_OFF and eventually to
+ * ADAPTER_STATE_OFF. Callers can monitor the status of this call by observing
+ * the IBluetoothCallback.onBluetoothStateChange callback.
+ */
+ boolean disable();
+
+ /**
+ * Returns the identity Bluetooth Device Address (BD_ADDR) assigned to the
+ * underlying Bluetooth controller. Returns a string of the form
+ * "XX:XX:XX:XX:XX:XX", where each "X" is a hexadecimal digit. Returns
+ * "00:00:00:00:00:00" if the address is not known, which is usually the case
+ * before the adapter is enabled for the first time.
+ */
+ String getAddress();
+
+ /**
+ * Sets the name assigned to the Bluetooth adapter. This is the name that will
+ * be seen by remote devices during discovery. Returns false if the operation
+ * fails.
+ */
+ boolean setName(in String name);
+
+ /**
+ * Returns the current name assigned to the Bluetooth adapter. This is the
+ * name that is seen by remote devices during discovery. If the controller has
+ * not been initialized yet (before the first time it gets enabled), this will
+ * return "not-initialized".
+ */
+ String getName();
+
+ /**
+ * Registers a callback receiver which can be used to listen to state updates
+ * from the adapter. The Bluetooth daemon will automatically register this if
+ * the owning process dies.
+ */
+ void registerCallback(in IBluetoothCallback callback);
+
+ /**
+ * Unregisters a previously registered callback.
+ */
+ void unregisterCallback(in IBluetoothCallback callback);
+
+ /**
+ * Returns true, if the multi-advertisement feature is supported. Returns
+ * false, if this device can only advertise a single instance.
+ */
+ boolean isMultiAdvertisementSupported();
+
+ /**
+ * Returns a binder that can be used to interact with Low-Energy features.
+ */
+ IBluetoothLowEnergy getLowEnergyInterface();
+
+ /**
+ * Returns a binder that can be used to interact with GATT server-role
+ * features.
+ */
+ IBluetoothGattServer getGattServerInterface();
+}
diff --git a/system/service/doc/IBluetoothCallback.txt b/system/service/doc/IBluetoothCallback.txt
new file mode 100644
index 0000000..612ecca
--- /dev/null
+++ b/system/service/doc/IBluetoothCallback.txt
@@ -0,0 +1,26 @@
+/*
+ * 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 callback interface for receiving notifications about the
+ * high-level Bluetooth adapter state.
+ */
+interface IBluetoothCallback {
+ /**
+ * Called when the adapter state changes from |prev_state| to |new_state|.
+ */
+ void onBluetoothStateChange(in int prev_state, in int new_state);
+}
diff --git a/system/service/doc/IBluetoothGattServer.txt b/system/service/doc/IBluetoothGattServer.txt
new file mode 100644
index 0000000..8ead69b
--- /dev/null
+++ b/system/service/doc/IBluetoothGattServer.txt
@@ -0,0 +1,114 @@
+/*
+ * 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 server-role
+ * features.
+ */
+interface IBluetoothGattServer {
+ /**
+ * Registers a client application with this interface. This creates a unique
+ * GATT server instance for the application that will contain the GATT
+ * services belonging to the calling application. A special interface ID will
+ * be returned in a callback to the application that can be used to perform
+ * GATT server operations. Returns false in case of an error.
+ */
+ boolean registerServer(in IBluetoothGattServerCallback callback);
+
+ /**
+ * Unregisters a previously registered server with interface ID |server_if|.
+ */
+ void unregisterServer(in int server_if);
+
+ /**
+ * Unregisters all previously registered servers.
+ */
+ void unregisterAll();
+
+ /**
+ * Begins a new GATT service declaration. This will execute synchronously and
+ * create a new service range. This can be followed by calls to populate the
+ * service range with attributes. The started service won't be published and
+ * made discoverable to remote devices until a successful call to
+ * endServiceDeclaration.
+ *
+ * The created service will be assigned a unique identifier that can be used
+ * by the caller to distinguish between different services. This will be
+ * returned in |out_id| in case of success. Returns false in case of failure,
+ * e.g. a service declaration is already in progress.
+ */
+ boolean beginServiceDeclaration(in int server_if, in boolean is_primary,
+ in ParcelUuid uuid,
+ out GattIdentifier out_id);
+
+ /**
+ * Adds a characteristic entry to a previously started service declaration.
+ * Returns false in case of failure, e.g. if no service declaration was
+ * started. Returns the uniquely assigned characteristic identifier in
+ * |out_id| in the case of success.
+ */
+ boolean addCharacteristic(in int server_if, in ParcelUuid uuid,
+ in int properties, in int permissions,
+ out GattIdentifier out_id);
+
+ /**
+ * Adds a characteristic descriptor entry to a previously started service
+ * declaration. Returns false in case of failure, e.g. if no service
+ * declaration was started or if the declaration does not contain a
+ * characteristic that can own this descriptor. Returns the uniquely assigned
+ * descriptor identifier in |out_id| in the case of success.
+ */
+ boolean addDescriptor(in int server_if, in ParcelUuid uuid,
+ in int permissions,
+ out GattIdentifier out_id);
+
+ /**
+ * Ends a previously started service declaration and asynchronously publishes
+ * the service in the underlying attribute database. Returns false in case of
+ * an asynchronous failure, e.g. if no service declaration was started or
+ * there is a pending call to endServiceDeclaration. Otherwise returns true
+ * and reports the result of the operation asynchronously in
+ * IBluetoothGattServerCallback.onServiceAdded.
+ */
+ boolean endServiceDeclaration(in int server_if);
+
+ /**
+ * Sends a response to a currently pending read or write request. The request
+ * will be propagated to the application via IBluetoothGattServerCallback with
+ * a unique |request_id| which must be passed to this method along with the
+ * |device_address| of the device that the request originated from.
+ *
+ * The |status| field should contain the result of the operation. In the case
+ * of success, the application should pass in "0". Otherwise this should
+ * contain an ATT protocol error code.
+ */
+ boolean sendResponse(in int server_if, in String device_address,
+ in int request_id, in int status,
+ in int offset, in byte[] value);
+
+ /**
+ * Sends a handle-value notification or indication to the device with the
+ * given address for the characteristic with the given identifier. |confirm|
+ * should be set to true, if a handle-value indication should be sent, which
+ * will remain pending until the remote device sends a handle-value
+ * confirmation. Returns false if a call to this method is pending. Otherwise
+ * reports the result asynchronously in
+ * IBluetoothGattServerCallback.onNotificationSent.
+ */
+ boolean sendNotification(in int server_if, in String device_address,
+ in GattIdentifier characteristic_id,
+ in boolean confirm, in byte[] value);
+}
diff --git a/system/service/doc/IBluetoothGattServerCallback.txt b/system/service/doc/IBluetoothGattServerCallback.txt
new file mode 100644
index 0000000..3de6969
--- /dev/null
+++ b/system/service/doc/IBluetoothGattServerCallback.txt
@@ -0,0 +1,110 @@
+/*
+ * 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 receiving callbacks related to Bluetooth GATT
+ * server-role operations.
+ */
+oneway interface IBluetoothGattServerCallback {
+ /**
+ * Called to report the result of a call to
+ * IBluetoothGattServer.registerServer. |status| will be 0 (or
+ * BLE_STATUS_SUCCESS) if the server was successfully registered. |server_if|
+ * is the owning application's unique GATT server handle and can be used to
+ * perform further operations on the IBluetoothGattServer interface.
+ */
+ void onServerRegistered(in int status, in int server_if);
+
+ /**
+ * Called to report the result of a call to
+ * IBluetoothGattServer.endServiceDeclaration. A |status| of 0 denotes
+ * success, which means that the GATT service has been published and is
+ * discoverable. |service_id| belongs to the service that was registered.
+ */
+ void onServiceAdded(in int status, in GattIdentifier service_id);
+
+ /**
+ * Called when there is an incoming read request from the remote device with
+ * address |device_address| for the characteristic with identifier
+ * |characteristic_id|. An implementation should handle this request by
+ * calling IBluetoothGattServer.sendResponse with the given |request_id| and
+ * the appropriate characteristic value.
+ */
+ void onCharacteristicReadRequest(in String device_address, in int request_id,
+ in int offset, in boolean is_long,
+ in GattIdentifier characteristic_id);
+
+ /**
+ * Called when there is an incoming read request from the remote device with
+ * address |device_address| for the descriptor with identifier
+ * |descriptor_id|. An implementation should handle this request by
+ * calling IBluetoothGattServer.sendResponse with the given |request_id| and
+ * the appropriate descriptor value.
+ */
+ void onDescriptorReadRequest(in String device_address, in int request_id,
+ in int offset, in boolean is_long,
+ in GattIdentifier descriptor_id);
+
+ /**
+ * Called when there is an incoming write request from the remote device with
+ * address |device_address| for the characteristic with identifier
+ * |characteristic_id| with the value |value|. An implementation should handle
+ * this request by calling IBluetoothGattServer.sendResponse with the given
+ * |request_id|. If |need_response| is false, then this is a "Write Without
+ * Response" procedure and sendResponse should not be called. If
+ * |is_prepare_write| is true, then the implementation should not commit this
+ * write until a call to onExecuteWriteRequest is received.
+ */
+ void onCharacteristicWriteRequest(in String device_address, in int request_id,
+ in int offset, in boolean is_prepare_write,
+ in boolean need_response, in byte[] value,
+ in GattIdentifier characteristic_id);
+
+ /**
+ * Called when there is an incoming write request from the remote device with
+ * address |device_address| for the descriptor with identifier
+ * |descriptor_id| with the value |value|. An implementation should handle
+ * this request by calling IBluetoothGattServer.sendResponse with the given
+ * |request_id|. If |need_response| is false, then this is a "Write Without
+ * Response" procedure and sendResponse should not be called. If
+ * |is_prepare_write| is true, then the implementation should not commit this
+ * write until a call to onExecuteWriteRequest is received.
+ */
+ void onDescriptorWriteRequest(in String device_address, in int request_id,
+ in int offset, in boolean is_prepare_write,
+ in boolean need_response, in byte[] value,
+ in GattIdentifier descriptor_id);
+
+ /**
+ * Called when there is an incoming execute-write request to commit or abort
+ * previously prepared writes. If |is_execute| is true, then the
+ * implementation should commit all previously prepared writes. Otherwise all
+ * prepared writes should dropped (aborted). The application should report the
+ * result of the execute write by calling IBluetoothGattServer.sendResponse
+ * with the given |request_id|.
+ */
+ void onExecuteWriteRequest(in String device_address, in int request_id,
+ in boolean is_execute);
+
+ /**
+ * Reports the result of a previous call to
+ * IBluetoothGattServer.sendNotification. If an indication was sent, this will
+ * be called when the remote end sends a confirmation packet. Otherwise this
+ * will be called as soon as the notification packet is successfully sent out
+ * over the radio.
+ */
+ void onNotificationSent(in String device_address, in int status);
+}
diff --git a/system/service/doc/IBluetoothLowEnergy.txt b/system/service/doc/IBluetoothLowEnergy.txt
new file mode 100644
index 0000000..c5f0782
--- /dev/null
+++ b/system/service/doc/IBluetoothLowEnergy.txt
@@ -0,0 +1,62 @@
+/*
+ * 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 API for interacting with Bluetooth Low-Energy features.
+ */
+interface IBluetoothLowEnergy {
+ /**
+ * Registers a client application that can manage its own Low Energy
+ * instance. A special client interface ID will be returned in a callback to
+ * the application that can be used to perform Low Energy operations. Returns
+ * false in case of an error.
+ */
+ boolean registerClient(in IBluetoothLowEnergyCallback callback);
+
+ /**
+ * Unregisters a previously registered client with "client interface ID"
+ * |client_if|.
+ */
+ void unregisterClient(in int client_if);
+
+ /**
+ * Unregisters all previous registered clients.
+ */
+ void unregisterAll();
+
+ /**
+ * Starts a multi-advertising instance with the given advertising and scan
+ * response data, both of which can be empty. Each of these parameters must
+ * contain the raw advertising packet. Returns false if there were any
+ * synchronous failures, e.g. if the advertising or scan response data are
+ * incorrectly formatted. Otherwise, the result of the operation will be
+ * asynchronously reported in
+ * IBluetoothLowEnergyCallback.onMultiAdvertiseCallback. See the headers in
+ * common/bluetooth/binder for documentation on the AdvertiseData and
+ * AdvertiseSettings data types.
+ */
+ boolean startMultiAdvertising(in int client_if,
+ in AdvertiseData advertise_data,
+ in AdvertiseData scan_response_data,
+ in AdvertiseSettings settings);
+
+ /**
+ * Stops the previously started multi-advertising instance for the given
+ * client. Returns false in case of an error, e.g. this client has not started
+ * an instance.
+ */
+ boolean stopMultiAdvertising(in int client_if);
+}
diff --git a/system/service/doc/IBluetoothLowEnergyCallback.txt b/system/service/doc/IBluetoothLowEnergyCallback.txt
new file mode 100644
index 0000000..c11f825
--- /dev/null
+++ b/system/service/doc/IBluetoothLowEnergyCallback.txt
@@ -0,0 +1,37 @@
+/*
+ * 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 receiving callbacks related to Bluetooth Low Energy
+ * operations.
+ */
+oneway interface IBluetoothLowEnergyCallback {
+ /**
+ * Called to report the result of a call to
+ * IBluetoothLowEnergy.registerClient. |status| will be 0 (or
+ * BLE_STATUS_SUCCESS) if the client was successfully registered. |client_if|
+ * is the owning application's unique Low Energy client handle and can be used
+ * to perform further operations on the IBluetoothLowEnergy interface.
+ */
+ void onClientRegistered(in int status, in int client_if);
+
+ /**
+ * Called to report the result of a call to
+ * IBluetoothLowEnergy.startMultiAdvertising or stopMultiAdvertising.
+ */
+ void onMultiAdvertiseCallback(in int status, in boolean is_start,
+ in AdvertiseSettings settings);
+}
