Gap.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2006-2013 ARM Limited
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 #ifndef __GAP_H__
00018 #define __GAP_H__
00019 
00020 #include "GapAdvertisingData.h"
00021 #include "GapAdvertisingParams.h"
00022 #include "GapEvents.h"
00023 #include "CallChain.h"
00024 
00025 using namespace mbed;
00026 
00027 class Gap {
00028 public:
00029     typedef enum addr_type_e {
00030         ADDR_TYPE_PUBLIC = 0,
00031         ADDR_TYPE_RANDOM_STATIC,
00032         ADDR_TYPE_RANDOM_PRIVATE_RESOLVABLE,
00033         ADDR_TYPE_RANDOM_PRIVATE_NON_RESOLVABLE
00034     } addr_type_t;
00035 
00036     static const unsigned ADDR_LEN = 6;
00037     typedef uint8_t address_t[ADDR_LEN];
00038 
00039     /**
00040      * Enumeration for disconnection reasons. The values for these reasons are
00041      * derived from Nordic's implementation; but the reasons are meant to be
00042      * independent of the transport. If you are returned a reason which is not
00043      * covered by this enumeration, then please refer to the underlying
00044      * transport library.
00045      */
00046     enum DisconnectionReason_t {
00047         REMOTE_USER_TERMINATED_CONNECTION = 0x13,
00048         LOCAL_HOST_TERMINATED_CONNECTION  = 0x16,
00049         CONN_INTERVAL_UNACCEPTABLE        = 0x3B,
00050     };
00051 
00052     /* Describes the current state of the device (more than one bit can be set) */
00053     typedef struct GapState_s {
00054         unsigned advertising : 1; /**< peripheral is currently advertising */
00055         unsigned connected   : 1; /**< peripheral is connected to a central */
00056     } GapState_t;
00057 
00058     typedef uint16_t Handle_t;
00059 
00060     typedef struct {
00061         uint16_t minConnectionInterval;      /**< Minimum Connection Interval in 1.25 ms units, see @ref BLE_GAP_CP_LIMITS.*/
00062         uint16_t maxConnectionInterval;      /**< Maximum Connection Interval in 1.25 ms units, see @ref BLE_GAP_CP_LIMITS.*/
00063         uint16_t slaveLatency;               /**< Slave Latency in number of connection events, see @ref BLE_GAP_CP_LIMITS.*/
00064         uint16_t connectionSupervisionTimeout; /**< Connection Supervision Timeout in 10 ms units, see @ref BLE_GAP_CP_LIMITS.*/
00065     } ConnectionParams_t;
00066 
00067     static const uint16_t UNIT_1_25_MS  = 1250; /**< Number of microseconds in 1.25 milliseconds. */
00068     static const uint16_t UNIT_0_625_MS = 650;  /**< Number of microseconds in 0.625 milliseconds. */
00069     static uint16_t MSEC_TO_GAP_DURATION_UNITS(uint32_t durationInMillis) {
00070         return (durationInMillis * 1000) / UNIT_1_25_MS;
00071     }
00072     static uint16_t MSEC_TO_ADVERTISEMENT_DURATION_UNITS(uint32_t durationInMillis) {
00073         return (durationInMillis * 1000) / UNIT_0_625_MS;
00074     }
00075     static uint16_t GAP_DURATION_UNITS_TO_MS(uint16_t gapUnits) {
00076         return (gapUnits * UNIT_0_625_MS) / 1000;
00077     }
00078 
00079     typedef void (*EventCallback_t)(void);
00080     typedef void (*ConnectionEventCallback_t)(Handle_t, addr_type_t peerAddrType, const address_t peerAddr, const ConnectionParams_t *);
00081     typedef void (*DisconnectionEventCallback_t)(Handle_t, DisconnectionReason_t);
00082     typedef void (*RadioNotificationEventCallback_t) (bool radio_active); /* gets passed true for ACTIVE; false for INACTIVE. */
00083 
00084     friend class BLEDevice;
00085 private:
00086     /* These functions must be defined in the sub-class */
00087     virtual ble_error_t setAddress(addr_type_t type,   const address_t address)                    = 0;
00088     virtual ble_error_t getAddress(addr_type_t *typeP, address_t address)                          = 0;
00089     virtual ble_error_t setAdvertisingData(const GapAdvertisingData &, const GapAdvertisingData &) = 0;
00090     virtual ble_error_t startAdvertising(const GapAdvertisingParams &)                             = 0;
00091     virtual ble_error_t stopAdvertising(void)                                                      = 0;
00092     virtual uint16_t    getMinAdvertisingInterval (void) const                                      = 0;
00093     virtual uint16_t    getMinNonConnectableAdvertisingInterval (void) const                        = 0;
00094     virtual uint16_t    getMaxAdvertisingInterval (void) const                                      = 0;
00095     virtual ble_error_t disconnect(DisconnectionReason_t reason)                                   = 0;
00096     virtual ble_error_t getPreferredConnectionParams(ConnectionParams_t *params)                   = 0;
00097     virtual ble_error_t setPreferredConnectionParams(const ConnectionParams_t *params)             = 0;
00098     virtual ble_error_t updateConnectionParams(Handle_t handle, const ConnectionParams_t *params)  = 0;
00099 
00100     virtual ble_error_t setDeviceName(const uint8_t *deviceName)              = 0;
00101     virtual ble_error_t getDeviceName(uint8_t *deviceName, unsigned *lengthP) = 0;
00102     virtual ble_error_t setAppearance(uint16_t appearance)                    = 0;
00103     virtual ble_error_t getAppearance(uint16_t *appearanceP)                  = 0;
00104 
00105 protected:
00106     /* Event callback handlers */
00107     void setOnTimeout(EventCallback_t callback) {onTimeout = callback;}
00108     void setOnConnection(ConnectionEventCallback_t callback) {onConnection = callback;}
00109 
00110     /**
00111      * Set the application callback for disconnection events.
00112      * @param callback
00113      *        Pointer to the unique callback.
00114      */
00115     void setOnDisconnection(DisconnectionEventCallback_t callback) {onDisconnection = callback;}
00116 
00117     /**
00118      * Set the application callback for radio-notification events.
00119      * @param callback
00120      *          Handler to be executed in resonse to a radio notification event.
00121      */
00122     virtual void setOnRadioNotification(RadioNotificationEventCallback_t callback) {onRadioNotification = callback;}
00123 
00124     /**
00125      * Append to a chain of callbacks to be invoked upon disconnection; these
00126      * callbacks receive no context and are therefore different from the
00127      * onDisconnection callback.
00128      * @param callback
00129      *        function pointer to be invoked upon disconnection; receives no context.
00130      *
00131      * @note the disconnection CallChain should have been merged with
00132      *     onDisconnctionCallback; but this was not possible because
00133      *     FunctionPointer (which is a building block for CallChain) doesn't
00134      *     accept variadic templates.
00135      */
00136     template<typename T>
00137     void addToDisconnectionCallChain(T *tptr, void (T::*mptr)(void)) {disconnectionCallChain.add(tptr, mptr);}
00138 
00139 private:
00140     GapState_t getState(void) const {
00141         return state;
00142     }
00143 
00144 protected:
00145     /* Default constructor. */
00146     Gap() : state(), onTimeout(NULL), onConnection(NULL), onDisconnection(NULL), onRadioNotification(), disconnectionCallChain() {
00147         /* empty */
00148     }
00149 
00150 public:
00151     void processConnectionEvent(Handle_t handle, addr_type_t type, const address_t addr, const ConnectionParams_t *params) {
00152         state.connected = 1;
00153         if (onConnection) {
00154             onConnection(handle, type, addr, params);
00155         }
00156     }
00157 
00158     void processDisconnectionEvent(Handle_t handle, DisconnectionReason_t reason) {
00159         state.connected = 0;
00160         if (onDisconnection) {
00161             onDisconnection(handle, reason);
00162         }
00163         disconnectionCallChain.call();
00164     }
00165 
00166     void processEvent(GapEvents::gapEvent_e type) {
00167         switch (type) {
00168             case GapEvents::GAP_EVENT_TIMEOUT:
00169                 state.advertising = 0;
00170                 if (onTimeout) {
00171                     onTimeout();
00172                 }
00173                 break;
00174             default:
00175                 break;
00176         }
00177     }
00178 
00179 protected:
00180     GapState_t                   state;
00181 
00182 protected:
00183     EventCallback_t              onTimeout;
00184     ConnectionEventCallback_t    onConnection;
00185     DisconnectionEventCallback_t onDisconnection;
00186     RadioNotificationEventCallback_t onRadioNotification;
00187     CallChain                    disconnectionCallChain;
00188 
00189 private:
00190     /* disallow copy and assignment */
00191     Gap(const Gap &);
00192     Gap& operator=(const Gap &);
00193 };
00194 
00195 #endif // ifndef __GAP_H__