ON Semiconductor / mbed-os

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Dependents:   mbed-TFT-example-NCS36510 mbed-Accelerometer-example-NCS36510 mbed-Accelerometer-example-NCS36510

features/FEATURE_BLE/ble/ServiceDiscovery.h@0:098463de4c5d, 2017-01-25 (annotated)

Committer:
group-onsemi
Date:
Wed Jan 25 20:34:15 2017 +0000
Revision:
0:098463de4c5d
Initial commit

Who changed what in which revision?

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