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@993:4d62b7967c11, 2015-12-02 (annotated)

Committer:
rgrover1
Date:
Wed Dec 02 10:29:44 2015 +0000
Revision:
993:4d62b7967c11
Parent:
992:ca834f7ae8ed
Child:
1042:21a86ac7f5b1
Synchronized with git rev 12e27cd4

Author: Rohit Grover

Release 2.1.3

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



* Improvements to CallChainOfFunctionPointerswithContext:

  - add a `detach` function to be able to remove callbacks.

  - detach function now return true if a function has been detached and

    false otherwise.

  - add a function call operator.

  - use safe-bool idiom. see : http://www.artima.com/cppsource/safebool.html



* Add SafeBool class which allow to easily declare a safe bool operator in

  c++03.



* Improvements to FunctionPointerWithContext:

  - fix call propagation

  - use safe bool idiom



* Add config file for generating Doxygen.



* Setup for onRadioNotification callback does not call initRadioNotification

  anymore.



* GapAdvertisementData now handles replacement and appending of data fields

  based on type. Some fields can be replaced with new values, and others

  require the payload to be appended.

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 /**
rgrover1 993:4d62b7967c11 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
rgrover1 993:4d62b7967c11 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
rgrover1 993:4d62b7967c11 39 * this object to work with the service beyond the callback.
rgrover1 716:11b41f651697 40 */
rgrover1 993:4d62b7967c11 41 typedef FunctionPointerWithContext<const DiscoveredService *> ServiceCallback_t;
rgrover1 716:11b41f651697 42
rgrover1 716:11b41f651697 43 /**
rgrover1 993:4d62b7967c11 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
rgrover1 993:4d62b7967c11 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
rgrover1 993:4d62b7967c11 49 * this object to work with the characteristic beyond the callback.
rgrover1 716:11b41f651697 50 */
rgrover1 993:4d62b7967c11 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 */
rgrover1 993:4d62b7967c11 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
rgrover1 993:4d62b7967c11 62 * services or characteristics. isActive() can be used to determine status, and
rgrover1 993:4d62b7967c11 63 * a termination callback (if set up) will be invoked at the end. Service
rgrover1 993:4d62b7967c11 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
rgrover1 993:4d62b7967c11 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
rgrover1 993:4d62b7967c11 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
rgrover1 993:4d62b7967c11 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,
rgrover1 993:4d62b7967c11 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
rgrover1 993:4d62b7967c11 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
rgrover1 993:4d62b7967c11 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
rgrover1 993:4d62b7967c11 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-
rgrover1 993:4d62b7967c11 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 /**
rgrover1 993:4d62b7967c11 125 * Terminate an ongoing service discovery. This should result in an
rgrover1 993:4d62b7967c11 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 /**
rgrover1 993:4d62b7967c11 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
rgrover1 716:11b41f651697 135 protected:
rgrover1 716:11b41f651697 136 Gap::Handle_t connHandle; /**< Connection handle as provided by the SoftDevice. */
rgrover1 716:11b41f651697 137 UUID matchingServiceUUID;
rgrover1 716:11b41f651697 138 ServiceCallback_t serviceCallback;
rgrover1 716:11b41f651697 139 UUID matchingCharacteristicUUID;
rgrover1 716:11b41f651697 140 CharacteristicCallback_t characteristicCallback;
rgrover1 716:11b41f651697 141 };
rgrover1 716:11b41f651697 142
rgrover1 716:11b41f651697 143 #endif // ifndef __SERVICE_DISOVERY_H__