Bluetooth Low Energy / BLE_API

High level Bluetooth Low Energy API and radio abstraction layer

Dependents:   BLE_ANCS_SDAPI BLE_temperature BLE_HeartRate BLE_ANCS_SDAPI_IRC ... more

Overview

The BLE_API is a high level abstraction for using Bluetooth Low Energy on multiple platforms. For details and examples using the BLE_API please see the BLE_API Summary Page. Or click on the API Documentation tab above.

Supported Services

Supported services can be found in the BLE_API/services folder.

ble/ServiceDiscovery.h@1074:1fedc77d9add, 2016-01-11 (annotated)

Committer:
vcoubard
Date:
Mon Jan 11 08:51:42 2016 +0000
Revision:
1074:1fedc77d9add
Parent:
1063:187f9929cb60
Child:
1075:0d0dafb54bc9
Synchronized with git rev cd809e2a

Author: Andres Amaya Garcia

Modify shutdown API and functionality



Modify the shutdown API to remove the static shutdown function in Gap,

SecurityManager, GattClient and GattServer. Futhermore, remove the static

references to Gap, SecurityManager, GattClient and GattServer objects inside

their own classes. The cleanup method is renamed to `reset()` and made public.

Finally, additional functionality is added to the reset implementation in

Gap.

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 1074:1fedc77d9add 135 /**
vcoubard 1074:1fedc77d9add 136 * Clear all ServiceDiscovery state of the associated object.
vcoubard 1074:1fedc77d9add 137 *
vcoubard 1074:1fedc77d9add 138 * This function is meant to be overridden in the platform-specific
vcoubard 1074:1fedc77d9add 139 * sub-class. Nevertheless, the sub-class is only expected to reset its
vcoubard 1074:1fedc77d9add 140 * state and not the data held in ServiceDiscovery members. This shall be
vcoubard 1074:1fedc77d9add 141 * achieved by a call to ServiceDiscovery::reset() from the sub-class'
vcoubard 1074:1fedc77d9add 142 * reset() implementation.
vcoubard 1074:1fedc77d9add 143 *
vcoubard 1074:1fedc77d9add 144 * @return BLE_ERROR_NONE on success.
vcoubard 1074:1fedc77d9add 145 */
vcoubard 1074:1fedc77d9add 146 virtual ble_error_t reset(void) {
vcoubard 1074:1fedc77d9add 147 connHandle = 0;
vcoubard 1074:1fedc77d9add 148 matchingServiceUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN);
vcoubard 1074:1fedc77d9add 149 serviceCallback = NULL;
vcoubard 1074:1fedc77d9add 150 matchingCharacteristicUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN);
vcoubard 1074:1fedc77d9add 151 characteristicCallback = NULL;
vcoubard 1074:1fedc77d9add 152
vcoubard 1074:1fedc77d9add 153 return BLE_ERROR_NONE;
vcoubard 1074:1fedc77d9add 154 }
vcoubard 1074:1fedc77d9add 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__