Productize / nRF51822

library for BLE_GAP_backpack

Dependencies:   nrf51-sdk

Fork of nRF51822 by Nordic Semiconductor

source/nRF5xGattClient.h@567:e1800bd55a9e, 2016-01-11 (annotated)

Committer:
vcoubard
Date:
Mon Jan 11 10:19:19 2016 +0000
Revision:
567:e1800bd55a9e
Parent:
566:e425ad9e5d6e
Child:
570:f162898cb6c4
Synchronized with git rev 59ced0b4

Author: Vincent Coubard

rename remainingCharacteristic member, now it is named

discoveredCharacteristic. Add doc to the discovery process and the

rationale behind discoveredCharacteristic member.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
vcoubard 542:1bf9c597f44f 1 /* mbed Microcontroller Library
vcoubard 542:1bf9c597f44f 2 * Copyright (c) 2006-2013 ARM Limited
vcoubard 542:1bf9c597f44f 3 *
vcoubard 542:1bf9c597f44f 4 * Licensed under the Apache License, Version 2.0 (the "License");
vcoubard 542:1bf9c597f44f 5 * you may not use this file except in compliance with the License.
vcoubard 542:1bf9c597f44f 6 * You may obtain a copy of the License at
vcoubard 542:1bf9c597f44f 7 *
vcoubard 542:1bf9c597f44f 8 * http://www.apache.org/licenses/LICENSE-2.0
vcoubard 542:1bf9c597f44f 9 *
vcoubard 542:1bf9c597f44f 10 * Unless required by applicable law or agreed to in writing, software
vcoubard 542:1bf9c597f44f 11 * distributed under the License is distributed on an "AS IS" BASIS,
vcoubard 542:1bf9c597f44f 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
vcoubard 542:1bf9c597f44f 13 * See the License for the specific language governing permissions and
vcoubard 542:1bf9c597f44f 14 * limitations under the License.
vcoubard 542:1bf9c597f44f 15 */
vcoubard 542:1bf9c597f44f 16
vcoubard 542:1bf9c597f44f 17 #ifndef __NRF51822_GATT_CLIENT_H__
vcoubard 542:1bf9c597f44f 18 #define __NRF51822_GATT_CLIENT_H__
vcoubard 542:1bf9c597f44f 19
vcoubard 542:1bf9c597f44f 20 #include "ble/GattClient.h"
vcoubard 542:1bf9c597f44f 21 #include "nRF5xServiceDiscovery.h"
vcoubard 567:e1800bd55a9e 22 #include "nRF5xCharacteristicDescriptorDiscoverer.h"
vcoubard 542:1bf9c597f44f 23
vcoubard 542:1bf9c597f44f 24 class nRF5xGattClient : public GattClient
vcoubard 542:1bf9c597f44f 25 {
vcoubard 542:1bf9c597f44f 26 public:
vcoubard 566:e425ad9e5d6e 27 static nRF5xGattClient &getInstance();
vcoubard 566:e425ad9e5d6e 28
vcoubard 542:1bf9c597f44f 29 /**
vcoubard 542:1bf9c597f44f 30 * When using S110, all Gatt client features will return
vcoubard 542:1bf9c597f44f 31 * BLE_ERROR_NOT_IMPLEMENTED
vcoubard 542:1bf9c597f44f 32 */
vcoubard 542:1bf9c597f44f 33 #if !defined(TARGET_MCU_NRF51_16K_S110) && !defined(TARGET_MCU_NRF51_32K_S110)
vcoubard 542:1bf9c597f44f 34
vcoubard 542:1bf9c597f44f 35 /**
vcoubard 542:1bf9c597f44f 36 * Launch service discovery. Once launched, service discovery will remain
vcoubard 542:1bf9c597f44f 37 * active with callbacks being issued back into the application for matching
vcoubard 542:1bf9c597f44f 38 * services/characteristics. isActive() can be used to determine status; and
vcoubard 542:1bf9c597f44f 39 * a termination callback (if setup) will be invoked at the end. Service
vcoubard 542:1bf9c597f44f 40 * discovery can be terminated prematurely if needed using terminate().
vcoubard 542:1bf9c597f44f 41 *
vcoubard 542:1bf9c597f44f 42 * @param connectionHandle
vcoubard 542:1bf9c597f44f 43 * Handle for the connection with the peer.
vcoubard 542:1bf9c597f44f 44 * @param sc
vcoubard 542:1bf9c597f44f 45 * This is the application callback for matching service. Taken as
vcoubard 542:1bf9c597f44f 46 * NULL by default. Note: service discovery may still be active
vcoubard 542:1bf9c597f44f 47 * when this callback is issued; calling asynchronous BLE-stack
vcoubard 542:1bf9c597f44f 48 * APIs from within this application callback might cause the
vcoubard 542:1bf9c597f44f 49 * stack to abort service discovery. If this becomes an issue, it
vcoubard 542:1bf9c597f44f 50 * may be better to make local copy of the discoveredService and
vcoubard 542:1bf9c597f44f 51 * wait for service discovery to terminate before operating on the
vcoubard 542:1bf9c597f44f 52 * service.
vcoubard 542:1bf9c597f44f 53 * @param cc
vcoubard 542:1bf9c597f44f 54 * This is the application callback for matching characteristic.
vcoubard 542:1bf9c597f44f 55 * Taken as NULL by default. Note: service discovery may still be
vcoubard 542:1bf9c597f44f 56 * active when this callback is issued; calling asynchronous
vcoubard 542:1bf9c597f44f 57 * BLE-stack APIs from within this application callback might cause
vcoubard 542:1bf9c597f44f 58 * the stack to abort service discovery. If this becomes an issue,
vcoubard 542:1bf9c597f44f 59 * it may be better to make local copy of the discoveredCharacteristic
vcoubard 542:1bf9c597f44f 60 * and wait for service discovery to terminate before operating on the
vcoubard 542:1bf9c597f44f 61 * characteristic.
vcoubard 542:1bf9c597f44f 62 * @param matchingServiceUUID
vcoubard 542:1bf9c597f44f 63 * UUID based filter for specifying a service in which the application is
vcoubard 542:1bf9c597f44f 64 * interested. By default it is set as the wildcard UUID_UNKNOWN,
vcoubard 542:1bf9c597f44f 65 * in which case it matches all services. If characteristic-UUID
vcoubard 542:1bf9c597f44f 66 * filter (below) is set to the wildcard value, then a service
vcoubard 542:1bf9c597f44f 67 * callback will be invoked for the matching service (or for every
vcoubard 542:1bf9c597f44f 68 * service if the service filter is a wildcard).
vcoubard 542:1bf9c597f44f 69 * @param matchingCharacteristicUUIDIn
vcoubard 542:1bf9c597f44f 70 * UUID based filter for specifying characteristic in which the application
vcoubard 542:1bf9c597f44f 71 * is interested. By default it is set as the wildcard UUID_UKNOWN
vcoubard 542:1bf9c597f44f 72 * to match against any characteristic. If both service-UUID
vcoubard 542:1bf9c597f44f 73 * filter and characteristic-UUID filter are used with non- wildcard
vcoubard 542:1bf9c597f44f 74 * values, then only a single characteristic callback is
vcoubard 542:1bf9c597f44f 75 * invoked for the matching characteristic.
vcoubard 542:1bf9c597f44f 76 *
vcoubard 542:1bf9c597f44f 77 * @Note Using wildcard values for both service-UUID and characteristic-
vcoubard 542:1bf9c597f44f 78 * UUID will result in complete service discovery--callbacks being
vcoubard 542:1bf9c597f44f 79 * called for every service and characteristic.
vcoubard 542:1bf9c597f44f 80 *
vcoubard 542:1bf9c597f44f 81 * @return
vcoubard 542:1bf9c597f44f 82 * BLE_ERROR_NONE if service discovery is launched successfully; else an appropriate error.
vcoubard 542:1bf9c597f44f 83 */
vcoubard 542:1bf9c597f44f 84 virtual ble_error_t launchServiceDiscovery(Gap::Handle_t connectionHandle,
vcoubard 542:1bf9c597f44f 85 ServiceDiscovery::ServiceCallback_t sc = NULL,
vcoubard 542:1bf9c597f44f 86 ServiceDiscovery::CharacteristicCallback_t cc = NULL,
vcoubard 542:1bf9c597f44f 87 const UUID &matchingServiceUUID = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN),
vcoubard 542:1bf9c597f44f 88 const UUID &matchingCharacteristicUUIDIn = UUID::ShortUUIDBytes_t(BLE_UUID_UNKNOWN));
vcoubard 542:1bf9c597f44f 89
vcoubard 542:1bf9c597f44f 90 virtual void onServiceDiscoveryTermination(ServiceDiscovery::TerminationCallback_t callback) {
vcoubard 567:e1800bd55a9e 91 _discovery.onTermination(callback);
vcoubard 542:1bf9c597f44f 92 }
vcoubard 542:1bf9c597f44f 93
vcoubard 542:1bf9c597f44f 94 /**
vcoubard 542:1bf9c597f44f 95 * Is service-discovery currently active?
vcoubard 542:1bf9c597f44f 96 */
vcoubard 542:1bf9c597f44f 97 virtual bool isServiceDiscoveryActive(void) const {
vcoubard 567:e1800bd55a9e 98 return _discovery.isActive();
vcoubard 542:1bf9c597f44f 99 }
vcoubard 542:1bf9c597f44f 100
vcoubard 542:1bf9c597f44f 101 /**
vcoubard 542:1bf9c597f44f 102 * Terminate an ongoing service-discovery. This should result in an
vcoubard 542:1bf9c597f44f 103 * invocation of the TerminationCallback if service-discovery is active.
vcoubard 542:1bf9c597f44f 104 */
vcoubard 542:1bf9c597f44f 105 virtual void terminateServiceDiscovery(void) {
vcoubard 567:e1800bd55a9e 106 _discovery.terminate();
vcoubard 542:1bf9c597f44f 107 }
vcoubard 542:1bf9c597f44f 108
vcoubard 567:e1800bd55a9e 109 /**
vcoubard 567:e1800bd55a9e 110 * @brief Implementation of GattClient::discoverCharacteristicDescriptors
vcoubard 567:e1800bd55a9e 111 * @see GattClient::discoverCharacteristicDescriptors
vcoubard 567:e1800bd55a9e 112 */
vcoubard 567:e1800bd55a9e 113 virtual ble_error_t discoverCharacteristicDescriptors(
vcoubard 567:e1800bd55a9e 114 const DiscoveredCharacteristic& characteristic,
vcoubard 567:e1800bd55a9e 115 const CharacteristicDescriptorDiscovery::DiscoveryCallback_t& discoveryCallback,
vcoubard 567:e1800bd55a9e 116 const CharacteristicDescriptorDiscovery::TerminationCallback_t& terminationCallback
vcoubard 567:e1800bd55a9e 117 );
vcoubard 567:e1800bd55a9e 118
vcoubard 567:e1800bd55a9e 119 /**
vcoubard 567:e1800bd55a9e 120 * @brief Implementation of GattClient::isCharacteristicDiscoveryActive
vcoubard 567:e1800bd55a9e 121 * @see GattClient::isCharacteristicDiscoveryActive
vcoubard 567:e1800bd55a9e 122 */
vcoubard 567:e1800bd55a9e 123 virtual bool isCharacteristicDescriptorsDiscoveryActive(const DiscoveredCharacteristic& characteristic) const;
vcoubard 567:e1800bd55a9e 124
vcoubard 567:e1800bd55a9e 125 /**
vcoubard 567:e1800bd55a9e 126 * @brief Implementation of GattClient::terminateCharacteristicDiscovery
vcoubard 567:e1800bd55a9e 127 * @see GattClient::terminateCharacteristicDiscovery
vcoubard 567:e1800bd55a9e 128 */
vcoubard 567:e1800bd55a9e 129 virtual void terminateCharacteristicDescriptorsDiscovery(const DiscoveredCharacteristic& characteristic);
vcoubard 567:e1800bd55a9e 130
vcoubard 542:1bf9c597f44f 131 virtual ble_error_t read(Gap::Handle_t connHandle, GattAttribute::Handle_t attributeHandle, uint16_t offset) const {
vcoubard 542:1bf9c597f44f 132 uint32_t rc = sd_ble_gattc_read(connHandle, attributeHandle, offset);
vcoubard 542:1bf9c597f44f 133 if (rc == NRF_SUCCESS) {
vcoubard 542:1bf9c597f44f 134 return BLE_ERROR_NONE;
vcoubard 542:1bf9c597f44f 135 }
vcoubard 542:1bf9c597f44f 136 switch (rc) {
vcoubard 542:1bf9c597f44f 137 case NRF_ERROR_BUSY:
vcoubard 542:1bf9c597f44f 138 return BLE_STACK_BUSY;
vcoubard 542:1bf9c597f44f 139 case BLE_ERROR_INVALID_CONN_HANDLE:
vcoubard 542:1bf9c597f44f 140 case NRF_ERROR_INVALID_STATE:
vcoubard 542:1bf9c597f44f 141 case NRF_ERROR_INVALID_ADDR:
vcoubard 542:1bf9c597f44f 142 default:
vcoubard 542:1bf9c597f44f 143 return BLE_ERROR_INVALID_STATE;
vcoubard 542:1bf9c597f44f 144 }
vcoubard 542:1bf9c597f44f 145 }
vcoubard 542:1bf9c597f44f 146
vcoubard 542:1bf9c597f44f 147 virtual ble_error_t write(GattClient::WriteOp_t cmd, Gap::Handle_t connHandle, GattAttribute::Handle_t attributeHandle, size_t length, const uint8_t *value) const {
vcoubard 542:1bf9c597f44f 148 ble_gattc_write_params_t writeParams;
vcoubard 542:1bf9c597f44f 149 writeParams.write_op = cmd;
vcoubard 542:1bf9c597f44f 150 writeParams.flags = 0; /* this is inconsequential */
vcoubard 542:1bf9c597f44f 151 writeParams.handle = attributeHandle;
vcoubard 542:1bf9c597f44f 152 writeParams.offset = 0;
vcoubard 542:1bf9c597f44f 153 writeParams.len = length;
vcoubard 542:1bf9c597f44f 154 writeParams.p_value = const_cast<uint8_t *>(value);
vcoubard 542:1bf9c597f44f 155
vcoubard 542:1bf9c597f44f 156 uint32_t rc = sd_ble_gattc_write(connHandle, &writeParams);
vcoubard 542:1bf9c597f44f 157 if (rc == NRF_SUCCESS) {
vcoubard 542:1bf9c597f44f 158 return BLE_ERROR_NONE;
vcoubard 542:1bf9c597f44f 159 }
vcoubard 542:1bf9c597f44f 160 switch (rc) {
vcoubard 542:1bf9c597f44f 161 case NRF_ERROR_BUSY:
vcoubard 542:1bf9c597f44f 162 return BLE_STACK_BUSY;
vcoubard 542:1bf9c597f44f 163 case BLE_ERROR_NO_TX_BUFFERS:
vcoubard 542:1bf9c597f44f 164 return BLE_ERROR_NO_MEM;
vcoubard 542:1bf9c597f44f 165 case BLE_ERROR_INVALID_CONN_HANDLE:
vcoubard 542:1bf9c597f44f 166 case NRF_ERROR_INVALID_STATE:
vcoubard 542:1bf9c597f44f 167 case NRF_ERROR_INVALID_ADDR:
vcoubard 542:1bf9c597f44f 168 default:
vcoubard 542:1bf9c597f44f 169 return BLE_ERROR_INVALID_STATE;
vcoubard 542:1bf9c597f44f 170 }
vcoubard 542:1bf9c597f44f 171 }
vcoubard 542:1bf9c597f44f 172
vcoubard 542:1bf9c597f44f 173 public:
vcoubard 567:e1800bd55a9e 174 nRF5xGattClient() : _discovery(this) {
vcoubard 542:1bf9c597f44f 175 /* empty */
vcoubard 542:1bf9c597f44f 176 }
vcoubard 542:1bf9c597f44f 177
vcoubard 567:e1800bd55a9e 178 nRF5xServiceDiscovery& discovery() {
vcoubard 567:e1800bd55a9e 179 return _discovery;
vcoubard 567:e1800bd55a9e 180 }
vcoubard 567:e1800bd55a9e 181
vcoubard 567:e1800bd55a9e 182 nRF5xCharacteristicDescriptorDiscoverer& characteristicDescriptorDiscoverer() {
vcoubard 567:e1800bd55a9e 183 return _characteristicDescriptorDiscoverer;
vcoubard 567:e1800bd55a9e 184 }
vcoubard 542:1bf9c597f44f 185
vcoubard 542:1bf9c597f44f 186 private:
vcoubard 542:1bf9c597f44f 187 nRF5xGattClient(const nRF5xGattClient &);
vcoubard 542:1bf9c597f44f 188 const nRF5xGattClient& operator=(const nRF5xGattClient &);
vcoubard 542:1bf9c597f44f 189
vcoubard 542:1bf9c597f44f 190 private:
vcoubard 567:e1800bd55a9e 191 nRF5xServiceDiscovery _discovery;
vcoubard 567:e1800bd55a9e 192 nRF5xCharacteristicDescriptorDiscoverer _characteristicDescriptorDiscoverer;
vcoubard 542:1bf9c597f44f 193
vcoubard 542:1bf9c597f44f 194 #endif // if !S110
vcoubard 542:1bf9c597f44f 195 };
vcoubard 542:1bf9c597f44f 196
rgrover1 388:db85a09c27ef 197 #endif // ifndef __NRF51822_GATT_CLIENT_H__