Cristi Stoican / BLE_API

jgh

Dependents:   Migration

Fork of BLE_API by Bluetooth Low Energy

ble/ServiceDiscovery.h@1131:692ddf04fc42, 2016-04-06 (annotated)

Committer:
vcoubard
Date:
Wed Apr 06 19:13:46 2016 +0100
Revision:
1131:692ddf04fc42
Parent:
1084:40c1e518d6de
Child:
1135:22aada733dbd
Synchronized with git rev 13bf70b6

Author: Rohit Grover

Release 2.1.5

=============



A minor release to separate the concept of minlen and len in

GattCharacteristic. Also contains some improvements to documentation.

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 1131:692ddf04fc42 120 * Is service-discovery 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 1131:692ddf04fc42 135 protected:
vcoubard 1131:692ddf04fc42 136 Gap::Handle_t connHandle; /**< Connection handle as provided by the SoftDevice. */
vcoubard 1131:692ddf04fc42 137 UUID matchingServiceUUID;
vcoubard 1131:692ddf04fc42 138 ServiceCallback_t serviceCallback;
vcoubard 1131:692ddf04fc42 139 UUID matchingCharacteristicUUID;
vcoubard 1131:692ddf04fc42 140 CharacteristicCallback_t characteristicCallback;
vcoubard 1131:692ddf04fc42 141 };
vcoubard 1131:692ddf04fc42 142
rgrover1 716:11b41f651697 143 #endif // ifndef __SERVICE_DISOVERY_H__