jgh

Dependents:   Migration

Fork of BLE_API by Bluetooth Low Energy

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?

UserRevisionLine numberNew 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__