Cataract Gemuese / BLE_API

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.

Fork of BLE_API by Bluetooth Low Energy

public/ServiceDiscovery.h@479:dbcb964cc288, 2015-06-19 (annotated)

Committer:
rgrover1
Date:
Fri Jun 19 15:52:00 2015 +0100
Revision:
479:dbcb964cc288
Parent:
478:230cd5e207ba
Child:
482:a4c6ac278fd4
Synchronized with git rev 1ccaaa5a

Author: Rohit Grover

document headers for the serviceDiscovery API.

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 478:230cd5e207ba 31 typedef void (*ServiceCallback_t)(const DiscoveredService *);
rgrover1 476:122bcbdadb56 32 typedef void (*CharacteristicCallback_t)(const DiscoveredCharacteristic *);
rgrover1 457:6ebc9bbde90b 33 typedef void (*TerminationCallback_t)(Gap::Handle_t connectionHandle);
rgrover1 431:1c8c592430ec 34
rgrover1 431:1c8c592430ec 35 public:
rgrover1 479:dbcb964cc288 36 /**
rgrover1 479:dbcb964cc288 37 * Launch service discovery. Once launched, service discovery will remain
rgrover1 479:dbcb964cc288 38 * active with callbacks being issued back into the application for matching
rgrover1 479:dbcb964cc288 39 * services/characteristics. isActive() can be used to determine status; and
rgrover1 479:dbcb964cc288 40 * a termination callback (if setup) will be invoked at the end. Service
rgrover1 479:dbcb964cc288 41 * discovery can be terminated prematurely if needed using terminate().
rgrover1 479:dbcb964cc288 42 *
rgrover1 479:dbcb964cc288 43 * @param connectionHandle
rgrover1 479:dbcb964cc288 44 * Handle for the connection with the peer.
rgrover1 479:dbcb964cc288 45 * @param sc
rgrover1 479:dbcb964cc288 46 * This is the application callback for matching service. Taken as
rgrover1 479:dbcb964cc288 47 * NULL by default. Note: service discovery may still be active
rgrover1 479:dbcb964cc288 48 * when this callback is issued; calling asynchronous BLE-stack
rgrover1 479:dbcb964cc288 49 * APIs from within this application callback might cause the
rgrover1 479:dbcb964cc288 50 * stack to abort service discovery. If this becomes an issue, it
rgrover1 479:dbcb964cc288 51 * may be better to make local copy of the discoveredService and
rgrover1 479:dbcb964cc288 52 * wait for service discovery to terminate before operating on the
rgrover1 479:dbcb964cc288 53 * service.
rgrover1 479:dbcb964cc288 54 * @param cc
rgrover1 479:dbcb964cc288 55 * This is the application callback for matching characteristic.
rgrover1 479:dbcb964cc288 56 * Taken as NULL by default. Note: service discovery may still be
rgrover1 479:dbcb964cc288 57 * active when this callback is issued; calling asynchronous
rgrover1 479:dbcb964cc288 58 * BLE-stack APIs from within this application callback might cause
rgrover1 479:dbcb964cc288 59 * the stack to abort service discovery. If this becomes an issue,
rgrover1 479:dbcb964cc288 60 * it may be better to make local copy of the discoveredCharacteristic
rgrover1 479:dbcb964cc288 61 * and wait for service discovery to terminate before operating on the
rgrover1 479:dbcb964cc288 62 * characteristic.
rgrover1 479:dbcb964cc288 63 * @param matchingServiceUUID
rgrover1 479:dbcb964cc288 64 * UUID based filter for specifying a service in which the application is
rgrover1 479:dbcb964cc288 65 * interested. By default it is set as the wildcard UUID_UNKNOWN,
rgrover1 479:dbcb964cc288 66 * in which case it matches all services. If characteristic-UUID
rgrover1 479:dbcb964cc288 67 * filter (below) is set to the wildcard value, then a service
rgrover1 479:dbcb964cc288 68 * callback will be invoked for the matching service (or for every
rgrover1 479:dbcb964cc288 69 * service if the service filter is a wildcard).
rgrover1 479:dbcb964cc288 70 * @param matchingCharacteristicUUIDIn
rgrover1 479:dbcb964cc288 71 * UUID based filter for specifying characteristic in which the application
rgrover1 479:dbcb964cc288 72 * is interested. By default it is set as the wildcard UUID_UKNOWN
rgrover1 479:dbcb964cc288 73 * to match against any characteristic. If both service-UUID
rgrover1 479:dbcb964cc288 74 * filter and characteristic-UUID filter are used with non- wildcard
rgrover1 479:dbcb964cc288 75 * values, then only a single characteristic callback is
rgrover1 479:dbcb964cc288 76 * invoked for the matching characteristic.
rgrover1 479:dbcb964cc288 77 *
rgrover1 479:dbcb964cc288 78 * @return
rgrover1 479:dbcb964cc288 79 * BLE_ERROR_NONE if service discovery is launched successfully; else an appropriate error.
rgrover1 479:dbcb964cc288 80 */
rgrover1 456:ff4ffb69e19f 81 static ble_error_t launch(Gap::Handle_t connectionHandle,
rgrover1 456:ff4ffb69e19f 82 ServiceCallback_t sc = NULL,
rgrover1 456:ff4ffb69e19f 83 CharacteristicCallback_t cc = NULL,
rgrover1 458:5546ebd25359 84 const UUID &matchingServiceUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN),
rgrover1 458:5546ebd25359 85 const UUID &matchingCharacteristicUUIDIn = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN));
rgrover1 431:1c8c592430ec 86
rgrover1 474:2a8a453ecd7e 87 /**
rgrover1 474:2a8a453ecd7e 88 * Terminate an ongoing service-discovery. This should result in an
rgrover1 474:2a8a453ecd7e 89 * invocation of the TerminationCallback if service-discovery is active.
rgrover1 474:2a8a453ecd7e 90 */
rgrover1 431:1c8c592430ec 91 static void terminate(void);
rgrover1 431:1c8c592430ec 92
rgrover1 474:2a8a453ecd7e 93 /**
rgrover1 474:2a8a453ecd7e 94 * Is service-discovery currently active?
rgrover1 474:2a8a453ecd7e 95 */
rgrover1 457:6ebc9bbde90b 96 static bool isActive(void);
rgrover1 474:2a8a453ecd7e 97
rgrover1 474:2a8a453ecd7e 98 /**
rgrover1 474:2a8a453ecd7e 99 * Setup callback to be invoked when service discovery is terminated.
rgrover1 474:2a8a453ecd7e 100 */
rgrover1 457:6ebc9bbde90b 101 static void onTermination(TerminationCallback_t callback);
rgrover1 457:6ebc9bbde90b 102
rgrover1 431:1c8c592430ec 103 protected:
rgrover1 431:1c8c592430ec 104 Gap::Handle_t connHandle; /**< Connection handle as provided by the SoftDevice. */
rgrover1 431:1c8c592430ec 105 UUID matchingServiceUUID;
rgrover1 431:1c8c592430ec 106 ServiceCallback_t serviceCallback;
rgrover1 431:1c8c592430ec 107 UUID matchingCharacteristicUUID;
rgrover1 431:1c8c592430ec 108 CharacteristicCallback_t characteristicCallback;
rgrover1 431:1c8c592430ec 109 };
rgrover1 431:1c8c592430ec 110
rgrover1 431:1c8c592430ec 111 #endif // ifndef __SERVICE_DISOVERY_H__