Cristi Stoican / BLE_API

jgh

Dependents:   Migration

Fork of BLE_API by Bluetooth Low Energy

public/ServiceDiscovery.h@487:07d4423e442b, 2015-06-19 (annotated)

Committer:
rgrover1
Date:
Fri Jun 19 15:52:01 2015 +0100
Revision:
487:07d4423e442b
Parent:
482:a4c6ac278fd4
Child:
497:926d444599e8
Synchronized with git rev ecdb5f51

Author: Rohit Grover

Add comments to explain memory lifetimes for the discovered objects within discovery callbacks.

Who changed what in which revision?

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