Merge from Chromium at DEPS revision 251904
This commit was generated by merge_to_master.py.
Change-Id: I1f9543259d7d2a57d81aa41a1b84f85837439d21
diff --git a/device/bluetooth/bluetooth_gatt_descriptor.h b/device/bluetooth/bluetooth_gatt_descriptor.h
new file mode 100644
index 0000000..9c0a1d2
--- /dev/null
+++ b/device/bluetooth/bluetooth_gatt_descriptor.h
@@ -0,0 +1,197 @@
+// Copyright 2014 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#ifndef DEVICE_BLUETOOTH_GATT_DESCRIPTOR_H_
+#define DEVICE_BLUETOOTH_GATT_DESCRIPTOR_H_
+
+#include <vector>
+
+#include "base/basictypes.h"
+#include "base/callback.h"
+#include "device/bluetooth/bluetooth_utils.h"
+
+namespace device {
+
+class BluetoothGattCharacteristic;
+
+// BluetoothGattDescriptor represents a local or remote GATT characteristic
+// descriptor. A GATT characteristic descriptor provides further information
+// about a characteristic's value. They can be used to describe the
+// characteristic's features or to control certain behaviors.
+class BluetoothGattDescriptor {
+ public:
+ // The Bluetooth Specification declares several predefined descriptors that
+ // profiles can use. The following are definitions for the list of UUIDs
+ // and descriptions of the characteristic descriptors that they represent.
+ // Possible values for and further information on each descriptor can be found
+ // in Core v4.0, Volume 3, Part G, Section 3.3.3. All of these desciptors are
+ // optional and may not be present for a given characteristic.
+
+ // The "Characteristic Extended Properties" descriptor. This defines
+ // additional "Characteristic Properties" which cannot fit into the allocated
+ // single octet property field of a characteristic. The value is a bit field
+ // and the two predefined bits, as per Bluetooth Core Specification v4.0, are:
+ //
+ // - Reliable Write: 0x0001
+ // - Writable Auxiliaries: 0x0002
+ //
+ static const bluetooth_utils::UUID kCharacteristicExtendedPropertiesUuid;
+
+ // The "Characteristic User Description" descriptor defines a UTF-8 string of
+ // variable size that is a user textual description of the associated
+ // characteristic's value. There can be only one instance of this descriptor
+ // per characteristic. This descriptor can be written to if the "Writable
+ // Auxiliaries" bit of the Characteristic Properties (via the "Characteristic
+ // Extended Properties" descriptor) has been set.
+ static const bluetooth_utils::UUID kCharacteristicUserDescriptionUuid;
+
+ // The "Client Characteristic Configuration" descriptor defines how the
+ // characteristic may be configured by a specific client. A server-side
+ // instance of this descriptor exists for each client that has bonded with
+ // the server and the value can be read and written by that client only. As
+ // of Core v4.0, this descriptor is used by clients to set up notifications
+ // and indications from a characteristic. The value is a bit field and the
+ // predefined bits are:
+ //
+ // - Default: 0x0000
+ // - Notification: 0x0001
+ // - Indication: 0x0002
+ //
+ static const bluetooth_utils::UUID kClientCharacteristicConfigurationUuid;
+
+ // The "Server Characteristic Configuration" descriptor defines how the
+ // characteristic may be configured for the server. There is one instance
+ // of this descriptor for all clients and setting the value of this descriptor
+ // affects its configuration for all clients. As of Core v4.0, this descriptor
+ // is used to set up the server to broadcast the characteristic value if
+ // advertising resources are available. The value is a bit field and the
+ // predefined bits are:
+ //
+ // - Default: 0x0000
+ // - Broadcast: 0x0001
+ //
+ static const bluetooth_utils::UUID kServerCharacteristicConfigurationUuid;
+
+ // The "Characteristic Presentation Format" declaration defines the format of
+ // the Characteristic Value. The value is composed of 7 octets which are
+ // divided into groups that represent different semantic meanings. For a
+ // detailed description of how the value of this descriptor should be
+ // interpreted, refer to Core v4.0, Volume 3, Part G, Section 3.3.3.5. If more
+ // than one declaration of this descriptor exists for a characteristic, then a
+ // "Characteristic Aggregate Format" descriptor must also exist for that
+ // characteristic.
+ static const bluetooth_utils::UUID kCharacteristicPresentationFormatUuid;
+
+ // The "Characteristic Aggregate Format" descriptor defines the format of an
+ // aggragated characteristic value. In GATT's underlying protocol, ATT, each
+ // attribute is identified by a handle that is unique for the hosting server.
+ // Multiple characteristics can share the same instance(s) of a
+ // "Characteristic Presentation Format" descriptor. The value of the
+ // "Characteristic Aggregate Format" descriptor contains a list of handles
+ // that each refer to a "Characteristic Presentation Format" descriptor that
+ // is used by that characteristic. Hence, exactly one instance of this
+ // descriptor must exist if more than one "Characteristic Presentation Format"
+ // descriptors exist for a characteristic.
+ //
+ // Applications that are using the device::Bluetooth API do not have access to
+ // the underlying handles and shouldn't use this descriptor to determine which
+ // "Characteristic Presentation Format" desciptors belong to a characteristic.
+ // The API will construct a BluetoothGattDescriptor object for each instance
+ // of "Characteristic Presentation Format" descriptor per instance of
+ // BluetoothGattCharacteristic that represents a remote characteristic.
+ // Similarly for local characteristics, implementations DO NOT need to create
+ // an instance of BluetoothGattDescriptor for this descriptor as this will be
+ // handled by the subsystem.
+ static const bluetooth_utils::UUID kCharacteristicAggregateFormatUuid;
+
+ // Interface for observing changes from a BluetoothGattDescriptor.
+ // Properties of remote characteristic desciptors are received asynchonously.
+ // The Observer interface can be used to be notified when the initial values
+ // of a characteristic descriptor are received as well as when successive
+ // changes occur during its life cycle.
+ class Observer {
+ public:
+ // Called when the UUID of |descriptor| has changed.
+ virtual void UuidChanged(
+ BluetoothGattDescriptor* descriptor,
+ const bluetooth_utils::UUID& uuid) {}
+
+ // Called when the current value of |descriptor| has changed.
+ virtual void ValueChanged(
+ BluetoothGattDescriptor* descriptor,
+ const std::vector<uint8>& value) {}
+ };
+
+ // The ErrorCallback is used by methods to asynchronously report errors.
+ typedef base::Callback<void(const std::string&)> ErrorCallback;
+
+ // The ValueCallback is used to return the value of a remote characteristic
+ // descriptor upon a read request.
+ typedef base::Callback<void(const std::vector<uint8>&)> ValueCallback;
+
+ // Adds and removes observers for events on this GATT characteristic
+ // descriptor. If monitoring multiple descriptors, check the |descriptor|
+ // parameter of observer methods to determine which characteristic is issuing
+ // the event.
+ virtual void AddObserver(Observer* observer) = 0;
+ virtual void RemoveObserver(Observer* observer) = 0;
+
+ // Constructs a BluetoothGattDescriptor that can be associated with a local
+ // GATT characteristic when the adapter is in the peripheral role. To
+ // associate the returned descriptor with a characteristic, add it to a local
+ // characteristic by calling BluetoothGattCharacteristic::AddDescriptor.
+ //
+ // This method constructs a characteristic descriptor with UUID |uuid| and the
+ // initial cached value |value|. |value| will be cached and returned for read
+ // requests and automatically modified for write requests by default, unless
+ // an instance of BluetoothGattService::Delegate has been provided to the
+ // associated BluetoothGattService instance, in which case the delegate will
+ // handle the read and write requests.
+ //
+ // Currently, only custom UUIDs, |kCharacteristicDescriptionUuid|, and
+ // |kCharacteristicPresentationFormat| are supported for locally hosted
+ // descriptors. This method will return NULL if |uuid| is any one of the
+ // unsupported predefined descriptor UUIDs.
+ static BluetoothGattDescriptor* Create(const bluetooth_utils::UUID& uuid,
+ const std::vector<uint8>& value);
+
+ // The Bluetooth-specific UUID of the characteristic descriptor.
+ virtual const bluetooth_utils::UUID& GetUuid() const = 0;
+
+ // Returns true, if this characteristic descriptor is hosted locally. If
+ // false, then this instance represents a remote descriptor.
+ virtual bool IsLocal() const = 0;
+
+ // Returns a pointer to the GATT characteristic that this characteristic
+ // descriptor belongs to.
+ virtual const BluetoothGattCharacteristic* GetCharacteristic() const = 0;
+
+ // Sends a read request to a remote characteristic descriptor to read its
+ // value. |callback| is called to return the read value on success and
+ // |error_callback| is called for failures.
+ virtual void ReadRemoteDescriptor(const ValueCallback& callback,
+ const ErrorCallback& error_callback) = 0;
+
+ // Sends a write request to a remote characteristic descriptor, to modify the
+ // value of the descriptor starting at offset |offset| with the new value
+ // |new_value|. |callback| is called to signal success and |error_callback|
+ // for failures. This method only applies to remote descriptors and will fail
+ // for those that are locally hosted.
+ virtual void WriteRemoteDescriptor(
+ int offset,
+ const std::vector<uint8>& new_value,
+ const base::Closure& callback,
+ const ErrorCallback& error_callback) = 0;
+
+ protected:
+ BluetoothGattDescriptor();
+ virtual ~BluetoothGattDescriptor();
+
+ private:
+ DISALLOW_COPY_AND_ASSIGN(BluetoothGattDescriptor);
+};
+
+} // namespace device
+
+#endif // DEVICE_BLUETOOTH_GATT_DESCRIPTOR_H_