device/bluetooth: Add chromeos::BluetoothRemoteGattCharacteristicChromeOS.

device/bluetooth/bluetooth_gatt_service.h

 // 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_BLUETOOTH_GATT_SERVICE_H_
 #define DEVICE_BLUETOOTH_BLUETOOTH_GATT_SERVICE_H_
 
 #include <vector>
 
 #include "base/basictypes.h"
@@ skipping 114 matching lines @@
   };
 
   // Interface for observing changes from a BluetoothGattService. Properties
   // of remote services are received asynchronously. The Observer interface can
   // be used to be notified when the initial values of a service are received
   // as well as when successive changes occur during its life cycle.
   class Observer {
    public:
     // Called when properties of the remote GATT service |service| have changed.
     // This will get called for properties such as UUID, as well as for changes
-    // to the list of known characteristics. Observers should read all GATT
-    // characteristic and descriptors objects and do any necessary set up
-    // required for a changed service.
+    // to the list of known characteristics and included services. Observers
+    // should read all GATT characteristic and descriptors objects and do any
+    // necessary set up required for a changed service. This method may be
+    // called several times, especially when the service is discovered for the
+    // first time. It will be called for each characteristic that is discovered
+    // or removed. Hence this method should be used to check whether or not all
+    // characteristics of a service have been discovered that correspond to the
+    // profile implemented by the Observer.
     virtual void GattServiceChanged(BluetoothGattService* service) {}
 
-    // Called when the value of a characteristic has been retrieved or updated
-    // via a notification or inidication.
-    virtual void CharacteristicValueChanged(
+    // Called when the remote GATT characteristic |characteristic| belonging to
+    // GATT service |service| has been discovered. Use this to issue any initial
+    // read/write requests to the characteristic but don't cache the pointer as
+    // it may become invalid. Instead, use the specially assigned identifier
+    // to obtain a characteristic and cache that identifier as necessary, as it
+    // can be used to retrieve the characteristic from its GATT service. The
+    // number of characteristics with the same UUID belonging to a service
+    // depends on the particular profile the remote device implements, hence the
+    // client of a GATT based profile will usually operate on the whole set of
+    // characteristics and not just one.
+    //
+    // This method will always be followed by a call to GattServiceChanged,
+    // which can be used by observers to get all the characteristics of a
+    // service and perform the necessary updates. GattCharacteristicAdded exists
+    // mostly for convenience.
+    virtual void GattCharacteristicAdded(
+        BluetoothGattService* service,
+        BluetoothGattCharacteristic* characteristic) {}
+
+    // Called when a GATT characteristic |characteristic| belonging to GATT
+    // service |service| has been removed. This method is for convenience
+    // and will be followed by a call to GattServiceChanged (except when called
+    // after the service gets removed) which should be used for bootstrapping a
+    // GATT based profile. See the documentation of GattCharacteristicAdded and
+    // GattServiceChanged for more information. Try to obtain the service from
+    // its device to see whether or not the service has been removed.
+    virtual void GattCharacteristicRemoved(
+        BluetoothGattService* service,
+        BluetoothGattCharacteristic* characteristic) {}
+
+    // Called when the value of a characteristic has changed. This might be a
+    // result of a read/write request to, or a notification/indication from, a
+    // remote GATT characteristic.
+    virtual void GattCharacteristicValueChanged(
         BluetoothGattService* service,
         BluetoothGattCharacteristic* characteristic,
         const std::vector<uint8>& value) {}
   };
 
   // The ErrorCallback is used by methods to asynchronously report errors.
   typedef base::Closure ErrorCallback;
 
   virtual ~BluetoothGattService();
 
   // Adds and removes observers for events on this GATT service. If monitoring
   // multiple services, check the |service| parameter of observer methods to
   // determine which service is issuing the event.
   virtual void AddObserver(Observer* observer) = 0;
   virtual void RemoveObserver(Observer* observer) = 0;
 
   // Constructs a BluetoothGattService that can be locally hosted when the local
   // adapter is in the peripheral role. The resulting object can then be made
   // available by calling the "Register" method. This method constructs a
   // service with UUID |uuid|. Whether the constructed service is primary or
   // secondary is determined by |is_primary|. |delegate| is used to send certain
   // peripheral role events. If |delegate| is NULL, then this service will
   // employ a default behavior when responding to read and write requests based
   // on the cached value of its characteristics and descriptors at a given time.
   static BluetoothGattService* Create(const BluetoothUUID& uuid,
                                       bool is_primary,
                                       Delegate* delegate);
 
-  // Identifier used to uniquely identify a GATT service object. This different
-  // from the service UUID: while multiple services with the same UUID can exist
-  // on a Bluetooth device, the identifier returned from this method is unique
-  // among all services of a device. The contents of the identifier are platform
-  // specific.
+  // Identifier used to uniquely identify a GATT service object. This is
+  // different from the service UUID: while multiple services with the same UUID
+  // can exist on a Bluetooth device, the identifier returned from this method
+  // is unique among all services of a device. The contents of the identifier
+  // are platform specific.
   virtual std::string GetIdentifier() const = 0;
 
   // The Bluetooth-specific UUID of the service.
   virtual BluetoothUUID GetUUID() const = 0;
 
   // Returns true, if this service hosted locally. If false, then this service
   // represents a remote GATT service.
   virtual bool IsLocal() const = 0;
 
   // Indicates whether the type of this service is primary or secondary. A
   // primary service describes the primary function of the peripheral that
   // hosts it, while a secondary service only makes sense in the presence of a
   // primary service. A primary service may include other primary or secondary
   // services.
   virtual bool IsPrimary() const = 0;
 
   // List of characteristics that belong to this service.
-  virtual const std::vector<BluetoothGattCharacteristic*>&
+  virtual std::vector<BluetoothGattCharacteristic*>
       GetCharacteristics() const = 0;
 
   // List of GATT services that are included by this service.
-  virtual const std::vector<BluetoothGattService*>&
+  virtual std::vector<BluetoothGattService*>
       GetIncludedServices() const = 0;
 
+  // Returns the GATT characteristic with identifier |identifier| if it belongs
+  // to this GATT service.
+  virtual BluetoothGattCharacteristic* GetCharacteristic(
+      const std::string& identifier) = 0;
+
   // Adds characteristics and included services to the local attribute hierarchy
   // represented by this service. These methods only make sense for local
   // services and won't have an effect if this instance represents a remote
   // GATT service and will return false. While ownership of added
   // characteristics are taken over by the service, ownership of an included
   // service is not taken.
   virtual bool AddCharacteristic(
       BluetoothGattCharacteristic* characteristic) = 0;
   virtual bool AddIncludedService(BluetoothGattService* service) = 0;
 
@@ skipping 14 matching lines @@
  protected:
   BluetoothGattService();
 
  private:
   DISALLOW_COPY_AND_ASSIGN(BluetoothGattService);
 };
 
 }  // namespace device
 
 #endif  // DEVICE_BLUETOOTH_BLUETOOTH_GATT_SERVICE_H_