Andrea Sortino / BLE_API

prova

Fork of BLE_API by Bluetooth Low Energy

ble/BLEInstanceBase.h@1178:a4418fcb462f, 2016-04-06 (annotated)

Committer:
vcoubard
Date:
Wed Apr 06 19:15:28 2016 +0100
Revision:
1178:a4418fcb462f
Parent:
1156:e1ea38b576c6
Child:
1179:4ab722f8dca0
Synchronized with git rev 9e491576

Author: Andres Amaya Garcia

Add doxygen note to BLEInstanceBase class

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 1178:a4418fcb462f 31 *
vcoubard 1178:a4418fcb462f 32 * @note This class is part of the interface of BLE API with the implementation;
vcoubard 1178:a4418fcb462f 33 * therefore, it is meant to be used only by porters rather than normal
vcoubard 1178:a4418fcb462f 34 * BLE API users.
vcoubard 1145:d21353309b6c 35 */
vcoubard 1145:d21353309b6c 36 class BLEInstanceBase
vcoubard 1145:d21353309b6c 37 {
vcoubard 1145:d21353309b6c 38 public:
vcoubard 1156:e1ea38b576c6 39 /**
vcoubard 1156:e1ea38b576c6 40 * Initialize the underlying BLE stack. This should be called before
vcoubard 1156:e1ea38b576c6 41 * anything else in the BLE API.
vcoubard 1156:e1ea38b576c6 42 *
vcoubard 1156:e1ea38b576c6 43 * @param[in] instanceID
vcoubard 1156:e1ea38b576c6 44 * The ID of the instance to initialize.
vcoubard 1156:e1ea38b576c6 45 * @param[in] initCallback
vcoubard 1156:e1ea38b576c6 46 * A callback for when initialization completes for a BLE
vcoubard 1156:e1ea38b576c6 47 * instance. This is an optional parameter set to NULL when not
vcoubard 1156:e1ea38b576c6 48 * supplied.
vcoubard 1156:e1ea38b576c6 49 *
vcoubard 1156:e1ea38b576c6 50 * @return BLE_ERROR_NONE if the initialization procedure was started
vcoubard 1156:e1ea38b576c6 51 * successfully.
vcoubard 1156:e1ea38b576c6 52 */
vcoubard 1145:d21353309b6c 53 virtual ble_error_t init(BLE::InstanceID_t instanceID,
vcoubard 1145:d21353309b6c 54 FunctionPointerWithContext<BLE::InitializationCompleteCallbackContext *> initCallback) = 0;
vcoubard 1156:e1ea38b576c6 55
vcoubard 1156:e1ea38b576c6 56 /**
vcoubard 1156:e1ea38b576c6 57 * Check whether the underlying stack has already been initialized,
vcoubard 1156:e1ea38b576c6 58 * possible with a call to init().
vcoubard 1156:e1ea38b576c6 59 *
vcoubard 1156:e1ea38b576c6 60 * @return true if the initialization has completed for the underlying BLE
vcoubard 1156:e1ea38b576c6 61 * stack.
vcoubard 1156:e1ea38b576c6 62 */
vcoubard 1145:d21353309b6c 63 virtual bool hasInitialized(void) const = 0;
vcoubard 1156:e1ea38b576c6 64
vcoubard 1156:e1ea38b576c6 65 /**
vcoubard 1156:e1ea38b576c6 66 * Shutdown the underlying BLE stack. This includes purging the stack of
vcoubard 1156:e1ea38b576c6 67 * GATT and GAP state and clearing all state from other BLE components
vcoubard 1156:e1ea38b576c6 68 * such as the SecurityManager. init() must be called afterwards to
vcoubard 1156:e1ea38b576c6 69 * re-instantiate services and GAP state.
vcoubard 1156:e1ea38b576c6 70 *
vcoubard 1156:e1ea38b576c6 71 * @return BLE_ERROR_NONE if the underlying stack and all other services of
vcoubard 1156:e1ea38b576c6 72 * the BLE API were shutdown correctly.
vcoubard 1156:e1ea38b576c6 73 */
vcoubard 1145:d21353309b6c 74 virtual ble_error_t shutdown(void) = 0;
vcoubard 1156:e1ea38b576c6 75
vcoubard 1156:e1ea38b576c6 76 /**
vcoubard 1156:e1ea38b576c6 77 * Fetches a string representation of the underlying BLE stack's version.
vcoubard 1156:e1ea38b576c6 78 *
vcoubard 1156:e1ea38b576c6 79 * @return A pointer to the string representation of the underlying
vcoubard 1156:e1ea38b576c6 80 * BLE stack's version.
vcoubard 1156:e1ea38b576c6 81 */
vcoubard 1145:d21353309b6c 82 virtual const char * getVersion(void) = 0;
vcoubard 1156:e1ea38b576c6 83
vcoubard 1156:e1ea38b576c6 84 /**
vcoubard 1156:e1ea38b576c6 85 * Accessor to Gap. This function is used by BLE::gap().
vcoubard 1156:e1ea38b576c6 86 *
vcoubard 1156:e1ea38b576c6 87 * @return A reference to a Gap object associated to this BLE instance.
vcoubard 1156:e1ea38b576c6 88 */
vcoubard 1145:d21353309b6c 89 virtual Gap& getGap() = 0;
vcoubard 1156:e1ea38b576c6 90
vcoubard 1156:e1ea38b576c6 91 /**
vcoubard 1156:e1ea38b576c6 92 * A const alternative to getGap().
vcoubard 1156:e1ea38b576c6 93 *
vcoubard 1156:e1ea38b576c6 94 * @return A const reference to a Gap object associated to this BLE instance.
vcoubard 1156:e1ea38b576c6 95 */
vcoubard 1145:d21353309b6c 96 virtual const Gap& getGap() const = 0;
vcoubard 1156:e1ea38b576c6 97
vcoubard 1156:e1ea38b576c6 98 /**
vcoubard 1156:e1ea38b576c6 99 * Accessor to GattServer. This function is used by BLE::gattServer().
vcoubard 1156:e1ea38b576c6 100 *
vcoubard 1156:e1ea38b576c6 101 * @return A reference to a GattServer object associated to this BLE instance.
vcoubard 1156:e1ea38b576c6 102 */
vcoubard 1145:d21353309b6c 103 virtual GattServer& getGattServer() = 0;
vcoubard 1156:e1ea38b576c6 104
vcoubard 1156:e1ea38b576c6 105 /**
vcoubard 1156:e1ea38b576c6 106 * A const alternative to getGattServer().
vcoubard 1156:e1ea38b576c6 107 *
vcoubard 1156:e1ea38b576c6 108 * @return A const reference to a GattServer object associated to this BLE instance.
vcoubard 1156:e1ea38b576c6 109 */
vcoubard 1145:d21353309b6c 110 virtual const GattServer& getGattServer() const = 0;
vcoubard 1156:e1ea38b576c6 111
vcoubard 1156:e1ea38b576c6 112 /**
vcoubard 1156:e1ea38b576c6 113 * Accessors to GattClient. This function is used by BLE::gattClient().
vcoubard 1156:e1ea38b576c6 114 *
vcoubard 1156:e1ea38b576c6 115 * @return A reference to a GattClient object associated to this BLE instance.
vcoubard 1156:e1ea38b576c6 116 */
vcoubard 1145:d21353309b6c 117 virtual GattClient& getGattClient() = 0;
vcoubard 1156:e1ea38b576c6 118
vcoubard 1156:e1ea38b576c6 119 /**
vcoubard 1156:e1ea38b576c6 120 * Accessors to SecurityManager. This function is used by BLE::securityManager().
vcoubard 1156:e1ea38b576c6 121 *
vcoubard 1156:e1ea38b576c6 122 * @return A reference to a SecurityManager object associated to this BLE instance.
vcoubard 1156:e1ea38b576c6 123 */
vcoubard 1145:d21353309b6c 124 virtual SecurityManager& getSecurityManager() = 0;
vcoubard 1156:e1ea38b576c6 125
vcoubard 1156:e1ea38b576c6 126 /**
vcoubard 1156:e1ea38b576c6 127 * A const alternative to getSecurityManager().
vcoubard 1156:e1ea38b576c6 128 *
vcoubard 1156:e1ea38b576c6 129 * @return A const reference to a SecurityManager object associated to this BLE instance.
vcoubard 1156:e1ea38b576c6 130 */
vcoubard 1145:d21353309b6c 131 virtual const SecurityManager& getSecurityManager() const = 0;
vcoubard 1156:e1ea38b576c6 132
vcoubard 1156:e1ea38b576c6 133 /**
vcoubard 1156:e1ea38b576c6 134 * Yield control to the BLE stack or to other tasks waiting for events.
vcoubard 1156:e1ea38b576c6 135 * refer to BLE::waitForEvent().
vcoubard 1156:e1ea38b576c6 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__