Home | History | Annotate | Download | only in dbus 
      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_CHARACTERISTIC_SERVICE_PROVIDER_H_
      6 #define CHROMEOS_DBUS_BLUETOOTH_GATT_CHARACTERISTIC_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 // BluetoothGattCharacteristicServiceProvider is used to provide a D-Bus object
     20 // that represents a local GATT characteristic that the Bluetooth daemon can
     21 // communicate with.
     22 //
     23 // Instantiate with a chosen D-Bus object path, delegate, and other fields.
     24 // The Bluetooth daemon communicates with a GATT characteristic using the
     25 // standard DBus.Properties interface. While most properties of the GATT
     26 // characteristic 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 BluetoothGattCharacteristicServiceProvider {
     34  public:
     35   // Interface for reacting to GATT characteristic value requests.
     36   class Delegate {
     37    public:
     38     virtual ~Delegate() {}
     39 
     40     // ValueCallback is used for methods that require a characteristic 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 characteristic. 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     // characteristic 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 GetCharacteristicValue(
     55         const ValueCallback& callback,
     56         const ErrorCallback& error_callback) = 0;
     57 
     58     // This method will be called, when a remote device requests to write the
     59     // value of the exported GATT characteristic. Invoke |callback| to report
     60     // that the value was successfully written. Invoke |error_callback| to
     61     // report a failure to write the value. This can happen, for example, if the
     62     // characteristic has no write permission set. Either callback should be
     63     // invoked after a reasonable amount of time, since the request will time
     64     // out if left pending for too long.
     65     //
     66     // The delegate should use this method to perform any side-effects that may
     67     // occur based on the set value and potentially send a property changed
     68     // signal to notify the Bluetooth daemon that the value has changed.
     69     virtual void SetCharacteristicValue(
     70         const std::vector<uint8>& value,
     71         const base::Closure& callback,
     72         const ErrorCallback& error_callback) = 0;
     73   };
     74 
     75   virtual ~BluetoothGattCharacteristicServiceProvider();
     76 
     77   // Send a PropertyChanged signal to notify the Bluetooth daemon that the value
     78   // of the "Value" property has changed to |value|.
     79   virtual void SendValueChanged(const std::vector<uint8>& value) = 0;
     80 
     81   // Creates the instance, where |bus| is the D-Bus bus connection to export
     82   // the object onto, |uuid| is the 128-bit GATT characteristic UUID,
     83   // |flags| is the list of GATT characteristic properties, |permissions| is the
     84   // list of attribute permissions, |service_path| is the object path of the
     85   // exported GATT service the characteristic belongs to, |object_path| is the
     86   // object path that the characteristic should have, and |delegate| is the
     87   // object that "Value" Get/Set requests will be passed to and responses
     88   // generated from.
     89   //
     90   // Object paths of GATT characteristics must be hierarchical to the path of
     91   // the GATT service they belong to. Hence, |object_path| must have
     92   // |service_path| as its prefix. Ownership of |delegate| is not taken, thus
     93   // the delegate should outlive this instance. A delegate should handle only
     94   // a single exported characteristic and own it.
     95   static BluetoothGattCharacteristicServiceProvider* Create(
     96       dbus::Bus* bus,
     97       const dbus::ObjectPath& object_path,
     98       Delegate* delegate,
     99       const std::string& uuid,
    100       const std::vector<std::string>& flags,
    101       const std::vector<std::string>& permissions,
    102       const dbus::ObjectPath& service_path);
    103 
    104  protected:
    105   BluetoothGattCharacteristicServiceProvider();
    106 
    107  private:
    108   DISALLOW_COPY_AND_ASSIGN(BluetoothGattCharacteristicServiceProvider);
    109 };
    110 
    111 }  // namespace chromeos
    112 
    113 #endif  // CHROMEOS_DBUS_BLUETOOTH_GATT_CHARACTERISTIC_SERVICE_PROVIDER_H_
    114