YuLin Jiang / nRF51BLE_API

BLE_API for nRF51

Fork of BLE_API by Bluetooth Low Energy

public/ServiceDiscovery.h@562:ad06c59db307, 2015-06-19 (annotated)

Committer:
rgrover1
Date:
Fri Jun 19 15:52:11 2015 +0100
Revision:
562:ad06c59db307
Parent:
524:6e97ab392e2a 
Synchronized with git rev d11a0b04

Author: Rohit Grover

update comment block for launchServiceDiscovery()

Who changed what in which revision?

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