YUFEI JIANG / BLE_API_Tiny_BLE

BLE_API_Tiny_BLE

Dependents:   CSSE4011_BLE_IMU

Fork of BLE_API by Bluetooth Low Energy

public/Gap.h@325:501ad8b8bbe5, 2015-03-23 (annotated)

Committer:
rgrover1
Date:
Mon Mar 23 16:28:09 2015 +0000
Revision:
325:501ad8b8bbe5
Parent:
267:ad6f6f40eb24
Child:
337:e7c2eb38f5cc
Synchronized with git rev c7a2b9bb

Author: Rohit Grover

Release 0.3.0

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



Enhancements

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



* BLEDevice::setAdvertisingInterval() uses milliseconds as the unit for its

  argument. If advertising interval is set to 0, advertising is stopped. If

  advertising interval is smaller than the minimum value supported, then the

  minimum value is used instead.



* Add an enumeration called GattCharacteristicAuthCBReply_t to capture a

  status code from read/write authorization callback. Previously it used to

  return only a bool.



* Add APIs for getMinAdvertisingInterval() and variants.



Bugfixes

~~~~~~~~



* URIBeaconConfigService uses better write-authorization filters. It now

  passes tests defined in Google's validator app.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
rgrover1 260:ea7f9f14cc15 1 /* mbed Microcontroller Library
rgrover1 260:ea7f9f14cc15 2 * Copyright (c) 2006-2013 ARM Limited
rgrover1 260:ea7f9f14cc15 3 *
rgrover1 260:ea7f9f14cc15 4 * Licensed under the Apache License, Version 2.0 (the "License");
rgrover1 260:ea7f9f14cc15 5 * you may not use this file except in compliance with the License.
rgrover1 260:ea7f9f14cc15 6 * You may obtain a copy of the License at
rgrover1 260:ea7f9f14cc15 7 *
rgrover1 260:ea7f9f14cc15 8 * http://www.apache.org/licenses/LICENSE-2.0
rgrover1 260:ea7f9f14cc15 9 *
rgrover1 260:ea7f9f14cc15 10 * Unless required by applicable law or agreed to in writing, software
rgrover1 260:ea7f9f14cc15 11 * distributed under the License is distributed on an "AS IS" BASIS,
rgrover1 260:ea7f9f14cc15 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
rgrover1 260:ea7f9f14cc15 13 * See the License for the specific language governing permissions and
rgrover1 260:ea7f9f14cc15 14 * limitations under the License.
rgrover1 260:ea7f9f14cc15 15 */
rgrover1 260:ea7f9f14cc15 16
rgrover1 260:ea7f9f14cc15 17 #ifndef __GAP_H__
rgrover1 260:ea7f9f14cc15 18 #define __GAP_H__
rgrover1 260:ea7f9f14cc15 19
rgrover1 260:ea7f9f14cc15 20 #include "GapAdvertisingData.h"
rgrover1 260:ea7f9f14cc15 21 #include "GapAdvertisingParams.h"
rgrover1 260:ea7f9f14cc15 22 #include "GapEvents.h"
rgrover1 260:ea7f9f14cc15 23 #include "CallChain.h"
rgrover1 260:ea7f9f14cc15 24
rgrover1 260:ea7f9f14cc15 25 using namespace mbed;
rgrover1 260:ea7f9f14cc15 26
rgrover1 260:ea7f9f14cc15 27 class Gap {
rgrover1 260:ea7f9f14cc15 28 public:
rgrover1 260:ea7f9f14cc15 29 typedef enum addr_type_e {
rgrover1 260:ea7f9f14cc15 30 ADDR_TYPE_PUBLIC = 0,
rgrover1 260:ea7f9f14cc15 31 ADDR_TYPE_RANDOM_STATIC,
rgrover1 260:ea7f9f14cc15 32 ADDR_TYPE_RANDOM_PRIVATE_RESOLVABLE,
rgrover1 260:ea7f9f14cc15 33 ADDR_TYPE_RANDOM_PRIVATE_NON_RESOLVABLE
rgrover1 260:ea7f9f14cc15 34 } addr_type_t;
rgrover1 260:ea7f9f14cc15 35
rgrover1 260:ea7f9f14cc15 36 static const unsigned ADDR_LEN = 6;
rgrover1 260:ea7f9f14cc15 37 typedef uint8_t address_t[ADDR_LEN];
rgrover1 260:ea7f9f14cc15 38
rgrover1 260:ea7f9f14cc15 39 /**
rgrover1 260:ea7f9f14cc15 40 * Enumeration for disconnection reasons. The values for these reasons are
rgrover1 260:ea7f9f14cc15 41 * derived from Nordic's implementation; but the reasons are meant to be
rgrover1 260:ea7f9f14cc15 42 * independent of the transport. If you are returned a reason which is not
rgrover1 260:ea7f9f14cc15 43 * covered by this enumeration, then please refer to the underlying
rgrover1 260:ea7f9f14cc15 44 * transport library.
rgrover1 260:ea7f9f14cc15 45 */
rgrover1 260:ea7f9f14cc15 46 enum DisconnectionReason_t {
rgrover1 260:ea7f9f14cc15 47 REMOTE_USER_TERMINATED_CONNECTION = 0x13,
rgrover1 260:ea7f9f14cc15 48 LOCAL_HOST_TERMINATED_CONNECTION = 0x16,
rgrover1 260:ea7f9f14cc15 49 CONN_INTERVAL_UNACCEPTABLE = 0x3B,
rgrover1 260:ea7f9f14cc15 50 };
rgrover1 260:ea7f9f14cc15 51
rgrover1 260:ea7f9f14cc15 52 /* Describes the current state of the device (more than one bit can be set) */
rgrover1 260:ea7f9f14cc15 53 typedef struct GapState_s {
rgrover1 260:ea7f9f14cc15 54 unsigned advertising : 1; /**< peripheral is currently advertising */
rgrover1 260:ea7f9f14cc15 55 unsigned connected : 1; /**< peripheral is connected to a central */
rgrover1 260:ea7f9f14cc15 56 } GapState_t;
rgrover1 260:ea7f9f14cc15 57
rgrover1 260:ea7f9f14cc15 58 typedef uint16_t Handle_t;
rgrover1 260:ea7f9f14cc15 59
rgrover1 260:ea7f9f14cc15 60 typedef struct {
rgrover1 260:ea7f9f14cc15 61 uint16_t minConnectionInterval; /**< Minimum Connection Interval in 1.25 ms units, see @ref BLE_GAP_CP_LIMITS.*/
rgrover1 260:ea7f9f14cc15 62 uint16_t maxConnectionInterval; /**< Maximum Connection Interval in 1.25 ms units, see @ref BLE_GAP_CP_LIMITS.*/
rgrover1 260:ea7f9f14cc15 63 uint16_t slaveLatency; /**< Slave Latency in number of connection events, see @ref BLE_GAP_CP_LIMITS.*/
rgrover1 260:ea7f9f14cc15 64 uint16_t connectionSupervisionTimeout; /**< Connection Supervision Timeout in 10 ms units, see @ref BLE_GAP_CP_LIMITS.*/
rgrover1 260:ea7f9f14cc15 65 } ConnectionParams_t;
rgrover1 260:ea7f9f14cc15 66
rgrover1 260:ea7f9f14cc15 67 static const uint16_t UNIT_1_25_MS = 1250; /**< Number of microseconds in 1.25 milliseconds. */
rgrover1 260:ea7f9f14cc15 68 static const uint16_t UNIT_0_625_MS = 650; /**< Number of microseconds in 0.625 milliseconds. */
rgrover1 260:ea7f9f14cc15 69 static uint16_t MSEC_TO_GAP_DURATION_UNITS(uint32_t durationInMillis) {
rgrover1 260:ea7f9f14cc15 70 return (durationInMillis * 1000) / UNIT_1_25_MS;
rgrover1 260:ea7f9f14cc15 71 }
rgrover1 260:ea7f9f14cc15 72 static uint16_t MSEC_TO_ADVERTISEMENT_DURATION_UNITS(uint32_t durationInMillis) {
rgrover1 260:ea7f9f14cc15 73 return (durationInMillis * 1000) / UNIT_0_625_MS;
rgrover1 260:ea7f9f14cc15 74 }
rgrover1 325:501ad8b8bbe5 75 static uint16_t GAP_DURATION_UNITS_TO_MS(uint16_t gapUnits) {
rgrover1 325:501ad8b8bbe5 76 return (gapUnits * UNIT_0_625_MS) / 1000;
rgrover1 325:501ad8b8bbe5 77 }
rgrover1 260:ea7f9f14cc15 78
rgrover1 260:ea7f9f14cc15 79 typedef void (*EventCallback_t)(void);
rgrover1 260:ea7f9f14cc15 80 typedef void (*ConnectionEventCallback_t)(Handle_t, addr_type_t peerAddrType, const address_t peerAddr, const ConnectionParams_t *);
rgrover1 260:ea7f9f14cc15 81 typedef void (*DisconnectionEventCallback_t)(Handle_t, DisconnectionReason_t);
rgrover1 260:ea7f9f14cc15 82
rgrover1 260:ea7f9f14cc15 83 friend class BLEDevice;
rgrover1 260:ea7f9f14cc15 84 private:
rgrover1 260:ea7f9f14cc15 85 /* These functions must be defined in the sub-class */
rgrover1 260:ea7f9f14cc15 86 virtual ble_error_t setAddress(addr_type_t type, const address_t address) = 0;
rgrover1 260:ea7f9f14cc15 87 virtual ble_error_t getAddress(addr_type_t *typeP, address_t address) = 0;
rgrover1 260:ea7f9f14cc15 88 virtual ble_error_t setAdvertisingData(const GapAdvertisingData &, const GapAdvertisingData &) = 0;
rgrover1 260:ea7f9f14cc15 89 virtual ble_error_t startAdvertising(const GapAdvertisingParams &) = 0;
rgrover1 260:ea7f9f14cc15 90 virtual ble_error_t stopAdvertising(void) = 0;
rgrover1 325:501ad8b8bbe5 91 virtual uint16_t getMinAdvertisingInterval(void) const = 0;
rgrover1 325:501ad8b8bbe5 92 virtual uint16_t getMinNonConnectableAdvertisingInterval(void) const = 0;
rgrover1 325:501ad8b8bbe5 93 virtual uint16_t getMaxAdvertisingInterval(void) const = 0;
rgrover1 260:ea7f9f14cc15 94 virtual ble_error_t disconnect(DisconnectionReason_t reason) = 0;
rgrover1 260:ea7f9f14cc15 95 virtual ble_error_t getPreferredConnectionParams(ConnectionParams_t *params) = 0;
rgrover1 260:ea7f9f14cc15 96 virtual ble_error_t setPreferredConnectionParams(const ConnectionParams_t *params) = 0;
rgrover1 260:ea7f9f14cc15 97 virtual ble_error_t updateConnectionParams(Handle_t handle, const ConnectionParams_t *params) = 0;
rgrover1 260:ea7f9f14cc15 98
rgrover1 260:ea7f9f14cc15 99 virtual ble_error_t setDeviceName(const uint8_t *deviceName) = 0;
rgrover1 260:ea7f9f14cc15 100 virtual ble_error_t getDeviceName(uint8_t *deviceName, unsigned *lengthP) = 0;
rgrover1 260:ea7f9f14cc15 101 virtual ble_error_t setAppearance(uint16_t appearance) = 0;
rgrover1 260:ea7f9f14cc15 102 virtual ble_error_t getAppearance(uint16_t *appearanceP) = 0;
rgrover1 260:ea7f9f14cc15 103
rgrover1 260:ea7f9f14cc15 104 private:
rgrover1 260:ea7f9f14cc15 105 /* Event callback handlers */
rgrover1 260:ea7f9f14cc15 106 void setOnTimeout(EventCallback_t callback) {onTimeout = callback;}
rgrover1 260:ea7f9f14cc15 107 void setOnConnection(ConnectionEventCallback_t callback) {onConnection = callback;}
rgrover1 260:ea7f9f14cc15 108
rgrover1 260:ea7f9f14cc15 109 /**
rgrover1 260:ea7f9f14cc15 110 * Set the application callback for disconnection events.
rgrover1 260:ea7f9f14cc15 111 * @param callback
rgrover1 260:ea7f9f14cc15 112 * Pointer to the unique callback.
rgrover1 260:ea7f9f14cc15 113 */
rgrover1 260:ea7f9f14cc15 114 void setOnDisconnection(DisconnectionEventCallback_t callback) {onDisconnection = callback;}
rgrover1 260:ea7f9f14cc15 115
rgrover1 260:ea7f9f14cc15 116 /**
rgrover1 260:ea7f9f14cc15 117 * Append to a chain of callbacks to be invoked upon disconnection; these
rgrover1 260:ea7f9f14cc15 118 * callbacks receive no context and are therefore different from the
rgrover1 260:ea7f9f14cc15 119 * onDisconnection callback.
rgrover1 260:ea7f9f14cc15 120 * @param callback
rgrover1 260:ea7f9f14cc15 121 * function pointer to be invoked upon disconnection; receives no context.
rgrover1 260:ea7f9f14cc15 122 *
rgrover1 260:ea7f9f14cc15 123 * @note the disconnection CallChain should have been merged with
rgrover1 260:ea7f9f14cc15 124 * onDisconnctionCallback; but this was not possible because
rgrover1 260:ea7f9f14cc15 125 * FunctionPointer (which is a building block for CallChain) doesn't
rgrover1 260:ea7f9f14cc15 126 * accept variadic templates.
rgrover1 260:ea7f9f14cc15 127 */
rgrover1 260:ea7f9f14cc15 128 template<typename T>
rgrover1 260:ea7f9f14cc15 129 void addToDisconnectionCallChain(T *tptr, void (T::*mptr)(void)) {disconnectionCallChain.add(tptr, mptr);}
rgrover1 260:ea7f9f14cc15 130
rgrover1 260:ea7f9f14cc15 131 GapState_t getState(void) const {
rgrover1 260:ea7f9f14cc15 132 return state;
rgrover1 260:ea7f9f14cc15 133 }
rgrover1 260:ea7f9f14cc15 134
rgrover1 260:ea7f9f14cc15 135 protected:
rgrover1 260:ea7f9f14cc15 136 /* Default constructor. */
rgrover1 260:ea7f9f14cc15 137 Gap() : state(), onTimeout(NULL), onConnection(NULL), onDisconnection(NULL), disconnectionCallChain() {
rgrover1 260:ea7f9f14cc15 138 /* empty */
rgrover1 260:ea7f9f14cc15 139 }
rgrover1 260:ea7f9f14cc15 140
rgrover1 260:ea7f9f14cc15 141 public:
rgrover1 260:ea7f9f14cc15 142 void processConnectionEvent(Handle_t handle, addr_type_t type, const address_t addr, const ConnectionParams_t *params) {
rgrover1 260:ea7f9f14cc15 143 state.connected = 1;
rgrover1 260:ea7f9f14cc15 144 if (onConnection) {
rgrover1 260:ea7f9f14cc15 145 onConnection(handle, type, addr, params);
rgrover1 260:ea7f9f14cc15 146 }
rgrover1 260:ea7f9f14cc15 147 }
rgrover1 260:ea7f9f14cc15 148
rgrover1 260:ea7f9f14cc15 149 void processDisconnectionEvent(Handle_t handle, DisconnectionReason_t reason) {
rgrover1 260:ea7f9f14cc15 150 state.connected = 0;
rgrover1 260:ea7f9f14cc15 151 if (onDisconnection) {
rgrover1 260:ea7f9f14cc15 152 onDisconnection(handle, reason);
rgrover1 260:ea7f9f14cc15 153 }
rgrover1 260:ea7f9f14cc15 154 disconnectionCallChain.call();
rgrover1 260:ea7f9f14cc15 155 }
rgrover1 260:ea7f9f14cc15 156
rgrover1 260:ea7f9f14cc15 157 void processEvent(GapEvents::gapEvent_e type) {
rgrover1 260:ea7f9f14cc15 158 switch (type) {
rgrover1 260:ea7f9f14cc15 159 case GapEvents::GAP_EVENT_TIMEOUT:
rgrover1 260:ea7f9f14cc15 160 state.advertising = 0;
rgrover1 260:ea7f9f14cc15 161 if (onTimeout) {
rgrover1 260:ea7f9f14cc15 162 onTimeout();
rgrover1 260:ea7f9f14cc15 163 }
rgrover1 260:ea7f9f14cc15 164 break;
rgrover1 267:ad6f6f40eb24 165 default:
rgrover1 267:ad6f6f40eb24 166 break;
rgrover1 260:ea7f9f14cc15 167 }
rgrover1 260:ea7f9f14cc15 168 }
rgrover1 260:ea7f9f14cc15 169
rgrover1 260:ea7f9f14cc15 170 protected:
rgrover1 260:ea7f9f14cc15 171 GapState_t state;
rgrover1 260:ea7f9f14cc15 172
rgrover1 260:ea7f9f14cc15 173 private:
rgrover1 260:ea7f9f14cc15 174 EventCallback_t onTimeout;
rgrover1 260:ea7f9f14cc15 175 ConnectionEventCallback_t onConnection;
rgrover1 260:ea7f9f14cc15 176 DisconnectionEventCallback_t onDisconnection;
rgrover1 260:ea7f9f14cc15 177 CallChain disconnectionCallChain;
rgrover1 260:ea7f9f14cc15 178
rgrover1 260:ea7f9f14cc15 179 private:
rgrover1 260:ea7f9f14cc15 180 /* disallow copy and assignment */
rgrover1 260:ea7f9f14cc15 181 Gap(const Gap &);
rgrover1 260:ea7f9f14cc15 182 Gap& operator=(const Gap &);
rgrover1 260:ea7f9f14cc15 183 };
rgrover1 260:ea7f9f14cc15 184
rgrover1 260:ea7f9f14cc15 185 #endif // ifndef __GAP_H__