Wang Xinglu / BLE_API

High level Bluetooth Low Energy API and radio abstraction layer

Dependencies:   nRF51822

Dependents:   LinkNode_LIS3DH

Fork of BLE_API by Bluetooth Low Energy

ble/ServiceDiscovery.h@1169:39f9a7bdf0a5, 2016-04-06 (annotated)

Committer:
vcoubard
Date:
Wed Apr 06 19:15:10 2016 +0100
Revision:
1169:39f9a7bdf0a5
Parent:
1135:22aada733dbd
Child:
1179:4ab722f8dca0
Synchronized with git rev 9d62d21e

Author: Andres Amaya Garcia

Add missing docs and fix doxy warnings in ServiceDiscovery.h

Who changed what in which revision?

UserRevisionLine numberNew contents of line
vcoubard 1131:692ddf04fc42 1 /* mbed Microcontroller Library
vcoubard 1131:692ddf04fc42 2 * Copyright (c) 2006-2013 ARM Limited
vcoubard 1131:692ddf04fc42 3 *
vcoubard 1131:692ddf04fc42 4 * Licensed under the Apache License, Version 2.0 (the "License");
vcoubard 1131:692ddf04fc42 5 * you may not use this file except in compliance with the License.
vcoubard 1131:692ddf04fc42 6 * You may obtain a copy of the License at
vcoubard 1131:692ddf04fc42 7 *
vcoubard 1131:692ddf04fc42 8 * http://www.apache.org/licenses/LICENSE-2.0
vcoubard 1131:692ddf04fc42 9 *
vcoubard 1131:692ddf04fc42 10 * Unless required by applicable law or agreed to in writing, software
vcoubard 1131:692ddf04fc42 11 * distributed under the License is distributed on an "AS IS" BASIS,
vcoubard 1131:692ddf04fc42 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
vcoubard 1131:692ddf04fc42 13 * See the License for the specific language governing permissions and
vcoubard 1131:692ddf04fc42 14 * limitations under the License.
vcoubard 1131:692ddf04fc42 15 */
vcoubard 1131:692ddf04fc42 16
vcoubard 1131:692ddf04fc42 17 #ifndef __SERVICE_DISOVERY_H__
vcoubard 1131:692ddf04fc42 18 #define __SERVICE_DISOVERY_H__
vcoubard 1131:692ddf04fc42 19
vcoubard 1131:692ddf04fc42 20 #include "UUID.h"
vcoubard 1131:692ddf04fc42 21 #include "Gap.h"
vcoubard 1131:692ddf04fc42 22 #include "GattAttribute.h"
vcoubard 1131:692ddf04fc42 23
vcoubard 1131:692ddf04fc42 24 class DiscoveredService;
vcoubard 1131:692ddf04fc42 25 class DiscoveredCharacteristic;
vcoubard 1131:692ddf04fc42 26
vcoubard 1131:692ddf04fc42 27 class ServiceDiscovery {
vcoubard 1131:692ddf04fc42 28 public:
vcoubard 1131:692ddf04fc42 29 /*
vcoubard 1131:692ddf04fc42 30 * Exposed application callback types.
vcoubard 1131:692ddf04fc42 31 */
vcoubard 1131:692ddf04fc42 32
vcoubard 1131:692ddf04fc42 33 /**
vcoubard 1131:692ddf04fc42 34 * Callback type for when a matching service is found during service-
vcoubard 1131:692ddf04fc42 35 * discovery. The receiving function is passed in a pointer to a
vcoubard 1131:692ddf04fc42 36 * DiscoveredService object, which will remain valid for the lifetime of the
vcoubard 1131:692ddf04fc42 37 * callback. Memory for this object is owned by the BLE_API eventing
vcoubard 1131:692ddf04fc42 38 * framework. The application can safely make a persistent shallow-copy of
vcoubard 1131:692ddf04fc42 39 * this object to work with the service beyond the callback.
vcoubard 1131:692ddf04fc42 40 */
vcoubard 1131:692ddf04fc42 41 typedef FunctionPointerWithContext<const DiscoveredService *> ServiceCallback_t;
vcoubard 1131:692ddf04fc42 42
vcoubard 1131:692ddf04fc42 43 /**
vcoubard 1131:692ddf04fc42 44 * Callback type for when a matching characteristic is found during service-
vcoubard 1131:692ddf04fc42 45 * discovery. The receiving function is passed in a pointer to a
vcoubard 1131:692ddf04fc42 46 * DiscoveredCharacteristic object, which will remain valid for the lifetime
vcoubard 1131:692ddf04fc42 47 * of the callback. Memory for this object is owned by the BLE_API eventing
vcoubard 1131:692ddf04fc42 48 * framework. The application can safely make a persistent shallow-copy of
vcoubard 1131:692ddf04fc42 49 * this object to work with the characteristic beyond the callback.
vcoubard 1131:692ddf04fc42 50 */
vcoubard 1131:692ddf04fc42 51 typedef FunctionPointerWithContext<const DiscoveredCharacteristic *> CharacteristicCallback_t;
vcoubard 1131:692ddf04fc42 52
vcoubard 1131:692ddf04fc42 53 /**
vcoubard 1131:692ddf04fc42 54 * Callback type for when serviceDiscovery terminates.
vcoubard 1131:692ddf04fc42 55 */
vcoubard 1131:692ddf04fc42 56 typedef FunctionPointerWithContext<Gap::Handle_t> TerminationCallback_t;
vcoubard 1131:692ddf04fc42 57
vcoubard 1131:692ddf04fc42 58 public:
vcoubard 1131:692ddf04fc42 59 /**
vcoubard 1131:692ddf04fc42 60 * Launch service discovery. Once launched, service discovery will remain
vcoubard 1131:692ddf04fc42 61 * active with callbacks being issued back into the application for matching
vcoubard 1131:692ddf04fc42 62 * services or characteristics. isActive() can be used to determine status, and
vcoubard 1131:692ddf04fc42 63 * a termination callback (if set up) will be invoked at the end. Service
vcoubard 1131:692ddf04fc42 64 * discovery can be terminated prematurely, if needed, using terminate().
vcoubard 1131:692ddf04fc42 65 *
vcoubard 1131:692ddf04fc42 66 * @param connectionHandle
vcoubard 1131:692ddf04fc42 67 * Handle for the connection with the peer.
vcoubard 1131:692ddf04fc42 68 * @param sc
vcoubard 1131:692ddf04fc42 69 * This is the application callback for a matching service. Taken as
vcoubard 1131:692ddf04fc42 70 * NULL by default. Note: service discovery may still be active
vcoubard 1131:692ddf04fc42 71 * when this callback is issued; calling asynchronous BLE-stack
vcoubard 1131:692ddf04fc42 72 * APIs from within this application callback might cause the
vcoubard 1131:692ddf04fc42 73 * stack to abort service discovery. If this becomes an issue, it
vcoubard 1131:692ddf04fc42 74 * may be better to make a local copy of the discoveredService and
vcoubard 1131:692ddf04fc42 75 * wait for service discovery to terminate before operating on the
vcoubard 1131:692ddf04fc42 76 * service.
vcoubard 1131:692ddf04fc42 77 * @param cc
vcoubard 1131:692ddf04fc42 78 * This is the application callback for a matching characteristic.
vcoubard 1131:692ddf04fc42 79 * Taken as NULL by default. Note: service discovery may still be
vcoubard 1131:692ddf04fc42 80 * active when this callback is issued; calling asynchronous
vcoubard 1131:692ddf04fc42 81 * BLE-stack APIs from within this application callback might cause
vcoubard 1131:692ddf04fc42 82 * the stack to abort service discovery. If this becomes an issue,
vcoubard 1131:692ddf04fc42 83 * it may be better to make a local copy of the discoveredCharacteristic
vcoubard 1131:692ddf04fc42 84 * and wait for service discovery to terminate before operating on the
vcoubard 1131:692ddf04fc42 85 * characteristic.
vcoubard 1131:692ddf04fc42 86 * @param matchingServiceUUID
vcoubard 1131:692ddf04fc42 87 * UUID-based filter for specifying a service in which the application is
vcoubard 1131:692ddf04fc42 88 * interested. By default it is set as the wildcard UUID_UNKNOWN,
vcoubard 1131:692ddf04fc42 89 * in which case it matches all services. If characteristic-UUID
vcoubard 1131:692ddf04fc42 90 * filter (below) is set to the wildcard value, then a service
vcoubard 1131:692ddf04fc42 91 * callback will be invoked for the matching service (or for every
vcoubard 1131:692ddf04fc42 92 * service if the service filter is a wildcard).
vcoubard 1131:692ddf04fc42 93 * @param matchingCharacteristicUUIDIn
vcoubard 1131:692ddf04fc42 94 * UUID-based filter for specifying a characteristic in which the application
vcoubard 1131:692ddf04fc42 95 * is interested. By default it is set as the wildcard UUID_UKNOWN
vcoubard 1131:692ddf04fc42 96 * to match against any characteristic. If both service-UUID
vcoubard 1131:692ddf04fc42 97 * filter and characteristic-UUID filter are used with non-wildcard
vcoubard 1131:692ddf04fc42 98 * values, then only a single characteristic callback is
vcoubard 1131:692ddf04fc42 99 * invoked for the matching characteristic.
vcoubard 1131:692ddf04fc42 100 *
vcoubard 1131:692ddf04fc42 101 * @note Using wildcard values for both service-UUID and characteristic-
vcoubard 1131:692ddf04fc42 102 * UUID will result in complete service discovery: callbacks being
vcoubard 1131:692ddf04fc42 103 * called for every service and characteristic.
vcoubard 1131:692ddf04fc42 104 *
vcoubard 1131:692ddf04fc42 105 * @note Providing NULL for the characteristic callback will result in
vcoubard 1131:692ddf04fc42 106 * characteristic discovery being skipped for each matching
vcoubard 1131:692ddf04fc42 107 * service. This allows for an inexpensive method to discover only
vcoubard 1131:692ddf04fc42 108 * services.
vcoubard 1131:692ddf04fc42 109 *
vcoubard 1131:692ddf04fc42 110 * @return
vcoubard 1131:692ddf04fc42 111 * BLE_ERROR_NONE if service discovery is launched successfully; else an appropriate error.
vcoubard 1131:692ddf04fc42 112 */
vcoubard 1131:692ddf04fc42 113 virtual ble_error_t launch(Gap::Handle_t connectionHandle,
vcoubard 1131:692ddf04fc42 114 ServiceCallback_t sc = NULL,
vcoubard 1131:692ddf04fc42 115 CharacteristicCallback_t cc = NULL,
vcoubard 1131:692ddf04fc42 116 const UUID &matchingServiceUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN),
vcoubard 1131:692ddf04fc42 117 const UUID &matchingCharacteristicUUIDIn = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN)) = 0;
vcoubard 1131:692ddf04fc42 118
vcoubard 1131:692ddf04fc42 119 /**
vcoubard 1169:39f9a7bdf0a5 120 * Check whether service-discovery is currently active.
vcoubard 1131:692ddf04fc42 121 */
vcoubard 1131:692ddf04fc42 122 virtual bool isActive(void) const = 0;
vcoubard 1131:692ddf04fc42 123
vcoubard 1131:692ddf04fc42 124 /**
vcoubard 1131:692ddf04fc42 125 * Terminate an ongoing service discovery. This should result in an
vcoubard 1131:692ddf04fc42 126 * invocation of the TerminationCallback if service discovery is active.
vcoubard 1131:692ddf04fc42 127 */
vcoubard 1131:692ddf04fc42 128 virtual void terminate(void) = 0;
vcoubard 1131:692ddf04fc42 129
vcoubard 1131:692ddf04fc42 130 /**
vcoubard 1131:692ddf04fc42 131 * Set up a callback to be invoked when service discovery is terminated.
vcoubard 1131:692ddf04fc42 132 */
vcoubard 1131:692ddf04fc42 133 virtual void onTermination(TerminationCallback_t callback) = 0;
vcoubard 1131:692ddf04fc42 134
vcoubard 1135:22aada733dbd 135 /**
vcoubard 1135:22aada733dbd 136 * Clear all ServiceDiscovery state of the associated object.
vcoubard 1135:22aada733dbd 137 *
vcoubard 1135:22aada733dbd 138 * This function is meant to be overridden in the platform-specific
vcoubard 1135:22aada733dbd 139 * sub-class. Nevertheless, the sub-class is only expected to reset its
vcoubard 1135:22aada733dbd 140 * state and not the data held in ServiceDiscovery members. This shall be
vcoubard 1135:22aada733dbd 141 * achieved by a call to ServiceDiscovery::reset() from the sub-class'
vcoubard 1135:22aada733dbd 142 * reset() implementation.
vcoubard 1135:22aada733dbd 143 *
vcoubard 1135:22aada733dbd 144 * @return BLE_ERROR_NONE on success.
vcoubard 1135:22aada733dbd 145 */
vcoubard 1135:22aada733dbd 146 virtual ble_error_t reset(void) {
vcoubard 1135:22aada733dbd 147 connHandle = 0;
vcoubard 1135:22aada733dbd 148 matchingServiceUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN);
vcoubard 1135:22aada733dbd 149 serviceCallback = NULL;
vcoubard 1135:22aada733dbd 150 matchingCharacteristicUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN);
vcoubard 1135:22aada733dbd 151 characteristicCallback = NULL;
vcoubard 1135:22aada733dbd 152
vcoubard 1135:22aada733dbd 153 return BLE_ERROR_NONE;
vcoubard 1135:22aada733dbd 154 }
vcoubard 1135:22aada733dbd 155
vcoubard 1131:692ddf04fc42 156 protected:
vcoubard 1169:39f9a7bdf0a5 157 /**
vcoubard 1169:39f9a7bdf0a5 158 * Connection handle as provided by the SoftDevice.
vcoubard 1169:39f9a7bdf0a5 159 */
vcoubard 1169:39f9a7bdf0a5 160 Gap::Handle_t connHandle;
vcoubard 1169:39f9a7bdf0a5 161 /**
vcoubard 1169:39f9a7bdf0a5 162 * UUID-based filter that specifies the service that the application is
vcoubard 1169:39f9a7bdf0a5 163 * interested in.
vcoubard 1169:39f9a7bdf0a5 164 */
vcoubard 1131:692ddf04fc42 165 UUID matchingServiceUUID;
vcoubard 1169:39f9a7bdf0a5 166 /**
vcoubard 1169:39f9a7bdf0a5 167 * The registered callback handle for when a matching service is found
vcoubard 1169:39f9a7bdf0a5 168 * during service-discovery.
vcoubard 1169:39f9a7bdf0a5 169 */
vcoubard 1131:692ddf04fc42 170 ServiceCallback_t serviceCallback;
vcoubard 1169:39f9a7bdf0a5 171 /**
vcoubard 1169:39f9a7bdf0a5 172 * UUID-based filter that specifies the characteristic that the
vcoubard 1169:39f9a7bdf0a5 173 * application is interested in.
vcoubard 1169:39f9a7bdf0a5 174 */
vcoubard 1131:692ddf04fc42 175 UUID matchingCharacteristicUUID;
vcoubard 1169:39f9a7bdf0a5 176 /**
vcoubard 1169:39f9a7bdf0a5 177 * The registered callback handler for when a matching characteristic is
vcoubard 1169:39f9a7bdf0a5 178 * found during service-discovery.
vcoubard 1169:39f9a7bdf0a5 179 */
vcoubard 1131:692ddf04fc42 180 CharacteristicCallback_t characteristicCallback;
vcoubard 1131:692ddf04fc42 181 };
vcoubard 1131:692ddf04fc42 182
vcoubard 1169:39f9a7bdf0a5 183 #endif /* ifndef __SERVICE_DISOVERY_H__ */