Refactor device::BluetoothGattXXX classes to split into remote/local.

device/bluetooth/bluetooth_remote_gatt_descriptor.h

-// Copyright 2014 The Chromium Authors. All rights reserved.
+// Copyright 2016 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_BLUETOOTH_GATT_DESCRIPTOR_H_
-#define DEVICE_BLUETOOTH_BLUETOOTH_GATT_DESCRIPTOR_H_
+#ifndef DEVICE_BLUETOOTH_BLUETOOTH_REMOTE_GATT_DESCRIPTOR_H_
+#define DEVICE_BLUETOOTH_BLUETOOTH_REMOTE_GATT_DESCRIPTOR_H_
 
 #include <stdint.h>
-
 #include <vector>
 
 #include "base/callback.h"
+#include "base/callback_forward.h"
 #include "base/macros.h"
 #include "device/bluetooth/bluetooth_export.h"
-#include "device/bluetooth/bluetooth_gatt_characteristic.h"
+#include "device/bluetooth/bluetooth_gatt_descriptor.h"
 #include "device/bluetooth/bluetooth_uuid.h"
 
 namespace device {
 
-// 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 DEVICE_BLUETOOTH_EXPORT BluetoothGattDescriptor {
+class BluetoothRemoteGattCharacteristic;
+
+// BluetoothRemoteGattDescriptor represents a remote GATT characteristic
+// descriptor.

[scheib, 2016/04/20 01:23:30]

Might as well keep the "A GATT characteristic descriptor provides..."
description.

[rkc, 2016/04/20 16:31:54]

Its there in the comment for the base class. I am trying to have header comments
for derived classes that just describe things that are different or not present
in the base class.

+//
+// Note: We use virtual inheritance on the GATT descriptor since it will be
+// inherited by platform specific versions of the GATT descriptor classes also.
+// The platform specific remote GATT descriptor classes will inherit both this
+// class and their GATT descriptor class, hence causing an inheritance diamond.
+class DEVICE_BLUETOOTH_EXPORT BluetoothRemoteGattDescriptor
+    : public virtual BluetoothGattDescriptor {
  public:
-  // The ErrorCallback is used by methods to asynchronously report errors.
-  typedef base::Callback<void(BluetoothGattService::GattErrorCode)>
-      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_t>&)> ValueCallback;
 
-  // 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 descriptors 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 BluetoothUUID& CharacteristicExtendedPropertiesUuid();
-
-  // 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 BluetoothUUID& CharacteristicUserDescriptionUuid();
-
-  // 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 BluetoothUUID& ClientCharacteristicConfigurationUuid();
-
-  // 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 BluetoothUUID& ServerCharacteristicConfigurationUuid();
-
-  // 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 BluetoothUUID& CharacteristicPresentationFormatUuid();
-
-  // The "Characteristic Aggregate Format" descriptor defines the format of an
-  // aggregated 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" descriptors 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 BluetoothUUID& CharacteristicAggregateFormatUuid();
-
-  // 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 BluetoothUUID& uuid,
-      const std::vector<uint8_t>& value,
-      BluetoothGattCharacteristic::Permissions permissions);
-
-  // Identifier used to uniquely identify a GATT descriptor object. This is
-  // different from the descriptor UUID: while multiple descriptors with the
-  // same UUID can exist on a Bluetooth device, the identifier returned from
-  // this method is unique among all descriptors on the adapter. The contents of
-  // the identifier are platform specific.
-  virtual std::string GetIdentifier() const = 0;
-
-  // The Bluetooth-specific UUID of the characteristic descriptor.
-  virtual BluetoothUUID 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 the value of the descriptor. For remote descriptors, this is the
   // most recently cached value of the remote descriptor. For local descriptors
   // this is the most recently updated value or the value retrieved from the
   // delegate.
   virtual const std::vector<uint8_t>& GetValue() const = 0;
 
   // Returns a pointer to the GATT characteristic that this characteristic
   // descriptor belongs to.
-  virtual BluetoothGattCharacteristic* GetCharacteristic() const = 0;
-
-  // Returns the bitmask of characteristic descriptor attribute permissions.
-  virtual BluetoothGattCharacteristic::Permissions GetPermissions() const = 0;
+  virtual BluetoothRemoteGattCharacteristic* 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 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(const std::vector<uint8_t>& new_value,
                                      const base::Closure& callback,
                                      const ErrorCallback& error_callback) = 0;
 
  protected:
-  BluetoothGattDescriptor();
-  virtual ~BluetoothGattDescriptor();
+  BluetoothRemoteGattDescriptor();
+  ~BluetoothRemoteGattDescriptor() override;
 
  private:
-  DISALLOW_COPY_AND_ASSIGN(BluetoothGattDescriptor);
+  DISALLOW_COPY_AND_ASSIGN(BluetoothRemoteGattDescriptor);
 };
 
 }  // namespace device
 
-#endif  // DEVICE_BLUETOOTH_BLUETOOTH_GATT_DESCRIPTOR_H_
+#endif  // DEVICE_BLUETOOTH_BLUETOOTH_REMOTE_GATT_DESCRIPTOR_H_