jgh
Fork of BLE_API by
ble/ServiceDiscovery.h@1062:a3fd424b73ca, 2016-01-11 (annotated)
- Committer:
- vcoubard
- Date:
- Mon Jan 11 08:51:37 2016 +0000
- Revision:
- 1062:a3fd424b73ca
- Parent:
- 1052:b55e1ad3e1b3
- Child:
- 1063:187f9929cb60
Synchronized with git rev b817cf3e
Author: Andres Amaya Garcia
Improve API to facilitate full shutdown procedure
The BLE API exposes a shutdown() function in BLE.h. This function is meant to
be overwridden by platform-specific sub-classes to clear all GAP and GATT
state. However, from the platform-specific implementation it is dificult to
achieve this because the Gap, GattClient, GattServer and SecurityManager
components of the API do not expose any functionality to shutdown.
This commit introduces the following changes:
* Add a static member pointer to Gap, GattClient, GattServer and
SecurityManager that is used to keep track of the initialized objects.
* Add a function member cleanup() to Gap, GattClient, GattServer and
SecurityManager to allow easy reset of the instance's state. This function
is meant to be overriden and called from the derived classes to fully clear the
state of the BLE API and the platform-specific implementation.
* Add a static member function shutdown() to Gap, GattClient, GattServer and
SecurityManager. This function shall be called from the shutdown()
overriding BLE::shutdown() for Gap, GattClient, GattServer and SecurityManager
that will in-turn clear the state of each of the components.
**NOTE:** Platform-specific implementations of this API must be modified to
this changes into account.
Who changed what in which revision?
User | Revision | Line number | New contents of line |
---|---|---|---|
rgrover1 | 716:11b41f651697 | 1 | /* mbed Microcontroller Library |
rgrover1 | 716:11b41f651697 | 2 | * Copyright (c) 2006-2013 ARM Limited |
rgrover1 | 716:11b41f651697 | 3 | * |
rgrover1 | 716:11b41f651697 | 4 | * Licensed under the Apache License, Version 2.0 (the "License"); |
rgrover1 | 716:11b41f651697 | 5 | * you may not use this file except in compliance with the License. |
rgrover1 | 716:11b41f651697 | 6 | * You may obtain a copy of the License at |
rgrover1 | 716:11b41f651697 | 7 | * |
rgrover1 | 716:11b41f651697 | 8 | * http://www.apache.org/licenses/LICENSE-2.0 |
rgrover1 | 716:11b41f651697 | 9 | * |
rgrover1 | 716:11b41f651697 | 10 | * Unless required by applicable law or agreed to in writing, software |
rgrover1 | 716:11b41f651697 | 11 | * distributed under the License is distributed on an "AS IS" BASIS, |
rgrover1 | 716:11b41f651697 | 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
rgrover1 | 716:11b41f651697 | 13 | * See the License for the specific language governing permissions and |
rgrover1 | 716:11b41f651697 | 14 | * limitations under the License. |
rgrover1 | 716:11b41f651697 | 15 | */ |
rgrover1 | 716:11b41f651697 | 16 | |
rgrover1 | 716:11b41f651697 | 17 | #ifndef __SERVICE_DISOVERY_H__ |
rgrover1 | 716:11b41f651697 | 18 | #define __SERVICE_DISOVERY_H__ |
rgrover1 | 716:11b41f651697 | 19 | |
rgrover1 | 716:11b41f651697 | 20 | #include "UUID.h" |
rgrover1 | 716:11b41f651697 | 21 | #include "Gap.h" |
rgrover1 | 716:11b41f651697 | 22 | #include "GattAttribute.h" |
rgrover1 | 716:11b41f651697 | 23 | |
rgrover1 | 716:11b41f651697 | 24 | class DiscoveredService; |
rgrover1 | 716:11b41f651697 | 25 | class DiscoveredCharacteristic; |
rgrover1 | 716:11b41f651697 | 26 | |
rgrover1 | 716:11b41f651697 | 27 | class ServiceDiscovery { |
rgrover1 | 716:11b41f651697 | 28 | public: |
rgrover1 | 716:11b41f651697 | 29 | /* |
rgrover1 | 716:11b41f651697 | 30 | * Exposed application callback types. |
rgrover1 | 716:11b41f651697 | 31 | */ |
rgrover1 | 716:11b41f651697 | 32 | |
rgrover1 | 716:11b41f651697 | 33 | /** |
vcoubard | 1048:efb29faf12fc | 34 | * Callback type for when a matching service is found during service- |
rgrover1 | 716:11b41f651697 | 35 | * discovery. The receiving function is passed in a pointer to a |
vcoubard | 1048:efb29faf12fc | 36 | * DiscoveredService object, which will remain valid for the lifetime of the |
rgrover1 | 716:11b41f651697 | 37 | * callback. Memory for this object is owned by the BLE_API eventing |
rgrover1 | 716:11b41f651697 | 38 | * framework. The application can safely make a persistent shallow-copy of |
vcoubard | 1048:efb29faf12fc | 39 | * this object to work with the service beyond the callback. |
rgrover1 | 716:11b41f651697 | 40 | */ |
vcoubard | 1052:b55e1ad3e1b3 | 41 | typedef FunctionPointerWithContext<const DiscoveredService *> ServiceCallback_t; |
rgrover1 | 716:11b41f651697 | 42 | |
rgrover1 | 716:11b41f651697 | 43 | /** |
vcoubard | 1048:efb29faf12fc | 44 | * Callback type for when a matching characteristic is found during service- |
rgrover1 | 716:11b41f651697 | 45 | * discovery. The receiving function is passed in a pointer to a |
vcoubard | 1048:efb29faf12fc | 46 | * DiscoveredCharacteristic object, which will remain valid for the lifetime |
rgrover1 | 716:11b41f651697 | 47 | * of the callback. Memory for this object is owned by the BLE_API eventing |
rgrover1 | 716:11b41f651697 | 48 | * framework. The application can safely make a persistent shallow-copy of |
vcoubard | 1048:efb29faf12fc | 49 | * this object to work with the characteristic beyond the callback. |
rgrover1 | 716:11b41f651697 | 50 | */ |
vcoubard | 1052:b55e1ad3e1b3 | 51 | typedef FunctionPointerWithContext<const DiscoveredCharacteristic *> CharacteristicCallback_t; |
rgrover1 | 716:11b41f651697 | 52 | |
rgrover1 | 716:11b41f651697 | 53 | /** |
rgrover1 | 716:11b41f651697 | 54 | * Callback type for when serviceDiscovery terminates. |
rgrover1 | 716:11b41f651697 | 55 | */ |
vcoubard | 1052:b55e1ad3e1b3 | 56 | typedef FunctionPointerWithContext<Gap::Handle_t> TerminationCallback_t; |
rgrover1 | 716:11b41f651697 | 57 | |
rgrover1 | 716:11b41f651697 | 58 | public: |
rgrover1 | 716:11b41f651697 | 59 | /** |
rgrover1 | 716:11b41f651697 | 60 | * Launch service discovery. Once launched, service discovery will remain |
rgrover1 | 716:11b41f651697 | 61 | * active with callbacks being issued back into the application for matching |
vcoubard | 1048:efb29faf12fc | 62 | * services or characteristics. isActive() can be used to determine status, and |
vcoubard | 1048:efb29faf12fc | 63 | * a termination callback (if set up) will be invoked at the end. Service |
vcoubard | 1048:efb29faf12fc | 64 | * discovery can be terminated prematurely, if needed, using terminate(). |
rgrover1 | 716:11b41f651697 | 65 | * |
rgrover1 | 716:11b41f651697 | 66 | * @param connectionHandle |
rgrover1 | 716:11b41f651697 | 67 | * Handle for the connection with the peer. |
rgrover1 | 716:11b41f651697 | 68 | * @param sc |
vcoubard | 1048:efb29faf12fc | 69 | * This is the application callback for a matching service. Taken as |
rgrover1 | 716:11b41f651697 | 70 | * NULL by default. Note: service discovery may still be active |
rgrover1 | 716:11b41f651697 | 71 | * when this callback is issued; calling asynchronous BLE-stack |
rgrover1 | 716:11b41f651697 | 72 | * APIs from within this application callback might cause the |
rgrover1 | 716:11b41f651697 | 73 | * stack to abort service discovery. If this becomes an issue, it |
vcoubard | 1048:efb29faf12fc | 74 | * may be better to make a local copy of the discoveredService and |
rgrover1 | 716:11b41f651697 | 75 | * wait for service discovery to terminate before operating on the |
rgrover1 | 716:11b41f651697 | 76 | * service. |
rgrover1 | 716:11b41f651697 | 77 | * @param cc |
vcoubard | 1048:efb29faf12fc | 78 | * This is the application callback for a matching characteristic. |
rgrover1 | 716:11b41f651697 | 79 | * Taken as NULL by default. Note: service discovery may still be |
rgrover1 | 716:11b41f651697 | 80 | * active when this callback is issued; calling asynchronous |
rgrover1 | 716:11b41f651697 | 81 | * BLE-stack APIs from within this application callback might cause |
rgrover1 | 716:11b41f651697 | 82 | * the stack to abort service discovery. If this becomes an issue, |
vcoubard | 1048:efb29faf12fc | 83 | * it may be better to make a local copy of the discoveredCharacteristic |
rgrover1 | 716:11b41f651697 | 84 | * and wait for service discovery to terminate before operating on the |
rgrover1 | 716:11b41f651697 | 85 | * characteristic. |
rgrover1 | 716:11b41f651697 | 86 | * @param matchingServiceUUID |
vcoubard | 1048:efb29faf12fc | 87 | * UUID-based filter for specifying a service in which the application is |
rgrover1 | 716:11b41f651697 | 88 | * interested. By default it is set as the wildcard UUID_UNKNOWN, |
rgrover1 | 716:11b41f651697 | 89 | * in which case it matches all services. If characteristic-UUID |
rgrover1 | 716:11b41f651697 | 90 | * filter (below) is set to the wildcard value, then a service |
rgrover1 | 716:11b41f651697 | 91 | * callback will be invoked for the matching service (or for every |
rgrover1 | 716:11b41f651697 | 92 | * service if the service filter is a wildcard). |
rgrover1 | 716:11b41f651697 | 93 | * @param matchingCharacteristicUUIDIn |
vcoubard | 1048:efb29faf12fc | 94 | * UUID-based filter for specifying a characteristic in which the application |
rgrover1 | 716:11b41f651697 | 95 | * is interested. By default it is set as the wildcard UUID_UKNOWN |
rgrover1 | 716:11b41f651697 | 96 | * to match against any characteristic. If both service-UUID |
vcoubard | 1048:efb29faf12fc | 97 | * filter and characteristic-UUID filter are used with non-wildcard |
rgrover1 | 716:11b41f651697 | 98 | * values, then only a single characteristic callback is |
rgrover1 | 716:11b41f651697 | 99 | * invoked for the matching characteristic. |
rgrover1 | 716:11b41f651697 | 100 | * |
rgrover1 | 716:11b41f651697 | 101 | * @note Using wildcard values for both service-UUID and characteristic- |
vcoubard | 1048:efb29faf12fc | 102 | * UUID will result in complete service discovery: callbacks being |
rgrover1 | 716:11b41f651697 | 103 | * called for every service and characteristic. |
rgrover1 | 716:11b41f651697 | 104 | * |
rgrover1 | 716:11b41f651697 | 105 | * @note Providing NULL for the characteristic callback will result in |
rgrover1 | 716:11b41f651697 | 106 | * characteristic discovery being skipped for each matching |
rgrover1 | 716:11b41f651697 | 107 | * service. This allows for an inexpensive method to discover only |
rgrover1 | 716:11b41f651697 | 108 | * services. |
rgrover1 | 716:11b41f651697 | 109 | * |
rgrover1 | 716:11b41f651697 | 110 | * @return |
rgrover1 | 716:11b41f651697 | 111 | * BLE_ERROR_NONE if service discovery is launched successfully; else an appropriate error. |
rgrover1 | 716:11b41f651697 | 112 | */ |
rgrover1 | 716:11b41f651697 | 113 | virtual ble_error_t launch(Gap::Handle_t connectionHandle, |
rgrover1 | 716:11b41f651697 | 114 | ServiceCallback_t sc = NULL, |
rgrover1 | 716:11b41f651697 | 115 | CharacteristicCallback_t cc = NULL, |
rgrover1 | 716:11b41f651697 | 116 | const UUID &matchingServiceUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN), |
rgrover1 | 716:11b41f651697 | 117 | const UUID &matchingCharacteristicUUIDIn = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN)) = 0; |
rgrover1 | 716:11b41f651697 | 118 | |
rgrover1 | 716:11b41f651697 | 119 | /** |
rgrover1 | 716:11b41f651697 | 120 | * Is service-discovery currently active? |
rgrover1 | 716:11b41f651697 | 121 | */ |
rgrover1 | 716:11b41f651697 | 122 | virtual bool isActive(void) const = 0; |
rgrover1 | 716:11b41f651697 | 123 | |
rgrover1 | 716:11b41f651697 | 124 | /** |
vcoubard | 1048:efb29faf12fc | 125 | * Terminate an ongoing service discovery. This should result in an |
vcoubard | 1048:efb29faf12fc | 126 | * invocation of the TerminationCallback if service discovery is active. |
rgrover1 | 716:11b41f651697 | 127 | */ |
rgrover1 | 716:11b41f651697 | 128 | virtual void terminate(void) = 0; |
rgrover1 | 716:11b41f651697 | 129 | |
rgrover1 | 716:11b41f651697 | 130 | /** |
vcoubard | 1048:efb29faf12fc | 131 | * Set up a callback to be invoked when service discovery is terminated. |
rgrover1 | 716:11b41f651697 | 132 | */ |
rgrover1 | 716:11b41f651697 | 133 | virtual void onTermination(TerminationCallback_t callback) = 0; |
rgrover1 | 716:11b41f651697 | 134 | |
vcoubard | 1062:a3fd424b73ca | 135 | /** |
vcoubard | 1062:a3fd424b73ca | 136 | * Clear all ServiceDiscovery state of the associated object. |
vcoubard | 1062:a3fd424b73ca | 137 | * |
vcoubard | 1062:a3fd424b73ca | 138 | * This function is meant to be overridden in the platform-specific |
vcoubard | 1062:a3fd424b73ca | 139 | * sub-class. Nevertheless, the sub-class is only expected to clean up its |
vcoubard | 1062:a3fd424b73ca | 140 | * state and not the data held in ServiceDiscovery members. This shall be |
vcoubard | 1062:a3fd424b73ca | 141 | * achieved by a call to ServiceDiscovery::cleanup() from the sub-class' |
vcoubard | 1062:a3fd424b73ca | 142 | * cleanup() implementation. |
vcoubard | 1062:a3fd424b73ca | 143 | * |
vcoubard | 1062:a3fd424b73ca | 144 | * @return BLE_ERROR_NONE on success. |
vcoubard | 1062:a3fd424b73ca | 145 | */ |
vcoubard | 1062:a3fd424b73ca | 146 | virtual ble_error_t cleanup(void) { |
vcoubard | 1062:a3fd424b73ca | 147 | connHandle = 0; |
vcoubard | 1062:a3fd424b73ca | 148 | matchingServiceUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN); |
vcoubard | 1062:a3fd424b73ca | 149 | serviceCallback = NULL; |
vcoubard | 1062:a3fd424b73ca | 150 | matchingCharacteristicUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN); |
vcoubard | 1062:a3fd424b73ca | 151 | characteristicCallback = NULL; |
vcoubard | 1062:a3fd424b73ca | 152 | |
vcoubard | 1062:a3fd424b73ca | 153 | return BLE_ERROR_NONE; |
vcoubard | 1062:a3fd424b73ca | 154 | } |
vcoubard | 1062:a3fd424b73ca | 155 | |
rgrover1 | 716:11b41f651697 | 156 | protected: |
rgrover1 | 716:11b41f651697 | 157 | Gap::Handle_t connHandle; /**< Connection handle as provided by the SoftDevice. */ |
rgrover1 | 716:11b41f651697 | 158 | UUID matchingServiceUUID; |
rgrover1 | 716:11b41f651697 | 159 | ServiceCallback_t serviceCallback; |
rgrover1 | 716:11b41f651697 | 160 | UUID matchingCharacteristicUUID; |
rgrover1 | 716:11b41f651697 | 161 | CharacteristicCallback_t characteristicCallback; |
rgrover1 | 716:11b41f651697 | 162 | }; |
rgrover1 | 716:11b41f651697 | 163 | |
rgrover1 | 716:11b41f651697 | 164 | #endif // ifndef __SERVICE_DISOVERY_H__ |