chromeos/dbus/bluetooth_gatt_descriptor_service_provider.h

   1 // Copyright 2014 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef CHROMEOS_DBUS_BLUETOOTH_GATT_DESCRIPTOR_SERVICE_PROVIDER_H_
   6 #define CHROMEOS_DBUS_BLUETOOTH_GATT_DESCRIPTOR_SERVICE_PROVIDER_H_
   7
   8 #include <string>
   9 #include <vector>
  10
  11 #include "base/basictypes.h"
  12 #include "base/callback.h"
  13 #include "chromeos/chromeos_export.h"
  14 #include "dbus/bus.h"
  15 #include "dbus/object_path.h"
  16
  17 namespace chromeos {
  18
  19 // BluetoothGattDescriptorServiceProvider is used to provide a D-Bus object that
  20 // represents a local GATT characteristic descriptor that the Bluetooth daemon
  21 // can communicate with.
  22 //
  23 // Instantiate with a chosen D-Bus object path, delegate, and other fields.
  24 // The Bluetooth daemon communicates with a GATT descriptor using the
  25 // standard DBus.Properties interface. While most properties of the GATT
  26 // descriptor interface are read-only and don't change throughout the
  27 // life-time of the object, the "Value" property is both writeable and its
  28 // value can change. Both Get and Set operations performed on the "Value"
  29 // property are delegated to the Delegate object, an instance of which is
  30 // mandatory during initialization. In addition, a "SendValueChanged" method is
  31 // provided, which emits a DBus.Properties.PropertyChanged signal for the
  32 // "Value" property.
  33 class CHROMEOS_EXPORT BluetoothGattDescriptorServiceProvider {
  34  public:
  35   // Interface for reacting to GATT characteristic descriptor value requests.
  36   class Delegate {
  37    public:
  38     virtual ~Delegate() {}
  39
  40     // ValueCallback is used for methods that require a descriptor value
  41     // to be returned.
  42     typedef base::Callback<void(const std::vector<uint8>&)> ValueCallback;
  43
  44     // ErrorCallback is used by methods to report failure.
  45     typedef base::Closure ErrorCallback;
  46
  47     // This method will be called when a remote device requests to read the
  48     // value of the exported GATT descriptor. Invoke |callback| with a value
  49     // to return that value to the requester. Invoke |error_callback| to report
  50     // a failure to read the value. This can happen, for example, if the
  51     // descriptor has no read permission set. Either callback should be
  52     // invoked after a reasonable amount of time, since the request will time
  53     // out if left pending for too long.
  54     virtual void GetDescriptorValue(const ValueCallback& callback,
  55                                     const ErrorCallback& error_callback) = 0;
  56
  57     // This method will be called, when a remote device requests to write the
  58     // value of the exported GATT descriptor. Invoke |callback| to report
  59     // that the value was successfully written. Invoke |error_callback| to
  60     // report a failure to write the value. This can happen, for example, if the
  61     // descriptor has no write permission set. Either callback should be
  62     // invoked after a reasonable amount of time, since the request will time
  63     // out if left pending for too long.
  64     //
  65     // The delegate should use this method to perform any side-effects that may
  66     // occur based on the set value and potentially send a property changed
  67     // signal to notify the Bluetooth daemon that the value has changed.
  68     virtual void SetDescriptorValue(const std::vector<uint8>& value,
  69                                     const base::Closure& callback,
  70                                     const ErrorCallback& error_callback) = 0;
  71   };
  72
  73   virtual ~BluetoothGattDescriptorServiceProvider();
  74
  75   // Send a PropertyChanged signal to notify the Bluetooth daemon that the value
  76   // of the "Value" property has changed to |value|.
  77   virtual void SendValueChanged(const std::vector<uint8>& value) = 0;
  78
  79   // Creates the instance, where |bus| is the D-Bus bus connection to export
  80   // the object onto, |uuid| is the 128-bit GATT descriptor UUID, |permissions|
  81   // is the list of attribute permissions, |characteristic_path| is the object
  82   // path of the exported GATT characteristic the descriptor belongs to,
  83   // |object_path| is the object path that the descriptor should have, and
  84   // |delegate| is the object that value Get/Set requests will be passed to and
  85   // responses generated from.
  86   //
  87   // Object paths of GATT descriptors must be hierarchical to the path of the
  88   // GATT characteristic they belong to. Hence, |object_path| must have
  89   // |characteristic_path| as its prefix. Ownership of |delegate| is not taken,
  90   // thus the delegate should outlive this instance. A delegate should handle
  91   // only a single exported descriptor and own it.
  92   static BluetoothGattDescriptorServiceProvider* Create(
  93       dbus::Bus* bus,
  94       const dbus::ObjectPath& object_path,
  95       Delegate* delegate,
  96       const std::string& uuid,
  97       const std::vector<std::string>& permissions,
  98       const dbus::ObjectPath& characteristic_path);
  99
 100  protected:
 101   BluetoothGattDescriptorServiceProvider();
 102
 103  private:
 104   DISALLOW_COPY_AND_ASSIGN(BluetoothGattDescriptorServiceProvider);
 105 };
 106
 107 }  // namespace chromeos
 108
 109 #endif  // CHROMEOS_DBUS_BLUETOOTH_GATT_DESCRIPTOR_SERVICE_PROVIDER_H_