BLE_API for nRF51
Fork of BLE_API by
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?
User | Revision | Line number | New 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__ |