Oscar Ariza / nRF51822

nordic

Fork of nRF51822 by Nordic Semiconductor

source/nRF5xGattClient.h@562:613dbbdeed27, 2016-01-11 (annotated)

Committer:
vcoubard
Date:
Mon Jan 11 10:19:15 2016 +0000
Revision:
562:613dbbdeed27
Parent:
550:3f782c64d014
Child:
564:9c4b96f7be8d
Synchronized with git rev 7bf81e7e

Author: Andres Amaya Garcia

Improve shutdown to clear BLE API and not just SD



Improve the shutdown functionality, such that a call to ble.shutdown() from

the user application clears the API and nRF5x state and NOT only the

SoftDevice. To achieve this the following changes are introduced:



* Add a protected member cleanup() to nRF5xGap, nRF5xGattClient,

nRF5xGattServer, nRF5xSecurityManager and nRF5xServiceDiscovery.

* Modify the shutdown() implementation in nRF5xn such that it also calls the

static member shutdown() exposed by the BLE API in Gap.h, SecurityManager.h,

GattClient.h and GattServer.h.

* Modify nRF5xGattClient, nRF5xGattServer and nRF5xSecurityManager

classes so that they dynamically create their respective objects only if

needed. Previously the GattClient, GattServer and SecurityManager objects were

declared as static, which means that they were always present even though they

were not always needed. This increases memory consumption unnecessarily.

Furthermore, pointers to the object instances are stored in static members of

the classes as specified by the BLE API base classes. This ensures that

calls to shutdown do not require calls to getInstance() functions that would

otherwise result in undesired memory allocations.

* nRF5xGap object is always needed, so this remains allocated statically. But

the reference in Gap is pointed to this object.



The shutdown procedure is as follows:



1. The user calls ble.shutdown() which executes the code in nRF5xn::shutdown()

1. The SoftDevice is shutdown

1. The static members of Gap.h, SecurityManager.h, GattClient.h and

GattServer.h are called to clean up their own state.



If at any point an error occur during the last step, BLE_ERROR_INVALID_STATE is

returned.

Who changed what in which revision?

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