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