Jörg Küfen / BLE_API

fka mod

Fork of BLE_API by Bluetooth Low Energy

ble/BLEInstanceBase.h@1156:e1ea38b576c6, 2016-04-06 (annotated)

Committer:
vcoubard
Date:
Wed Apr 06 19:14:38 2016 +0100
Revision:
1156:e1ea38b576c6
Parent:
1155:e28c7aac64ab
Child:
1178:a4418fcb462f
Synchronized with git rev 5749d87d

Author: Andres Amaya Garcia

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