Marco Ferreira / BLE_API

just a fork

Fork of BLE_API by Bluetooth Low Energy

ble/BLEInstanceBase.h@1145:d21353309b6c, 2016-04-06 (annotated)

Committer:
vcoubard
Date:
Wed Apr 06 19:14:13 2016 +0100
Revision:
1145:d21353309b6c
Parent:
1048:efb29faf12fc
Child:
1155:e28c7aac64ab
Synchronized with git rev 759c32d2

Author: Andres Amaya Garcia

Add missing documentation to BLEInstanceBase.h

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