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