add "LE Device Address" 0x1B to advertising data types
Fork of BLE_API by
ble/ServiceDiscovery.h@934:5e3acddfcd82, 2015-11-26 (annotated)
- Committer:
- rgrover1
- Date:
- Thu Nov 26 12:52:06 2015 +0000
- Revision:
- 934:5e3acddfcd82
- Parent:
- 933:3ec277a0d780
- Child:
- 935:e9b595e6b0ed
Synchronized with git rev fea34e77
Author: Marcus Chang
Updated GapAdvertisementData.h to handle insertion and appending of data fields. Made appendField private.
Who changed what in which revision?
User | Revision | Line number | New 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 | 934:5e3acddfcd82 | 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 | 934:5e3acddfcd82 | 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 | 934:5e3acddfcd82 | 39 | * this object to work with the service beyond the callback. |
rgrover1 | 716:11b41f651697 | 40 | */ |
rgrover1 | 933:3ec277a0d780 | 41 | typedef void (*ServiceCallback_t)(const DiscoveredService *); |
rgrover1 | 716:11b41f651697 | 42 | |
rgrover1 | 716:11b41f651697 | 43 | /** |
rgrover1 | 934:5e3acddfcd82 | 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 | 934:5e3acddfcd82 | 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 | 934:5e3acddfcd82 | 49 | * this object to work with the characteristic beyond the callback. |
rgrover1 | 716:11b41f651697 | 50 | */ |
rgrover1 | 933:3ec277a0d780 | 51 | typedef void (*CharacteristicCallback_t)(const DiscoveredCharacteristic *); |
rgrover1 | 716:11b41f651697 | 52 | |
rgrover1 | 716:11b41f651697 | 53 | /** |
rgrover1 | 716:11b41f651697 | 54 | * Callback type for when serviceDiscovery terminates. |
rgrover1 | 716:11b41f651697 | 55 | */ |
rgrover1 | 933:3ec277a0d780 | 56 | typedef void (*TerminationCallback_t)(Gap::Handle_t connectionHandle); |
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 | 934:5e3acddfcd82 | 62 | * services or characteristics. isActive() can be used to determine status, and |
rgrover1 | 934:5e3acddfcd82 | 63 | * a termination callback (if set up) will be invoked at the end. Service |
rgrover1 | 934:5e3acddfcd82 | 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 | 934:5e3acddfcd82 | 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 | 934:5e3acddfcd82 | 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 | 934:5e3acddfcd82 | 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 | 934:5e3acddfcd82 | 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 | 934:5e3acddfcd82 | 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 | 934:5e3acddfcd82 | 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 | 934:5e3acddfcd82 | 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 | 934:5e3acddfcd82 | 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 | 934:5e3acddfcd82 | 125 | * Terminate an ongoing service discovery. This should result in an |
rgrover1 | 934:5e3acddfcd82 | 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 | 934:5e3acddfcd82 | 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__ |