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 DEVICE_BLUETOOTH_BLUETOOTH_GATT_SERVICE_H_
6#define DEVICE_BLUETOOTH_BLUETOOTH_GATT_SERVICE_H_
7
8#include <vector>
9
10#include "base/basictypes.h"
11#include "base/callback.h"
12#include "device/bluetooth/bluetooth_uuid.h"
13
14namespace device {
15
16class BluetoothDevice;
17class BluetoothGattCharacteristic;
18class BluetoothGattDescriptor;
19
20// BluetoothGattService represents a local or remote GATT service. A GATT
21// service is hosted by a peripheral and represents a collection of data in
22// the form of GATT characteristics and a set of included GATT services if this
23// service is what is called "a primary service".
24//
25// Instances of the BluetoothGattService class are used for two functions:
26//   1. To represent GATT attribute hierarchies that have been received from a
27//      remote Bluetooth GATT peripheral. Such BluetoothGattService instances
28//      are constructed and owned by a BluetoothDevice.
29//
30//   2. To represent a locally hosted GATT attribute hierarchy when the local
31//      adapter is used in the "peripheral" role. Such instances are meant to be
32//      constructed directly and registered. Once registered, a GATT attribute
33//      hierarchy will be visible to remote devices in the "central" role.
34class BluetoothGattService {
35 public:
36  // The Delegate class is used to send certain events that need to be handled
37  // when the device is in peripheral mode. The delegate handles read and write
38  // requests that are issued from remote clients.
39  class Delegate {
40   public:
41    // Callbacks used for communicating GATT request responses.
42    typedef base::Callback<void(const std::vector<uint8>)> ValueCallback;
43    typedef base::Closure ErrorCallback;
44
45    // Called when a remote device in the central role requests to read the
46    // value of the characteristic |characteristic| starting at offset |offset|.
47    // This method is only called if the characteristic was specified as
48    // readable and any authentication and authorization challanges were
49    // satisfied by the remote device.
50    //
51    // To respond to the request with success and return the requested value,
52    // the delegate must invoke |callback| with the value. Doing so will
53    // automatically update the value property of |characteristic|. To respond
54    // to the request with failure (e.g. if an invalid offset was given),
55    // delegates must invoke |error_callback|. If neither callback parameter is
56    // invoked, the request will time out and result in an error. Therefore,
57    // delegates MUST invoke either |callback| or |error_callback|.
58    virtual void OnCharacteristicReadRequest(
59        const BluetoothGattService* service,
60        const BluetoothGattCharacteristic* characteristic,
61        int offset,
62        const ValueCallback& callback,
63        const ErrorCallback& error_callback) = 0;
64
65    // Called when a remote device in the central role requests to write the
66    // value of the characteristic |characteristic| starting at offset |offset|.
67    // This method is only called if the characteristic was specified as
68    // writeable and any authentication and authorization challanges were
69    // satisfied by the remote device.
70    //
71    // To respond to the request with success the delegate must invoke
72    // |callback| with the new value of the characteristic. Doing so will
73    // automatically update the value property of |characteristic|. To respond
74    // to the request with failure (e.g. if an invalid offset was given),
75    // delegates must invoke |error_callback|. If neither callback parameter is
76    // invoked, the request will time out and result in an error. Therefore,
77    // delegates MUST invoke either |callback| or |error_callback|.
78    virtual void OnCharacteristicWriteRequest(
79        const BluetoothGattService* service,
80        const BluetoothGattCharacteristic* characteristic,
81        const std::vector<uint8>& value,
82        int offset,
83        const ValueCallback& callback,
84        const ErrorCallback& error_callback) = 0;
85
86    // Called when a remote device in the central role requests to read the
87    // value of the descriptor |descriptor| starting at offset |offset|.
88    // This method is only called if the characteristic was specified as
89    // readable and any authentication and authorization challanges were
90    // satisfied by the remote device.
91    //
92    // To respond to the request with success and return the requested value,
93    // the delegate must invoke |callback| with the value. Doing so will
94    // automatically update the value property of |descriptor|. To respond
95    // to the request with failure (e.g. if an invalid offset was given),
96    // delegates must invoke |error_callback|. If neither callback parameter is
97    // invoked, the request will time out and result in an error. Therefore,
98    // delegates MUST invoke either |callback| or |error_callback|.
99    virtual void OnDescriptorReadRequest(
100        const BluetoothGattService* service,
101        const BluetoothGattDescriptor* descriptor,
102        int offset,
103        const ValueCallback& callback,
104        const ErrorCallback& error_callback) = 0;
105
106    // Called when a remote device in the central role requests to write the
107    // value of the descriptor |descriptor| starting at offset |offset|.
108    // This method is only called if the characteristic was specified as
109    // writeable and any authentication and authorization challanges were
110    // satisfied by the remote device.
111    //
112    // To respond to the request with success the delegate must invoke
113    // |callback| with the new value of the descriptor. Doing so will
114    // automatically update the value property of |descriptor|. To respond
115    // to the request with failure (e.g. if an invalid offset was given),
116    // delegates must invoke |error_callback|. If neither callback parameter is
117    // invoked, the request will time out and result in an error. Therefore,
118    // delegates MUST invoke either |callback| or |error_callback|.
119    virtual void OnDescriptorWriteRequest(
120        const BluetoothGattService* service,
121        const BluetoothGattDescriptor* descriptor,
122        const std::vector<uint8>& value,
123        int offset,
124        const ValueCallback& callback,
125        const ErrorCallback& error_callback) = 0;
126  };
127
128  // The ErrorCallback is used by methods to asynchronously report errors.
129  typedef base::Closure ErrorCallback;
130
131  virtual ~BluetoothGattService();
132
133  // Constructs a BluetoothGattService that can be locally hosted when the local
134  // adapter is in the peripheral role. The resulting object can then be made
135  // available by calling the "Register" method. This method constructs a
136  // service with UUID |uuid|. Whether the constructed service is primary or
137  // secondary is determined by |is_primary|. |delegate| is used to send certain
138  // peripheral role events. If |delegate| is NULL, then this service will
139  // employ a default behavior when responding to read and write requests based
140  // on the cached value of its characteristics and descriptors at a given time.
141  static BluetoothGattService* Create(const BluetoothUUID& uuid,
142                                      bool is_primary,
143                                      Delegate* delegate);
144
145  // Identifier used to uniquely identify a GATT service object. This is
146  // different from the service UUID: while multiple services with the same UUID
147  // can exist on a Bluetooth device, the identifier returned from this method
148  // is unique among all services of a device. The contents of the identifier
149  // are platform specific.
150  virtual std::string GetIdentifier() const = 0;
151
152  // The Bluetooth-specific UUID of the service.
153  virtual BluetoothUUID GetUUID() const = 0;
154
155  // Returns true, if this service hosted locally. If false, then this service
156  // represents a remote GATT service.
157  virtual bool IsLocal() const = 0;
158
159  // Indicates whether the type of this service is primary or secondary. A
160  // primary service describes the primary function of the peripheral that
161  // hosts it, while a secondary service only makes sense in the presence of a
162  // primary service. A primary service may include other primary or secondary
163  // services.
164  virtual bool IsPrimary() const = 0;
165
166  // Returns the BluetoothDevice that this GATT service was received from, which
167  // also owns this service. Local services always return NULL.
168  virtual BluetoothDevice* GetDevice() const = 0;
169
170  // List of characteristics that belong to this service.
171  virtual std::vector<BluetoothGattCharacteristic*>
172      GetCharacteristics() const = 0;
173
174  // List of GATT services that are included by this service.
175  virtual std::vector<BluetoothGattService*>
176      GetIncludedServices() const = 0;
177
178  // Returns the GATT characteristic with identifier |identifier| if it belongs
179  // to this GATT service.
180  virtual BluetoothGattCharacteristic* GetCharacteristic(
181      const std::string& identifier) const = 0;
182
183  // Adds characteristics and included services to the local attribute hierarchy
184  // represented by this service. These methods only make sense for local
185  // services and won't have an effect if this instance represents a remote
186  // GATT service and will return false. While ownership of added
187  // characteristics are taken over by the service, ownership of an included
188  // service is not taken.
189  virtual bool AddCharacteristic(
190      BluetoothGattCharacteristic* characteristic) = 0;
191  virtual bool AddIncludedService(BluetoothGattService* service) = 0;
192
193  // Registers this GATT service. Calling Register will make this service and
194  // all of its associated attributes available on the local adapters GATT
195  // database and the service UUID will be advertised to nearby devices if the
196  // local adapter is discoverable. Call Unregister to make this service no
197  // longer available.
198  //
199  // These methods only make sense for services that are local and will hence
200  // fail if this instance represents a remote GATT service. |callback| is
201  // called to denote success and |error_callback| to denote failure.
202  virtual void Register(const base::Closure& callback,
203                        const ErrorCallback& error_callback) = 0;
204  virtual void Unregister(const base::Closure& callback,
205                          const ErrorCallback& error_callback) = 0;
206
207 protected:
208  BluetoothGattService();
209
210 private:
211  DISALLOW_COPY_AND_ASSIGN(BluetoothGattService);
212};
213
214}  // namespace device
215
216#endif  // DEVICE_BLUETOOTH_BLUETOOTH_GATT_SERVICE_H_
217