Mistake on this page?
Report an issue in GitHub or email us
gatt/ServiceDiscovery.h
1 /* mbed Microcontroller Library
2  * Copyright (c) 2006-2020 ARM Limited
3  *
4  * SPDX-License-Identifier: Apache-2.0
5  *
6  * Licensed under the Apache License, Version 2.0 (the "License");
7  * you may not use this file except in compliance with the License.
8  * You may obtain a copy of the License at
9  *
10  * http://www.apache.org/licenses/LICENSE-2.0
11  *
12  * Unless required by applicable law or agreed to in writing, software
13  * distributed under the License is distributed on an "AS IS" BASIS,
14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15  * See the License for the specific language governing permissions and
16  * limitations under the License.
17  */
18 
19 #ifndef MBED_BLE_SERVICE_DISOVERY_H__
20 #define MBED_BLE_SERVICE_DISOVERY_H__
21 
22 #include "ble/common/blecommon.h"
23 #include "ble/common/UUID.h"
24 #include "ble/gatt/GattAttribute.h"
25 
26 class DiscoveredService;
28 
29 /**
30  * @addtogroup ble
31  * @{
32  * @addtogroup gatt
33  * @{
34  * @addtogroup client
35  * @{
36  */
37 
38 /**
39  * Host callback types needed by the service discovery procedure.
40  *
41  * This class is also an interface that may be used in vendor port to model
42  * the service discovery process. This interface is not used in user code.
43  *
44  * @attention Implementing this interface is not a requirement for the
45  * implementation of the service discover process.
46  */
48 public:
49  /**
50  * Service discovered event handler.
51  *
52  * The callback accepts a pointer to a DiscoveredService as parameter.
53  *
54  * @attention The argument passed to the callback may not persist after the
55  * callback invocation; therefore, the callbacks must make a shallow copy
56  * of the DiscoveredService passed as parameter to access its value beyond
57  * the callback scope.
58  */
61 
62  /**
63  * Characteristic discovered event handler.
64  *
65  * The callback accepts a pointer to a DiscoveredCharacteristic as
66  * parameter.
67  *
68  * @attention The argument passed to the callback may not persist after the
69  * callback invocation; therefore, the callbacks must make a shallow copy
70  * of the DiscoveredCharacteristic passed as parameter to access its value
71  * beyond the callback scope.
72  */
75 
76  /**
77  * Service discovery ended event.
78  *
79  * The callback accepts a connection handle as parameter. This
80  * parameter is used to identify on which connection the service discovery
81  * process ended.
82  */
84 
85 public:
86  /**
87  * Launch service discovery. Once launched, service discovery remains
88  * active with callbacks being issued back into the application for matching
89  * services or characteristics. isActive() can be used to determine status, and
90  * a termination callback (if set up) is invoked at the end. Service
91  * discovery can be terminated prematurely, if needed, using terminate().
92  *
93  * @param connectionHandle
94  * Handle for the connection with the peer.
95  * @param sc
96  * This is the application callback for a matching service. Taken as
97  * NULL by default. Note: service discovery may still be active
98  * when this callback is issued; calling asynchronous BLE-stack
99  * APIs from within this application callback might cause the
100  * stack to abort service discovery. If this becomes an issue, it
101  * may be better to make a local copy of the discoveredService and
102  * wait for service discovery to terminate before operating on the
103  * service.
104  * @param cc
105  * This is the application callback for a matching characteristic.
106  * Taken as NULL by default. Note: service discovery may still be
107  * active when this callback is issued; calling asynchronous
108  * BLE-stack APIs from within this application callback might cause
109  * the stack to abort service discovery. If this becomes an issue,
110  * it may be better to make a local copy of the discoveredCharacteristic
111  * and wait for service discovery to terminate before operating on the
112  * characteristic.
113  * @param matchingServiceUUID
114  * UUID-based filter for specifying a service in which the application is
115  * interested. By default, it is set as the wildcard UUID_UNKNOWN,
116  * in which case it matches all services. If characteristic-UUID
117  * filter (below) is set to the wildcard value, then a service
118  * callback is invoked for the matching service (or for every
119  * service if the service filter is a wildcard).
120  * @param matchingCharacteristicUUIDIn
121  * UUID-based filter for specifying a characteristic in which the application
122  * is interested. By default, it is set as the wildcard UUID_UKNOWN
123  * to match against any characteristic. If both service-UUID
124  * filter and characteristic-UUID filter are used with nonwildcard
125  * values, then only a single characteristic callback is
126  * invoked for the matching characteristic.
127  *
128  * @note Using wildcard values for both service-UUID and characteristic-
129  * UUID result in complete service discovery: callbacks being
130  * called for every service and characteristic.
131  *
132  * @note Providing NULL for the characteristic callback results in
133  * characteristic discovery being skipped for each matching
134  * service. This allows for an inexpensive method to discover only
135  * services.
136  *
137  * @return
138  * BLE_ERROR_NONE if service discovery is launched successfully; else an appropriate error.
139  */
140  virtual ble_error_t launch(ble::connection_handle_t connectionHandle,
141  ServiceCallback_t sc = nullptr,
142  CharacteristicCallback_t cc = nullptr,
144  const UUID &matchingCharacteristicUUIDIn = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN)) = 0;
145 
146  /**
147  * Check whether service-discovery is currently active.
148  */
149  virtual bool isActive() const = 0;
150 
151  /**
152  * Terminate an ongoing service discovery. This should result in an
153  * invocation of the TerminationCallback if service discovery is active.
154  */
155  virtual void terminate() = 0;
156 
157  /**
158  * Set up a callback to be invoked when service discovery is terminated.
159  */
160  virtual void onTermination(TerminationCallback_t callback) = 0;
161 
162  /**
163  * Clear all ServiceDiscovery state of the associated object.
164  *
165  * This function is meant to be overridden in the platform-specific
166  * subclass. Nevertheless, the subclass is only expected to reset its
167  * state and not the data held in ServiceDiscovery members. This is
168  * achieved by a call to ServiceDiscovery::reset() from the subclass'
169  * reset() implementation.
170  *
171  * @return BLE_ERROR_NONE on success.
172  */
173  virtual ble_error_t reset() {
174  connHandle = 0;
176  serviceCallback = nullptr;
178  characteristicCallback = nullptr;
179 
180  return BLE_ERROR_NONE;
181  }
182 
183 protected:
184  /**
185  * Connection handle as provided by the SoftDevice.
186  */
188  /**
189  * UUID-based filter that specifies the service that the application is
190  * interested in.
191  */
193  /**
194  * The registered callback handle for when a matching service is found
195  * during service-discovery.
196  */
198  /**
199  * UUID-based filter that specifies the characteristic that the
200  * application is interested in.
201  */
203  /**
204  * The registered callback handler for when a matching characteristic is
205  * found during service-discovery.
206  */
208 };
209 
210 /**
211  * @}
212  * @}
213  * @}
214  */
215 
216 #endif /* ifndef MBED_BLE_SERVICE_DISOVERY_H__ */
virtual bool isActive() const =0
Check whether service-discovery is currently active.
ble::connection_handle_t connHandle
Connection handle as provided by the SoftDevice.
UUID matchingCharacteristicUUID
UUID-based filter that specifies the characteristic that the application is interested in...
uintptr_t connection_handle_t
Opaque reference to a connection.
Representation of a characteristic discovered.
virtual void terminate()=0
Terminate an ongoing service discovery.
Callback< R(ArgTs...)> callback(R(*func)(ArgTs...)=nullptr) noexcept
Create a callback class with type inferred from the arguments.
Definition: Callback.h:678
Representation of a Universally Unique Identifier (UUID).
Definition: common/UUID.h:76
virtual ble_error_t launch(ble::connection_handle_t connectionHandle, ServiceCallback_t sc=nullptr, CharacteristicCallback_t cc=nullptr, const UUID &matchingServiceUUID=UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN), const UUID &matchingCharacteristicUUIDIn=UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN))=0
Launch service discovery.
virtual void onTermination(TerminationCallback_t callback)=0
Set up a callback to be invoked when service discovery is terminated.
CharacteristicCallback_t characteristicCallback
The registered callback handler for when a matching characteristic is found during service-discovery...
Host callback types needed by the service discovery procedure.
uint16_t ShortUUIDBytes_t
Type for a 16-bit UUID.
Definition: common/UUID.h:114
Representation of a GATT service discovered.
FunctionPointerWithContext< ble::connection_handle_t > TerminationCallback_t
Service discovery ended event.
UUID matchingServiceUUID
UUID-based filter that specifies the service that the application is interested in.
Reserved UUID.
FunctionPointerWithContext< const DiscoveredCharacteristic * > CharacteristicCallback_t
Characteristic discovered event handler.
FunctionPointerWithContext< const DiscoveredService * > ServiceCallback_t
Service discovered event handler.
virtual ble_error_t reset()
Clear all ServiceDiscovery state of the associated object.
ServiceCallback_t serviceCallback
The registered callback handle for when a matching service is found during service-discovery.
ble_error_t
Error codes for the BLE API.
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.