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@1183:1589830dbdb7, 2016-04-06 (annotated)

Committer:
vcoubard
Date:
Wed Apr 06 19:15:36 2016 +0100
Revision:
1183:1589830dbdb7
Parent:
1179:4ab722f8dca0
Child:
1201:9b71aac42d14
Synchronized with git rev 44cc6871

Author: Andres Amaya Garcia

Merge branch 'develop' into fix-doxy-warnings

Who changed what in which revision?

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