device/bluetooth: Add abstract API definition for BluetoothGattCharacteristic.

This CL defines the abstract class BluetoothGattCharacteristic, which represents
remote and local GATT characteristics in the GATT API.

BUG=340525
TEST=Compile Chrome.

Review URL: https://codereview.chromium.org/158283002

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@250340 0039d316-1c4b-4281-b951-d872f2087c98

4 files changed, 214 insertions, 1 deletions

diff --git a/device/bluetooth/bluetooth.gyp b/device/bluetooth/bluetooth.gyp
index 757729d..695ce66 100644
--- a/device/bluetooth/bluetooth.gyp
+++ b/device/bluetooth/bluetooth.gyp
@@ -39,6 +39,8 @@
         'bluetooth_device_mac.mm',
         'bluetooth_device_win.cc',
         'bluetooth_device_win.h',
+        'bluetooth_gatt_characteristic.cc',
+        'bluetooth_gatt_characteristic.h',
         'bluetooth_gatt_service.cc',
         'bluetooth_gatt_service.h',
         'bluetooth_init_win.cc',
diff --git a/device/bluetooth/bluetooth_gatt_characteristic.cc b/device/bluetooth/bluetooth_gatt_characteristic.cc
new file mode 100644
index 0000000..49fd3b3
--- /dev/null
+++ b/device/bluetooth/bluetooth_gatt_characteristic.cc
@@ -0,0 +1,27 @@
+// 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.
+
+#include "device/bluetooth/bluetooth_gatt_characteristic.h"
+
+#include "base/logging.h"
+
+namespace device {
+
+BluetoothGattCharacteristic::BluetoothGattCharacteristic() {
+}
+
+BluetoothGattCharacteristic::~BluetoothGattCharacteristic() {
+}
+
+// static
+BluetoothGattCharacteristic* BluetoothGattCharacteristic::Create(
+    const bluetooth_utils::UUID& uuid,
+    const std::vector<uint8>& value,
+    Properties properties,
+    Permissions permissions) {
+  LOG(ERROR) << "Creating local GATT characteristics currently not supported.";
+  return NULL;
+}
+
+}  // namespace device
diff --git a/device/bluetooth/bluetooth_gatt_characteristic.h b/device/bluetooth/bluetooth_gatt_characteristic.h
new file mode 100644
index 0000000..87993ac
--- /dev/null
+++ b/device/bluetooth/bluetooth_gatt_characteristic.h
@@ -0,0 +1,184 @@
+// 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_CHARACTERISTIC_H_
+#define DEVICE_BLUETOOTH_GATT_CHARACTERISTIC_H_
+
+#include <vector>
+
+#include "base/basictypes.h"
+#include "base/callback.h"
+#include "device/bluetooth/bluetooth_utils.h"
+
+namespace device {
+
+class BluetoothGattDescriptor;
+class BluetoothGattService;
+
+// BluetoothGattCharacteristic represents a local or remote GATT characteristic.
+// A GATT characteristic is a basic data element used to construct a GATT
+// service. Hence, instances of a BluetoothGattCharacteristic are associated
+// with a BluetoothGattService. There are two ways in which this class is used:
+//
+//   1. To represent GATT characteristics that belong to a service hosted by a
+//      a remote device. In this case the characteristic will be constructed by
+//      the subsystem.
+//   2. To represent GATT characteristics that belong to a locally hosted
+//      service. To achieve this, users can construct instances of
+//      BluetoothGattCharacteristic directly and add it to the desired
+//      BluetoothGattService instance that represents a local service.
+class BluetoothGattCharacteristic {
+ public:
+  // Values representing the possible properties of a characteristic, which
+  // define how the characteristic can be used. Each of these properties serve
+  // a role as defined in the Bluetooth Specification.
+  // |kPropertyExtendedProperties| is a special property that, if present,
+  // indicates that there is a characteristic descriptor (namely the
+  // "Characteristic Extended Properties Descriptor" with UUID 0x2900) that
+  // contains additional properties pertaining to the characteristic.
+  enum Property {
+    kPropertyNone = 0,
+    kPropertyBroadcast = 1 << 0,
+    kPropertyRead = 1 << 1,
+    kPropertyWriteWithoutResponse = 1 << 2,
+    kPropertyWrite = 1 << 3,
+    kPropertyNotify = 1 << 4,
+    kPropertyIndicate = 1 << 5,
+    kPropertyAuthenticatedSignedWrites = 1 << 6,
+    kPropertyExtendedProperties = 1 << 7
+  };
+  typedef uint32 Properties;
+
+  // Values representing read, write, and encryption permissions for a
+  // characteristic's value. While attribute permissions for all GATT
+  // definitions have been set by the Bluetooth specification, characteristic
+  // value permissions are left up to the higher-level profile.
+  //
+  // Attribute permissions are distinct from the characteristic properties. For
+  // example, a characteristic may have the property |kPropertyRead| to make
+  // clients know that it is possible to read the characteristic value and have
+  // the permission |kPermissionReadEncrypted| to require a secure connection.
+  // It is up to the application to properly specify the permissions and
+  // properties for a local characteristic.
+  enum Permission {
+    kPermissionNone = 0,
+    kPermissionRead = 1 << 0,
+    kPermissionWrite = 1 << 1,
+    kPermissionReadEncrypted = 1 << 2,
+    kPermissionWriteEncrypted = 1 << 3
+  };
+  typedef uint32 Permissions;
+
+  // Interface for observing changes from a BluetoothGattCharacteristic.
+  // Properties of remote characteristics are received asynchonously. The
+  // Observer interface can be used to be notified when the initial values of a
+  // characteristic are received as well as when successive changes occur during
+  // its life cycle.
+  class Observer {
+   public:
+    // Called when the UUID of |characteristic| has changed.
+    virtual void UuidChanged(
+        BluetoothGattCharacteristic* characteristic,
+        const bluetooth_utils::UUID& uuid) {}
+
+    // Called when the current value of |characteristic| has changed.
+    virtual void ValueChanged(
+        BluetoothGattCharacteristic* characteristic,
+        const std::vector<uint8>& value) {}
+
+    // Called when the descriptors that are associated with |characteristic|
+    // have changed.
+    virtual void DescriptorsChanged(
+        BluetoothGattCharacteristic* characteristic,
+        const std::vector<BluetoothGattDescriptor*>& descriptors) {}
+  };
+
+  // The ErrorCallback is used by methods to asynchronously report errors.
+  typedef base::Callback<const std::string&> ErrorCallback;
+
+  // Adds and removes observers for events on this GATT characteristic. If
+  // monitoring multiple characteristics, check the |characteristic| 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 BluetoothGattCharacteristic that can be associated with a
+  // local GATT service when the adapter is in the peripheral role. To
+  // associate the returned characteristic with a service, add it to a local
+  // service by calling BluetoothGattService::AddCharacteristic.
+  //
+  // This method constructs a characteristic with UUID |uuid|, initial cached
+  // value |value|, properties |properties|, and permissions |permissions|.
+  // |value| will be cached and returned for read requests and automatically set
+  // 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 read
+  // and write requests.
+  //
+  // NOTE: Don't explicitly set |kPropertyExtendedProperties| in |properties|.
+  // Instead, create and add a BluetoothGattDescriptor that represents the
+  // "Characteristic Extended Properties" descriptor and this will automatically
+  // set the correspoding bit in the characteristic's properties field. If
+  // |properties| has |kPropertyExtendedProperties| set, it will be ignored.
+  static BluetoothGattCharacteristic* Create(const bluetooth_utils::UUID& uuid,
+                                             const std::vector<uint8>& value,
+                                             Properties properties,
+                                             Permissions permissions);
+
+  // The Bluetooth-specific UUID of the characteristic.
+  virtual const bluetooth_utils::UUID& GetUuid() const = 0;
+
+  // Returns true, if this characteristic is hosted locally. If false, then this
+  // instance represents a remote GATT characteristic.
+  virtual bool IsLocal() const = 0;
+
+  // Returns a pointer to the GATT service this characteristic belongs to.
+  virtual const BluetoothGattService* GetService() const = 0;
+
+  // Returns the list of GATT characteristic descriptors that provide more
+  // information about this characteristic.
+  virtual const std::vector<BluetoothGattDescriptor*>
+      GetDescriptors() const = 0;
+
+  // Adds a characteristic descriptor to the locally hosted characteristic
+  // represented by this instance. This method only makes sense for local
+  // characteristics and won't have an effect if this instance represents a
+  // remote GATT service and will return false. This method takes ownership
+  // of |descriptor|.
+  virtual bool AddDescriptor(BluetoothGattDescriptor* descriptor) = 0;
+
+  // For locally hosted characteristics, updates the characteristic's value.
+  // This will update the value that is visible to remote devices and send out
+  // any notifications and indications that have been configured. This method
+  // can be used in place of, and in conjunction with,
+  // BluetoothGattService::Delegate methods to send updates to remote devices,
+  // or simply to set update the cached value for read requests without having
+  // to implement the delegate methods.
+  //
+  // This method only makes sense for local characteristics and does nothing and
+  // returns false if this instance represents a remote characteristic.
+  virtual bool UpdateValue(const std::vector<uint8>& value) = 0;
+
+  // Sends a write request to a remote characteristic, to modify the
+  // characteristic's value 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 characteristics and will
+  // fail for those that are locally hosted.
+  virtual void WriteRemoteCharacteristic(
+      int offset,
+      const std::vector<uint8>& new_value,
+      const base::Closure& callback,
+      const ErrorCallback& error_callback) = 0;
+
+ protected:
+  BluetoothGattCharacteristic();
+  virtual ~BluetoothGattCharacteristic();
+
+ private:
+  DISALLOW_COPY_AND_ASSIGN(BluetoothGattCharacteristic);
+};
+
+}  // namespace device
+
+#endif  // DEVICE_BLUETOOTH_GATT_CHARACTERISTIC_H_
diff --git a/device/bluetooth/bluetooth_gatt_service.cc b/device/bluetooth/bluetooth_gatt_service.cc
index 628475b..dccb06a 100644
--- a/device/bluetooth/bluetooth_gatt_service.cc
+++ b/device/bluetooth/bluetooth_gatt_service.cc
@@ -19,7 +19,7 @@ BluetoothGattService* BluetoothGattService::Create(
     const bluetooth_utils::UUID& uuid,
     bool is_primary,
     Delegate* delegate) {
-  LOG(ERROR) << "Local GATT services currently not supported.";
+  LOG(ERROR) << "Creating local GATT services currently not supported.";
   return NULL;
 }