Maxim nexpaq / nexpaq_dev

Preliminary main mbed library for nexpaq development

features/FEATURE_BLE/ble/BLEInstanceBase.h@1:d96dbedaebdb, 2016-11-04 (annotated)

Committer:
nexpaq
Date:
Fri Nov 04 20:54:50 2016 +0000
Revision:
1:d96dbedaebdb
Parent:
0:6c56fb4bc5f0 
Removed extra directories for other platforms

Who changed what in which revision?

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