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_CLIENT_H_
6#define CHROMEOS_DBUS_BLUETOOTH_GATT_CHARACTERISTIC_CLIENT_H_
7
8#include <string>
9
10#include "base/basictypes.h"
11#include "base/callback.h"
12#include "chromeos/chromeos_export.h"
13#include "chromeos/dbus/dbus_client.h"
14#include "dbus/object_path.h"
15#include "dbus/property.h"
16
17namespace chromeos {
18
19// BluetoothGattCharacteristicClient is used to communicate with remote GATT
20// characteristic objects exposed by the Bluetooth daemon.
21class CHROMEOS_EXPORT BluetoothGattCharacteristicClient : public DBusClient {
22 public:
23  // Structure of properties associated with GATT characteristics.
24  struct Properties : public dbus::PropertySet {
25    // The 128-bit characteristic UUID. [read-only]
26    dbus::Property<std::string> uuid;
27
28    // Object path of the GATT service the characteristic belongs to.
29    // [read-only]
30    dbus::Property<dbus::ObjectPath> service;
31
32    // Whether or not this characteristic is currently sending ValueUpdated
33    // signals. [read-only]
34    dbus::Property<bool> notifying;
35
36    // List of flags representing the GATT "Characteristic Properties bit field"
37    // and properties read from the GATT "Characteristic Extended Properties"
38    // descriptor bit field. [read-only, optional]
39    dbus::Property<std::vector<std::string> > flags;
40
41    // Array of object paths representing the descriptors of this
42    // characteristic. [read-only]
43    dbus::Property<std::vector<dbus::ObjectPath> > descriptors;
44
45    Properties(dbus::ObjectProxy* object_proxy,
46               const std::string& interface_name,
47               const PropertyChangedCallback& callback);
48    virtual ~Properties();
49  };
50
51  // Interface for observing changes from a remote GATT characteristic.
52  class Observer {
53   public:
54    virtual ~Observer() {}
55
56    // Called when the GATT characteristic with object path |object_path| is
57    // added to the system.
58    virtual void GattCharacteristicAdded(const dbus::ObjectPath& object_path) {}
59
60    // Called when the GATT characteristic with object path |object_path| is
61    // removed from the system.
62    virtual void GattCharacteristicRemoved(
63        const dbus::ObjectPath& object_path) {}
64
65    // Called when the GATT characteristic with object path |object_path| has a
66    // change in the value of the property named |property_name|.
67    virtual void GattCharacteristicPropertyChanged(
68        const dbus::ObjectPath& object_path,
69        const std::string& property_name) {}
70
71    // Called when a "ValueUpdated" signal is received from the remote GATT
72    // characteristic with object path |object_path| with characteristic value
73    // |value|.
74    virtual void GattCharacteristicValueUpdated(
75        const dbus::ObjectPath& object_path,
76        const std::vector<uint8>& value) {}
77  };
78
79  // Callbacks used to report the result of asynchronous methods.
80  typedef base::Callback<void(const std::string& error_name,
81                              const std::string& error_message)> ErrorCallback;
82  typedef base::Callback<void(const std::vector<uint8>& value)> ValueCallback;
83
84  virtual ~BluetoothGattCharacteristicClient();
85
86  // Adds and removes observers for events on all remote GATT characteristics.
87  // Check the |object_path| parameter of observer methods to determine which
88  // GATT characteristic is issuing the event.
89  virtual void AddObserver(Observer* observer) = 0;
90  virtual void RemoveObserver(Observer* observer) = 0;
91
92  // Returns the list of GATT characteristic object paths known to the system.
93  virtual std::vector<dbus::ObjectPath> GetCharacteristics() = 0;
94
95  // Obtain the properties for the GATT characteristic with object path
96  // |object_path|. Values should be copied if needed.
97  virtual Properties* GetProperties(const dbus::ObjectPath& object_path) = 0;
98
99  // Issues a request to read the value of GATT characteristic with object path
100  // |object_path| and returns the value in |callback| on success. On error,
101  // invokes |error_callback|.
102  virtual void ReadValue(const dbus::ObjectPath& object_path,
103                         const ValueCallback& callback,
104                         const ErrorCallback& error_callback) = 0;
105
106  // Issues a request to write the value of GATT characteristic with object path
107  // |object_path| with value |value|. Invokes |callback| on success and
108  // |error_callback| on failure.
109  virtual void WriteValue(const dbus::ObjectPath& object_path,
110                          const std::vector<uint8>& value,
111                          const base::Closure& callback,
112                          const ErrorCallback& error_callback) = 0;
113
114  // Starts a notification session from this characteristic with object path
115  // |object_path| if it supports value notifications or indications. Invokes
116  // |callback| on success and |error_callback| on failure.
117  virtual void StartNotify(const dbus::ObjectPath& object_path,
118                           const base::Closure& callback,
119                           const ErrorCallback& error_callback) = 0;
120
121  // Cancels any previous StartNotify transaction for characteristic with
122  // object path |object_path|. Invokes |callback| on success and
123  // |error_callback| on failure.
124  virtual void StopNotify(const dbus::ObjectPath& object_path,
125                          const base::Closure& callback,
126                          const ErrorCallback& error_callback) = 0;
127
128  // Creates the instance.
129  static BluetoothGattCharacteristicClient* Create();
130
131  // Constants used to indicate exceptional error conditions.
132  static const char kNoResponseError[];
133  static const char kUnknownCharacteristicError[];
134
135 protected:
136  BluetoothGattCharacteristicClient();
137
138 private:
139  DISALLOW_COPY_AND_ASSIGN(BluetoothGattCharacteristicClient);
140};
141
142}  // namespace chromeos
143
144#endif  // CHROMEOS_DBUS_BLUETOOTH_GATT_CHARACTERISTIC_CLIENT_H_
145