Alex Cordonnier / BLE_API

High level Bluetooth Low Energy API and radio abstraction layer

Fork of BLE_API by Bluetooth Low Energy

ble/BLEInstanceBase.h@1201:9b71aac42d14, 2016-09-14 (annotated)

Committer:
Vincent Coubard
Date:
Wed Sep 14 14:17:52 2016 +0100
Branch:
2f55eed1fdde06fdabfb66d41ce6cd14e280978f
Revision:
1201:9b71aac42d14
Parent:
1183:1589830dbdb7 
Sync with 2f55eed1fdde06fdabfb66d41ce6cd14e280978f



2016-06-06 09:36:57+01:00: Vincent Coubard

Add an interface which allows user code to customise the way BLE events

are processed.



The mechanism is quite simple:

  * user code can process all events pending in the internal BLE stack by

    calling the function BLE::processEvent.

  * user code can be notified when an event become available and the event

    stack has to be processed. The notification is issued by the port of

    mbed BLE.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Vincent Coubard 1201:9b71aac42d14 1 /* mbed Microcontroller Library
Vincent Coubard 1201:9b71aac42d14 2 * Copyright (c) 2006-2013 ARM Limited
Vincent Coubard 1201:9b71aac42d14 3 *
Vincent Coubard 1201:9b71aac42d14 4 * Licensed under the Apache License, Version 2.0 (the "License");
Vincent Coubard 1201:9b71aac42d14 5 * you may not use this file except in compliance with the License.
Vincent Coubard 1201:9b71aac42d14 6 * You may obtain a copy of the License at
Vincent Coubard 1201:9b71aac42d14 7 *
Vincent Coubard 1201:9b71aac42d14 8 * http://www.apache.org/licenses/LICENSE-2.0
Vincent Coubard 1201:9b71aac42d14 9 *
Vincent Coubard 1201:9b71aac42d14 10 * Unless required by applicable law or agreed to in writing, software
Vincent Coubard 1201:9b71aac42d14 11 * distributed under the License is distributed on an "AS IS" BASIS,
Vincent Coubard 1201:9b71aac42d14 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
Vincent Coubard 1201:9b71aac42d14 13 * See the License for the specific language governing permissions and
Vincent Coubard 1201:9b71aac42d14 14 * limitations under the License.
Vincent Coubard 1201:9b71aac42d14 15 */
Vincent Coubard 1201:9b71aac42d14 16
Vincent Coubard 1201:9b71aac42d14 17 #ifndef __BLE_DEVICE_INSTANCE_BASE__
Vincent Coubard 1201:9b71aac42d14 18 #define __BLE_DEVICE_INSTANCE_BASE__
Vincent Coubard 1201:9b71aac42d14 19
Vincent Coubard 1201:9b71aac42d14 20 #include "Gap.h"
Vincent Coubard 1201:9b71aac42d14 21 #include "ble/SecurityManager.h"
Vincent Coubard 1201:9b71aac42d14 22 #include "ble/BLE.h"
Vincent Coubard 1201:9b71aac42d14 23
Vincent Coubard 1201:9b71aac42d14 24 /* Forward declarations. */
Vincent Coubard 1201:9b71aac42d14 25 class GattServer;
Vincent Coubard 1201:9b71aac42d14 26 class GattClient;
Vincent Coubard 1201:9b71aac42d14 27
Vincent Coubard 1201:9b71aac42d14 28 /**
Vincent Coubard 1201:9b71aac42d14 29 * The interface for the transport object to be created by the target library's
Vincent Coubard 1201:9b71aac42d14 30 * createBLEInstance().
Vincent Coubard 1201:9b71aac42d14 31 *
Vincent Coubard 1201:9b71aac42d14 32 * @note This class is part of the interface of BLE API with the implementation;
Vincent Coubard 1201:9b71aac42d14 33 * therefore, it is meant to be used only by porters rather than normal
Vincent Coubard 1201:9b71aac42d14 34 * BLE API users.
Vincent Coubard 1201:9b71aac42d14 35 */
Vincent Coubard 1201:9b71aac42d14 36 class BLEInstanceBase
Vincent Coubard 1201:9b71aac42d14 37 {
Vincent Coubard 1201:9b71aac42d14 38 public:
Vincent Coubard 1201:9b71aac42d14 39 BLEInstanceBase() {}
Vincent Coubard 1201:9b71aac42d14 40
Vincent Coubard 1201:9b71aac42d14 41 /**
Vincent Coubard 1201:9b71aac42d14 42 * Virtual destructor of the interface.
Vincent Coubard 1201:9b71aac42d14 43 */
Vincent Coubard 1201:9b71aac42d14 44 virtual ~BLEInstanceBase();
Vincent Coubard 1201:9b71aac42d14 45
Vincent Coubard 1201:9b71aac42d14 46 /**
Vincent Coubard 1201:9b71aac42d14 47 * Initialize the underlying BLE stack. This should be called before
Vincent Coubard 1201:9b71aac42d14 48 * anything else in the BLE API.
Vincent Coubard 1201:9b71aac42d14 49 *
Vincent Coubard 1201:9b71aac42d14 50 * @param[in] instanceID
Vincent Coubard 1201:9b71aac42d14 51 * The ID of the instance to initialize.
Vincent Coubard 1201:9b71aac42d14 52 * @param[in] initCallback
Vincent Coubard 1201:9b71aac42d14 53 * A callback for when initialization completes for a BLE
Vincent Coubard 1201:9b71aac42d14 54 * instance. This is an optional parameter set to NULL when not
Vincent Coubard 1201:9b71aac42d14 55 * supplied.
Vincent Coubard 1201:9b71aac42d14 56 *
Vincent Coubard 1201:9b71aac42d14 57 * @return BLE_ERROR_NONE if the initialization procedure was started
Vincent Coubard 1201:9b71aac42d14 58 * successfully.
Vincent Coubard 1201:9b71aac42d14 59 */
Vincent Coubard 1201:9b71aac42d14 60 virtual ble_error_t init(BLE::InstanceID_t instanceID,
Vincent Coubard 1201:9b71aac42d14 61 FunctionPointerWithContext<BLE::InitializationCompleteCallbackContext *> initCallback) = 0;
Vincent Coubard 1201:9b71aac42d14 62
Vincent Coubard 1201:9b71aac42d14 63 /**
Vincent Coubard 1201:9b71aac42d14 64 * Check whether the underlying stack has already been initialized,
Vincent Coubard 1201:9b71aac42d14 65 * possible with a call to init().
Vincent Coubard 1201:9b71aac42d14 66 *
Vincent Coubard 1201:9b71aac42d14 67 * @return true if the initialization has completed for the underlying BLE
Vincent Coubard 1201:9b71aac42d14 68 * stack.
Vincent Coubard 1201:9b71aac42d14 69 */
Vincent Coubard 1201:9b71aac42d14 70 virtual bool hasInitialized(void) const = 0;
Vincent Coubard 1201:9b71aac42d14 71
Vincent Coubard 1201:9b71aac42d14 72 /**
Vincent Coubard 1201:9b71aac42d14 73 * Shutdown the underlying BLE stack. This includes purging the stack of
Vincent Coubard 1201:9b71aac42d14 74 * GATT and GAP state and clearing all state from other BLE components
Vincent Coubard 1201:9b71aac42d14 75 * such as the SecurityManager. init() must be called afterwards to
Vincent Coubard 1201:9b71aac42d14 76 * re-instantiate services and GAP state.
Vincent Coubard 1201:9b71aac42d14 77 *
Vincent Coubard 1201:9b71aac42d14 78 * @return BLE_ERROR_NONE if the underlying stack and all other services of
Vincent Coubard 1201:9b71aac42d14 79 * the BLE API were shutdown correctly.
Vincent Coubard 1201:9b71aac42d14 80 */
Vincent Coubard 1201:9b71aac42d14 81 virtual ble_error_t shutdown(void) = 0;
Vincent Coubard 1201:9b71aac42d14 82
Vincent Coubard 1201:9b71aac42d14 83 /**
Vincent Coubard 1201:9b71aac42d14 84 * Fetches a string representation of the underlying BLE stack's version.
Vincent Coubard 1201:9b71aac42d14 85 *
Vincent Coubard 1201:9b71aac42d14 86 * @return A pointer to the string representation of the underlying
Vincent Coubard 1201:9b71aac42d14 87 * BLE stack's version.
Vincent Coubard 1201:9b71aac42d14 88 */
Vincent Coubard 1201:9b71aac42d14 89 virtual const char * getVersion(void) = 0;
Vincent Coubard 1201:9b71aac42d14 90
Vincent Coubard 1201:9b71aac42d14 91 /**
Vincent Coubard 1201:9b71aac42d14 92 * Accessor to Gap. This function is used by BLE::gap().
Vincent Coubard 1201:9b71aac42d14 93 *
Vincent Coubard 1201:9b71aac42d14 94 * @return A reference to a Gap object associated to this BLE instance.
Vincent Coubard 1201:9b71aac42d14 95 */
Vincent Coubard 1201:9b71aac42d14 96 virtual Gap& getGap() = 0;
Vincent Coubard 1201:9b71aac42d14 97
Vincent Coubard 1201:9b71aac42d14 98 /**
Vincent Coubard 1201:9b71aac42d14 99 * A const alternative to getGap().
Vincent Coubard 1201:9b71aac42d14 100 *
Vincent Coubard 1201:9b71aac42d14 101 * @return A const reference to a Gap object associated to this BLE instance.
Vincent Coubard 1201:9b71aac42d14 102 */
Vincent Coubard 1201:9b71aac42d14 103 virtual const Gap& getGap() const = 0;
Vincent Coubard 1201:9b71aac42d14 104
Vincent Coubard 1201:9b71aac42d14 105 /**
Vincent Coubard 1201:9b71aac42d14 106 * Accessor to GattServer. This function is used by BLE::gattServer().
Vincent Coubard 1201:9b71aac42d14 107 *
Vincent Coubard 1201:9b71aac42d14 108 * @return A reference to a GattServer object associated to this BLE instance.
Vincent Coubard 1201:9b71aac42d14 109 */
Vincent Coubard 1201:9b71aac42d14 110 virtual GattServer& getGattServer() = 0;
Vincent Coubard 1201:9b71aac42d14 111
Vincent Coubard 1201:9b71aac42d14 112 /**
Vincent Coubard 1201:9b71aac42d14 113 * A const alternative to getGattServer().
Vincent Coubard 1201:9b71aac42d14 114 *
Vincent Coubard 1201:9b71aac42d14 115 * @return A const reference to a GattServer object associated to this BLE instance.
Vincent Coubard 1201:9b71aac42d14 116 */
Vincent Coubard 1201:9b71aac42d14 117 virtual const GattServer& getGattServer() const = 0;
Vincent Coubard 1201:9b71aac42d14 118
Vincent Coubard 1201:9b71aac42d14 119 /**
Vincent Coubard 1201:9b71aac42d14 120 * Accessors to GattClient. This function is used by BLE::gattClient().
Vincent Coubard 1201:9b71aac42d14 121 *
Vincent Coubard 1201:9b71aac42d14 122 * @return A reference to a GattClient object associated to this BLE instance.
Vincent Coubard 1201:9b71aac42d14 123 */
Vincent Coubard 1201:9b71aac42d14 124 virtual GattClient& getGattClient() = 0;
Vincent Coubard 1201:9b71aac42d14 125
Vincent Coubard 1201:9b71aac42d14 126 /**
Vincent Coubard 1201:9b71aac42d14 127 * Accessors to SecurityManager. This function is used by BLE::securityManager().
Vincent Coubard 1201:9b71aac42d14 128 *
Vincent Coubard 1201:9b71aac42d14 129 * @return A reference to a SecurityManager object associated to this BLE instance.
Vincent Coubard 1201:9b71aac42d14 130 */
Vincent Coubard 1201:9b71aac42d14 131 virtual SecurityManager& getSecurityManager() = 0;
Vincent Coubard 1201:9b71aac42d14 132
Vincent Coubard 1201:9b71aac42d14 133 /**
Vincent Coubard 1201:9b71aac42d14 134 * A const alternative to getSecurityManager().
Vincent Coubard 1201:9b71aac42d14 135 *
Vincent Coubard 1201:9b71aac42d14 136 * @return A const reference to a SecurityManager object associated to this BLE instance.
Vincent Coubard 1201:9b71aac42d14 137 */
Vincent Coubard 1201:9b71aac42d14 138 virtual const SecurityManager& getSecurityManager() const = 0;
Vincent Coubard 1201:9b71aac42d14 139
Vincent Coubard 1201:9b71aac42d14 140 /**
Vincent Coubard 1201:9b71aac42d14 141 * Yield control to the BLE stack or to other tasks waiting for events.
Vincent Coubard 1201:9b71aac42d14 142 * refer to BLE::waitForEvent().
Vincent Coubard 1201:9b71aac42d14 143 */
Vincent Coubard 1201:9b71aac42d14 144 virtual void waitForEvent(void) = 0;
Vincent Coubard 1201:9b71aac42d14 145
Vincent Coubard 1201:9b71aac42d14 146 /**
Vincent Coubard 1201:9b71aac42d14 147 * Process ALL pending events living in the BLE stack .
Vincent Coubard 1201:9b71aac42d14 148 * Return once all events have been consumed.
Vincent Coubard 1201:9b71aac42d14 149 */
Vincent Coubard 1201:9b71aac42d14 150 virtual void processEvents() = 0;
Vincent Coubard 1201:9b71aac42d14 151
Vincent Coubard 1201:9b71aac42d14 152 /**
Vincent Coubard 1201:9b71aac42d14 153 * This function allow the BLE stack to signal that their is work to do and
Vincent Coubard 1201:9b71aac42d14 154 * event processing should be done (BLE::processEvent()).
Vincent Coubard 1201:9b71aac42d14 155 * @param id: The ID of the BLE instance which does have events to process.
Vincent Coubard 1201:9b71aac42d14 156 */
Vincent Coubard 1201:9b71aac42d14 157 void signalEventsToProcess(BLE::InstanceID_t id);
Vincent Coubard 1201:9b71aac42d14 158
Vincent Coubard 1201:9b71aac42d14 159 private:
Vincent Coubard 1201:9b71aac42d14 160 // this class is not a value type.
Vincent Coubard 1201:9b71aac42d14 161 // prohibit copy construction and copy assignement
Vincent Coubard 1201:9b71aac42d14 162 BLEInstanceBase(const BLEInstanceBase&);
Vincent Coubard 1201:9b71aac42d14 163 BLEInstanceBase& operator=(const BLEInstanceBase&);
Vincent Coubard 1201:9b71aac42d14 164 };
Vincent Coubard 1201:9b71aac42d14 165
Vincent Coubard 1201:9b71aac42d14 166 /**
Vincent Coubard 1201:9b71aac42d14 167 * BLE uses composition to hide an interface object encapsulating the
Vincent Coubard 1201:9b71aac42d14 168 * backend transport.
Vincent Coubard 1201:9b71aac42d14 169 *
Vincent Coubard 1201:9b71aac42d14 170 * The following API is used to create the singleton interface object. An
Vincent Coubard 1201:9b71aac42d14 171 * implementation for this function must be provided by the device-specific
Vincent Coubard 1201:9b71aac42d14 172 * library, otherwise there will be a linker error.
Vincent Coubard 1201:9b71aac42d14 173 */
Vincent Coubard 1201:9b71aac42d14 174 extern BLEInstanceBase *createBLEInstance(void);
Vincent Coubard 1201:9b71aac42d14 175
rgrover1 716:11b41f651697 176 #endif // ifndef __BLE_DEVICE_INSTANCE_BASE__