Marco Ferreira / BLE_API

just a fork

Fork of BLE_API by Bluetooth Low Energy

ble/ServiceDiscovery.h@716:11b41f651697, 2015-07-02 (annotated)

Committer:
rgrover1
Date:
Thu Jul 02 09:06:11 2015 +0100
Revision:
716:11b41f651697
Child:
910:77ca47abaecf
Synchronized with git rev d80fec88

Author: Rohit Grover

Release 0.4.0

=============



This is a major release which introduces the GATT Client functionality. It

also aligns BLE_API with builds using our new package manager: yotta

(https://github.com/armmbed/yotta).



Many APIs have seen some redesign. We encourage our users to pay attention to

the changes and migrate appropriately over time. We've also taken care to

ensure that existing code continues to work the same way. There's more

documentation in the form of comment headers for APIs to explain proper usage;

in many cases comment headers suggest alternative use of APIs.



Enhancements

~~~~~~~~~~~~



* Introduce GattClient. This includes functionality for service-discovery,

  connections, and attribute-reads and writes. You'll find a demo program for

  LEDBlinker on the mbed.org Bluetooth team page to use the new APIs. Some of

  the GATT client functionality hasn't been implemented yet, but the APIs have

  been added.



* Most APIs in the abstract base classes like Gap and GattServer return

  BLE_ERROR_NOT_IMPLEMENTED. Previously many APIs were pure-virtual, which did

  not permit partial ports to compile.



* We've added a new abstract base class for SecurityManager. All security

  related APIs have been moved into that.



* BLEDevice has been renamed as BLE. A deprecated alias for BLEDevice is

  available to support existing code.



* There has been a major cleanup of APIs under BLE. APIs have now been

  categorized as belonging to Gap, GattServer, GattClient, or SecurityManager.

  There are accessors to get references for Gap, GattServer, GattClient, and

  SecurityManager. A former call to ble.setAddress(...) is now expected to be

  achieved with ble.gap().setAddress(...).



* We've cleaned up our APIs, and this has resulted in dropping some APIs like

  BLE::reset().



* We've also dropped GattServer::initializeGattDatabase(). THis was added at

  some point to support controllers where a commit point was needed to

  indicate when the application had finished constructing the GATT database.

  This API would get called internally before Gap::startAdvertising(). We now

  expect the underlying port to do the equivalent of initializeGattDatabase()

  implicitly upon Gap::startAdvertising().



* The callback for BLE.onTimeout() now receives a TimeoutSource_t to indicate

  the cause of the timeout. This is perhaps the only breaking API change. We

  expect it to have very little disruptive effect.



* We've added a version of Gap::disconnect() which takes a connection handle.

  The previous API (which did not take a connection handle) has been

  deprecated; it will still work for situations where there's only a single

  active connection. We hold on to that API to allow existing code to migrate

  to the new API.



Bugfixes

~~~~~~~~



* None.

Who changed what in which revision?

UserRevisionLine numberNew 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 716:11b41f651697 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 716:11b41f651697 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 716:11b41f651697 39 * this object in order to work with the service beyond the callback.
rgrover1 716:11b41f651697 40 */
rgrover1 716:11b41f651697 41 typedef void (*ServiceCallback_t)(const DiscoveredService *);
rgrover1 716:11b41f651697 42
rgrover1 716:11b41f651697 43 /**
rgrover1 716:11b41f651697 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 716:11b41f651697 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 716:11b41f651697 49 * this object in order to work with the characteristic beyond the callback.
rgrover1 716:11b41f651697 50 */
rgrover1 716:11b41f651697 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 716:11b41f651697 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 716:11b41f651697 62 * services/characteristics. isActive() can be used to determine status; and
rgrover1 716:11b41f651697 63 * a termination callback (if setup) will be invoked at the end. Service
rgrover1 716:11b41f651697 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 716:11b41f651697 69 * This is the application callback for 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 716:11b41f651697 74 * may be better to make 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 716:11b41f651697 78 * This is the application callback for 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 716:11b41f651697 83 * it may be better to make 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 716:11b41f651697 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 716:11b41f651697 94 * UUID based filter for specifying 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 716:11b41f651697 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 716:11b41f651697 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 716:11b41f651697 125 * Terminate an ongoing service-discovery. This should result in an
rgrover1 716:11b41f651697 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 716:11b41f651697 131 * Setup 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__