EL4121 Embedded System / mbed-os

mbed-os

Dependents:   cobaLCDJoyMotor_Thread odometry_omni_3roda_v3 odometry_omni_3roda_v1 odometry_omni_3roda_v2 ... more

features/FEATURE_BLE/ble/BLE.h@0:b74591d5ab33, 2017-12-11 (annotated)

Committer:
be_bryan
Date:
Mon Dec 11 17:54:04 2017 +0000
Revision:
0:b74591d5ab33
motor ++

Who changed what in which revision?

UserRevisionLine numberNew contents of line
be_bryan 0:b74591d5ab33 1 /* mbed Microcontroller Library
be_bryan 0:b74591d5ab33 2 * Copyright (c) 2006-2013 ARM Limited
be_bryan 0:b74591d5ab33 3 *
be_bryan 0:b74591d5ab33 4 * Licensed under the Apache License, Version 2.0 (the "License");
be_bryan 0:b74591d5ab33 5 * you may not use this file except in compliance with the License.
be_bryan 0:b74591d5ab33 6 * You may obtain a copy of the License at
be_bryan 0:b74591d5ab33 7 *
be_bryan 0:b74591d5ab33 8 * http://www.apache.org/licenses/LICENSE-2.0
be_bryan 0:b74591d5ab33 9 *
be_bryan 0:b74591d5ab33 10 * Unless required by applicable law or agreed to in writing, software
be_bryan 0:b74591d5ab33 11 * distributed under the License is distributed on an "AS IS" BASIS,
be_bryan 0:b74591d5ab33 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
be_bryan 0:b74591d5ab33 13 * See the License for the specific language governing permissions and
be_bryan 0:b74591d5ab33 14 * limitations under the License.
be_bryan 0:b74591d5ab33 15 */
be_bryan 0:b74591d5ab33 16
be_bryan 0:b74591d5ab33 17 #ifndef MBED_BLE_H__
be_bryan 0:b74591d5ab33 18 #define MBED_BLE_H__
be_bryan 0:b74591d5ab33 19
be_bryan 0:b74591d5ab33 20 #include "blecommon.h"
be_bryan 0:b74591d5ab33 21 #include "Gap.h"
be_bryan 0:b74591d5ab33 22 #include "GattServer.h"
be_bryan 0:b74591d5ab33 23 #include "GattClient.h"
be_bryan 0:b74591d5ab33 24 #include "SecurityManager.h"
be_bryan 0:b74591d5ab33 25
be_bryan 0:b74591d5ab33 26 #include "ble/FunctionPointerWithContext.h"
be_bryan 0:b74591d5ab33 27
be_bryan 0:b74591d5ab33 28 #ifdef YOTTA_CFG_MBED_OS
be_bryan 0:b74591d5ab33 29 #include "mbed-drivers/mbed_error.h"
be_bryan 0:b74591d5ab33 30 #else
be_bryan 0:b74591d5ab33 31 #include "mbed_error.h"
be_bryan 0:b74591d5ab33 32 #endif
be_bryan 0:b74591d5ab33 33
be_bryan 0:b74591d5ab33 34 #include "platform/mbed_toolchain.h"
be_bryan 0:b74591d5ab33 35
be_bryan 0:b74591d5ab33 36 /* Forward declaration for the implementation class */
be_bryan 0:b74591d5ab33 37 class BLEInstanceBase;
be_bryan 0:b74591d5ab33 38
be_bryan 0:b74591d5ab33 39 /**
be_bryan 0:b74591d5ab33 40 * @addtogroup ble
be_bryan 0:b74591d5ab33 41 * @{
be_bryan 0:b74591d5ab33 42 */
be_bryan 0:b74591d5ab33 43
be_bryan 0:b74591d5ab33 44 /**
be_bryan 0:b74591d5ab33 45 * Abstract away BLE-capable radio transceivers or SOCs.
be_bryan 0:b74591d5ab33 46 *
be_bryan 0:b74591d5ab33 47 * Instances of this class have three responsibilities:
be_bryan 0:b74591d5ab33 48 * - Initialize the inner BLE subsystem.
be_bryan 0:b74591d5ab33 49 * - Signal user code that BLE events are available and an API to process them.
be_bryan 0:b74591d5ab33 50 * - Manage access to the instances abstracting each BLE layer:
be_bryan 0:b74591d5ab33 51 * + GAP: Handle advertising and scan, as well as connection and
be_bryan 0:b74591d5ab33 52 * disconnection.
be_bryan 0:b74591d5ab33 53 * + GATTServer: API to construct and manage a GATT server, which connected peers can
be_bryan 0:b74591d5ab33 54 * access.
be_bryan 0:b74591d5ab33 55 * + GATTClient: API to interact with a peer GATT server.
be_bryan 0:b74591d5ab33 56 * + SecurityManager: API to manage security.
be_bryan 0:b74591d5ab33 57 *
be_bryan 0:b74591d5ab33 58 * The user should not create BLE instances directly but rather access to the
be_bryan 0:b74591d5ab33 59 * singleton(s) holding the BLE interfaces present in the system by using the
be_bryan 0:b74591d5ab33 60 * static function Instance().
be_bryan 0:b74591d5ab33 61 *
be_bryan 0:b74591d5ab33 62 * @code
be_bryan 0:b74591d5ab33 63 * #include "ble/BLE.h"
be_bryan 0:b74591d5ab33 64 *
be_bryan 0:b74591d5ab33 65 * BLE& ble_interface = BLE::Instance();
be_bryan 0:b74591d5ab33 66 * @endcode
be_bryan 0:b74591d5ab33 67 *
be_bryan 0:b74591d5ab33 68 * Next, the signal handling/process mechanism should be set up. By design,
be_bryan 0:b74591d5ab33 69 * Mbed BLE does not impose to the user an event handling/processing mechanism;
be_bryan 0:b74591d5ab33 70 * however, it exposes APIs, which allows an application to compose its own:
be_bryan 0:b74591d5ab33 71 * - onEventsToProcess(), whichs register a callback that
be_bryan 0:b74591d5ab33 72 * the BLE subsystem will call when there is an event ready to be processed.
be_bryan 0:b74591d5ab33 73 * - processEvents(), which processes all the events present in the BLE subsystem.
be_bryan 0:b74591d5ab33 74 *
be_bryan 0:b74591d5ab33 75 * It is common to bind BLE event mechanism with Mbed EventQueue:
be_bryan 0:b74591d5ab33 76 *
be_bryan 0:b74591d5ab33 77 * @code
be_bryan 0:b74591d5ab33 78 * #include <events/mbed_events.h>
be_bryan 0:b74591d5ab33 79 * #include "ble/BLE.h"
be_bryan 0:b74591d5ab33 80 *
be_bryan 0:b74591d5ab33 81 * // declare the event queue, which the whole application will share.
be_bryan 0:b74591d5ab33 82 * static EventQueue event_queue( 4 * EVENTS_EVENT_SIZE);
be_bryan 0:b74591d5ab33 83 *
be_bryan 0:b74591d5ab33 84 * // Function invoked when there is a BLE event available.
be_bryan 0:b74591d5ab33 85 * // It put into the event queue the processing of the event(s)
be_bryan 0:b74591d5ab33 86 * void schedule_ble_processing(BLE::OnEventsToProcessCallbackContext* context) {
be_bryan 0:b74591d5ab33 87 * event_queue.call(callback(&(context->ble), &BLE::processEvents));
be_bryan 0:b74591d5ab33 88 * }
be_bryan 0:b74591d5ab33 89 *
be_bryan 0:b74591d5ab33 90 * int main()
be_bryan 0:b74591d5ab33 91 * {
be_bryan 0:b74591d5ab33 92 * BLE &ble_interface = BLE::Instance();
be_bryan 0:b74591d5ab33 93 *
be_bryan 0:b74591d5ab33 94 * // Bind event signaling to schedule_ble_processing
be_bryan 0:b74591d5ab33 95 * ble_interface.onEventsToProcess(schedule_ble_processing);
be_bryan 0:b74591d5ab33 96 *
be_bryan 0:b74591d5ab33 97 * // Launch BLE initialisation
be_bryan 0:b74591d5ab33 98 *
be_bryan 0:b74591d5ab33 99 * // Dispatch events in the event queue
be_bryan 0:b74591d5ab33 100 * event_queue.dispatch_forever();
be_bryan 0:b74591d5ab33 101 * return 0;
be_bryan 0:b74591d5ab33 102 * }
be_bryan 0:b74591d5ab33 103 * @endcode
be_bryan 0:b74591d5ab33 104 *
be_bryan 0:b74591d5ab33 105 * Once the event processing mechanism is in place, the Bluetooth subsystem can
be_bryan 0:b74591d5ab33 106 * be initialized with the init() function. That function accepts in input a
be_bryan 0:b74591d5ab33 107 * callback, which will be invoked once the initialization process has finished.
be_bryan 0:b74591d5ab33 108 *
be_bryan 0:b74591d5ab33 109 * @code
be_bryan 0:b74591d5ab33 110 * void on_ble_init_complete(BLE::InitializationCompleteCallbackContext *context)
be_bryan 0:b74591d5ab33 111 * {
be_bryan 0:b74591d5ab33 112 * BLE& ble_interface = context->ble;
be_bryan 0:b74591d5ab33 113 * ble_error_t initialization_error = context->error;
be_bryan 0:b74591d5ab33 114 *
be_bryan 0:b74591d5ab33 115 * if (initialization_error) {
be_bryan 0:b74591d5ab33 116 * // handle error
be_bryan 0:b74591d5ab33 117 * return;
be_bryan 0:b74591d5ab33 118 * }
be_bryan 0:b74591d5ab33 119 *
be_bryan 0:b74591d5ab33 120 * // The BLE interface can be accessed now.
be_bryan 0:b74591d5ab33 121 * }
be_bryan 0:b74591d5ab33 122 *
be_bryan 0:b74591d5ab33 123 * int main() {
be_bryan 0:b74591d5ab33 124 * BLE &ble_interface = BLE::Instance();
be_bryan 0:b74591d5ab33 125 * ble_interface.onEventsToProcess(schedule_ble_processing);
be_bryan 0:b74591d5ab33 126 *
be_bryan 0:b74591d5ab33 127 * // Initialize the BLE interface
be_bryan 0:b74591d5ab33 128 * ble_interface.init(on_ble_init_complete);
be_bryan 0:b74591d5ab33 129 *
be_bryan 0:b74591d5ab33 130 * event_queue.dispatch_forever();
be_bryan 0:b74591d5ab33 131 * return 0;
be_bryan 0:b74591d5ab33 132 * }
be_bryan 0:b74591d5ab33 133 * @endcode
be_bryan 0:b74591d5ab33 134 */
be_bryan 0:b74591d5ab33 135 class BLE
be_bryan 0:b74591d5ab33 136 {
be_bryan 0:b74591d5ab33 137 public:
be_bryan 0:b74591d5ab33 138 /**
be_bryan 0:b74591d5ab33 139 * Opaque type used to store the ID of a BLE instance.
be_bryan 0:b74591d5ab33 140 */
be_bryan 0:b74591d5ab33 141 typedef unsigned InstanceID_t;
be_bryan 0:b74591d5ab33 142
be_bryan 0:b74591d5ab33 143 /**
be_bryan 0:b74591d5ab33 144 * The value of the BLE::InstanceID_t for the default BLE instance.
be_bryan 0:b74591d5ab33 145 */
be_bryan 0:b74591d5ab33 146 static const InstanceID_t DEFAULT_INSTANCE = 0;
be_bryan 0:b74591d5ab33 147
be_bryan 0:b74591d5ab33 148 #ifndef YOTTA_CFG_BLE_INSTANCES_COUNT
be_bryan 0:b74591d5ab33 149 /**
be_bryan 0:b74591d5ab33 150 * The number of permitted BLE instances for the application.
be_bryan 0:b74591d5ab33 151 */
be_bryan 0:b74591d5ab33 152 static const InstanceID_t NUM_INSTANCES = 1;
be_bryan 0:b74591d5ab33 153 #else
be_bryan 0:b74591d5ab33 154 /**
be_bryan 0:b74591d5ab33 155 * The number of permitted BLE instances for the application.
be_bryan 0:b74591d5ab33 156 */
be_bryan 0:b74591d5ab33 157 static const InstanceID_t NUM_INSTANCES = YOTTA_CFG_BLE_INSTANCES_COUNT;
be_bryan 0:b74591d5ab33 158 #endif
be_bryan 0:b74591d5ab33 159
be_bryan 0:b74591d5ab33 160 /**
be_bryan 0:b74591d5ab33 161 * Get a reference to the BLE singleton corresponding to a given interface.
be_bryan 0:b74591d5ab33 162 *
be_bryan 0:b74591d5ab33 163 * There is a static array of BLE singletons.
be_bryan 0:b74591d5ab33 164 *
be_bryan 0:b74591d5ab33 165 * @note Calling Instance() is preferred over constructing a BLE object
be_bryan 0:b74591d5ab33 166 * directly because it returns references to singletons.
be_bryan 0:b74591d5ab33 167 *
be_bryan 0:b74591d5ab33 168 * @param[in] id BLE Instance ID to get.
be_bryan 0:b74591d5ab33 169 *
be_bryan 0:b74591d5ab33 170 * @return A reference to a single object.
be_bryan 0:b74591d5ab33 171 *
be_bryan 0:b74591d5ab33 172 * @pre id shall be less than NUM_INSTANCES.
be_bryan 0:b74591d5ab33 173 */
be_bryan 0:b74591d5ab33 174 static BLE &Instance(InstanceID_t id = DEFAULT_INSTANCE);
be_bryan 0:b74591d5ab33 175
be_bryan 0:b74591d5ab33 176 /**
be_bryan 0:b74591d5ab33 177 * Fetch the ID of a BLE instance.
be_bryan 0:b74591d5ab33 178 *
be_bryan 0:b74591d5ab33 179 * @return Instance id of this BLE instance.
be_bryan 0:b74591d5ab33 180 */
be_bryan 0:b74591d5ab33 181 InstanceID_t getInstanceID(void) const {
be_bryan 0:b74591d5ab33 182 return instanceID;
be_bryan 0:b74591d5ab33 183 }
be_bryan 0:b74591d5ab33 184
be_bryan 0:b74591d5ab33 185 /**
be_bryan 0:b74591d5ab33 186 * Events to process event.
be_bryan 0:b74591d5ab33 187 *
be_bryan 0:b74591d5ab33 188 * Instances of OnEventsToProcessCallbackContext are passed to the event
be_bryan 0:b74591d5ab33 189 * handler registered with onEventsToProcess().
be_bryan 0:b74591d5ab33 190 */
be_bryan 0:b74591d5ab33 191 struct OnEventsToProcessCallbackContext {
be_bryan 0:b74591d5ab33 192 /**
be_bryan 0:b74591d5ab33 193 * The ble instance which have events to process.
be_bryan 0:b74591d5ab33 194 */
be_bryan 0:b74591d5ab33 195 BLE& ble;
be_bryan 0:b74591d5ab33 196 };
be_bryan 0:b74591d5ab33 197
be_bryan 0:b74591d5ab33 198 /**
be_bryan 0:b74591d5ab33 199 * Events to process event handler
be_bryan 0:b74591d5ab33 200 */
be_bryan 0:b74591d5ab33 201 typedef FunctionPointerWithContext<OnEventsToProcessCallbackContext*>
be_bryan 0:b74591d5ab33 202 OnEventsToProcessCallback_t;
be_bryan 0:b74591d5ab33 203
be_bryan 0:b74591d5ab33 204 /**
be_bryan 0:b74591d5ab33 205 * Register a callback called when the BLE stack has pending work.
be_bryan 0:b74591d5ab33 206 *
be_bryan 0:b74591d5ab33 207 * By registering a callback, application code can know when event processing
be_bryan 0:b74591d5ab33 208 * has to be scheduled.
be_bryan 0:b74591d5ab33 209 *
be_bryan 0:b74591d5ab33 210 * @param on_event_cb Callback invoked when there are new events to process.
be_bryan 0:b74591d5ab33 211 */
be_bryan 0:b74591d5ab33 212 void onEventsToProcess(const OnEventsToProcessCallback_t& on_event_cb);
be_bryan 0:b74591d5ab33 213
be_bryan 0:b74591d5ab33 214 /**
be_bryan 0:b74591d5ab33 215 * Process ALL pending events living in the BLE stack and return once all
be_bryan 0:b74591d5ab33 216 * events have been consumed.
be_bryan 0:b74591d5ab33 217 *
be_bryan 0:b74591d5ab33 218 * @see onEventsToProcess()
be_bryan 0:b74591d5ab33 219 */
be_bryan 0:b74591d5ab33 220 void processEvents();
be_bryan 0:b74591d5ab33 221
be_bryan 0:b74591d5ab33 222 /**
be_bryan 0:b74591d5ab33 223 * Initialization complete event.
be_bryan 0:b74591d5ab33 224 *
be_bryan 0:b74591d5ab33 225 * This event is generated at the end of the init() procedure and is passed
be_bryan 0:b74591d5ab33 226 * to the completion callback passed to init().
be_bryan 0:b74591d5ab33 227 */
be_bryan 0:b74591d5ab33 228 struct InitializationCompleteCallbackContext {
be_bryan 0:b74591d5ab33 229 /**
be_bryan 0:b74591d5ab33 230 * Reference to the BLE object that has been initialized
be_bryan 0:b74591d5ab33 231 */
be_bryan 0:b74591d5ab33 232 BLE& ble;
be_bryan 0:b74591d5ab33 233
be_bryan 0:b74591d5ab33 234 /**
be_bryan 0:b74591d5ab33 235 * Error status of the initialization.
be_bryan 0:b74591d5ab33 236 *
be_bryan 0:b74591d5ab33 237 * That value is set to BLE_ERROR_NONE if initialization completed
be_bryan 0:b74591d5ab33 238 * successfully or the appropriate error code otherwise.
be_bryan 0:b74591d5ab33 239 * */
be_bryan 0:b74591d5ab33 240 ble_error_t error;
be_bryan 0:b74591d5ab33 241 };
be_bryan 0:b74591d5ab33 242
be_bryan 0:b74591d5ab33 243 /**
be_bryan 0:b74591d5ab33 244 * Initialization complete event handler.
be_bryan 0:b74591d5ab33 245 *
be_bryan 0:b74591d5ab33 246 * @note There are two versions of init(). In addition to the
be_bryan 0:b74591d5ab33 247 * function-pointer, init() can also take an <Object, member> tuple as its
be_bryan 0:b74591d5ab33 248 * callback target. In case of the latter, the following declaration doesn't
be_bryan 0:b74591d5ab33 249 * apply.
be_bryan 0:b74591d5ab33 250 */
be_bryan 0:b74591d5ab33 251 typedef void (*InitializationCompleteCallback_t)(
be_bryan 0:b74591d5ab33 252 InitializationCompleteCallbackContext *context
be_bryan 0:b74591d5ab33 253 );
be_bryan 0:b74591d5ab33 254
be_bryan 0:b74591d5ab33 255 /**
be_bryan 0:b74591d5ab33 256 * Initialize the BLE controller/stack.
be_bryan 0:b74591d5ab33 257 *
be_bryan 0:b74591d5ab33 258 * init() hands control to the underlying BLE module to accomplish
be_bryan 0:b74591d5ab33 259 * initialization. This initialization may tacitly depend on other hardware
be_bryan 0:b74591d5ab33 260 * setup (such as clocks or power-modes) that happens early on during system
be_bryan 0:b74591d5ab33 261 * startup. It may not be safe to call init() from a global static context
be_bryan 0:b74591d5ab33 262 * where ordering is compiler-specific and can't be guaranteed - it is safe
be_bryan 0:b74591d5ab33 263 * to call BLE::init() from within main().
be_bryan 0:b74591d5ab33 264 *
be_bryan 0:b74591d5ab33 265 * @param[in] completion_cb A callback for when initialization completes for
be_bryan 0:b74591d5ab33 266 * a BLE instance. This is an optional parameter; if no callback is set up,
be_bryan 0:b74591d5ab33 267 * the application can still determine the status of initialization using
be_bryan 0:b74591d5ab33 268 * BLE::hasInitialized() (see below).
be_bryan 0:b74591d5ab33 269 *
be_bryan 0:b74591d5ab33 270 * @return BLE_ERROR_NONE if the initialization procedure started
be_bryan 0:b74591d5ab33 271 * successfully.
be_bryan 0:b74591d5ab33 272 *
be_bryan 0:b74591d5ab33 273 * @note If init() returns BLE_ERROR_NONE, the underlying stack must invoke
be_bryan 0:b74591d5ab33 274 * the initialization completion callback at some point.
be_bryan 0:b74591d5ab33 275 *
be_bryan 0:b74591d5ab33 276 * @note Nearly all BLE APIs would return BLE_ERROR_INITIALIZATION_INCOMPLETE
be_bryan 0:b74591d5ab33 277 * if used on an instance before the corresponding transport is initialized.
be_bryan 0:b74591d5ab33 278 *
be_bryan 0:b74591d5ab33 279 * @note There are two versions of init(). In addition to the
be_bryan 0:b74591d5ab33 280 * function-pointer, init() can also take an <Object, member> pair as its
be_bryan 0:b74591d5ab33 281 * callback target.
be_bryan 0:b74591d5ab33 282 *
be_bryan 0:b74591d5ab33 283 * @important This should be called before using anything else in the BLE
be_bryan 0:b74591d5ab33 284 * API.
be_bryan 0:b74591d5ab33 285 */
be_bryan 0:b74591d5ab33 286 ble_error_t init(InitializationCompleteCallback_t completion_cb = NULL) {
be_bryan 0:b74591d5ab33 287 FunctionPointerWithContext<InitializationCompleteCallbackContext *> callback(completion_cb);
be_bryan 0:b74591d5ab33 288 return initImplementation(callback);
be_bryan 0:b74591d5ab33 289 }
be_bryan 0:b74591d5ab33 290
be_bryan 0:b74591d5ab33 291 /**
be_bryan 0:b74591d5ab33 292 * Initialize the BLE controller/stack.
be_bryan 0:b74591d5ab33 293 *
be_bryan 0:b74591d5ab33 294 * This is an alternate declaration for init(). This one takes an
be_bryan 0:b74591d5ab33 295 * <Object, member> pair as its callback target.
be_bryan 0:b74591d5ab33 296 *
be_bryan 0:b74591d5ab33 297 * @param[in] object Object, which will be used to invoke the completion callback.
be_bryan 0:b74591d5ab33 298 * @param[in] completion_cb Member function pointer, which will be invoked when
be_bryan 0:b74591d5ab33 299 * initialization is complete.
be_bryan 0:b74591d5ab33 300 */
be_bryan 0:b74591d5ab33 301 template<typename T>
be_bryan 0:b74591d5ab33 302 ble_error_t init(T *object, void (T::*completion_cb)(InitializationCompleteCallbackContext *context)) {
be_bryan 0:b74591d5ab33 303 FunctionPointerWithContext<InitializationCompleteCallbackContext *> callback(object, completion_cb);
be_bryan 0:b74591d5ab33 304 return initImplementation(callback);
be_bryan 0:b74591d5ab33 305 }
be_bryan 0:b74591d5ab33 306
be_bryan 0:b74591d5ab33 307 /**
be_bryan 0:b74591d5ab33 308 * Indicate if the BLE instance has been initialized.
be_bryan 0:b74591d5ab33 309 *
be_bryan 0:b74591d5ab33 310 * @return true if initialization has completed for the underlying BLE
be_bryan 0:b74591d5ab33 311 * transport.
be_bryan 0:b74591d5ab33 312 *
be_bryan 0:b74591d5ab33 313 * @note The application should set up a callback to signal completion of
be_bryan 0:b74591d5ab33 314 * initialization when using init().
be_bryan 0:b74591d5ab33 315 */
be_bryan 0:b74591d5ab33 316 bool hasInitialized(void) const;
be_bryan 0:b74591d5ab33 317
be_bryan 0:b74591d5ab33 318 /**
be_bryan 0:b74591d5ab33 319 * Shut down the underlying stack, and reset state of this BLE instance.
be_bryan 0:b74591d5ab33 320 *
be_bryan 0:b74591d5ab33 321 * @return BLE_ERROR_NONE if the instance was shut down without error or the
be_bryan 0:b74591d5ab33 322 * appropriate error code.
be_bryan 0:b74591d5ab33 323 *
be_bryan 0:b74591d5ab33 324 * @important init() must be called afterward to reinstate services and
be_bryan 0:b74591d5ab33 325 * GAP state. This API offers a way to repopulate the GATT database with new
be_bryan 0:b74591d5ab33 326 * services and characteristics.
be_bryan 0:b74591d5ab33 327 */
be_bryan 0:b74591d5ab33 328 ble_error_t shutdown(void);
be_bryan 0:b74591d5ab33 329
be_bryan 0:b74591d5ab33 330 /**
be_bryan 0:b74591d5ab33 331 * This call allows the application to get the BLE stack version information.
be_bryan 0:b74591d5ab33 332 *
be_bryan 0:b74591d5ab33 333 * @return A pointer to a const string representing the version.
be_bryan 0:b74591d5ab33 334 *
be_bryan 0:b74591d5ab33 335 * @note The BLE API owns the string returned.
be_bryan 0:b74591d5ab33 336 */
be_bryan 0:b74591d5ab33 337 const char *getVersion(void);
be_bryan 0:b74591d5ab33 338
be_bryan 0:b74591d5ab33 339 /**
be_bryan 0:b74591d5ab33 340 * Accessor to Gap. All Gap-related functionality requires going through
be_bryan 0:b74591d5ab33 341 * this accessor.
be_bryan 0:b74591d5ab33 342 *
be_bryan 0:b74591d5ab33 343 * @return A reference to a Gap object associated to this BLE instance.
be_bryan 0:b74591d5ab33 344 */
be_bryan 0:b74591d5ab33 345 Gap &gap();
be_bryan 0:b74591d5ab33 346
be_bryan 0:b74591d5ab33 347 /**
be_bryan 0:b74591d5ab33 348 * A const alternative to gap().
be_bryan 0:b74591d5ab33 349 *
be_bryan 0:b74591d5ab33 350 * @return A const reference to a Gap object associated to this BLE instance.
be_bryan 0:b74591d5ab33 351 */
be_bryan 0:b74591d5ab33 352 const Gap &gap() const;
be_bryan 0:b74591d5ab33 353
be_bryan 0:b74591d5ab33 354 /**
be_bryan 0:b74591d5ab33 355 * Accessor to GattServer. All GattServer related functionality requires
be_bryan 0:b74591d5ab33 356 * going through this accessor.
be_bryan 0:b74591d5ab33 357 *
be_bryan 0:b74591d5ab33 358 * @return A reference to a GattServer object associated to this BLE instance.
be_bryan 0:b74591d5ab33 359 */
be_bryan 0:b74591d5ab33 360 GattServer& gattServer();
be_bryan 0:b74591d5ab33 361
be_bryan 0:b74591d5ab33 362 /**
be_bryan 0:b74591d5ab33 363 * A const alternative to gattServer().
be_bryan 0:b74591d5ab33 364 *
be_bryan 0:b74591d5ab33 365 * @return A const reference to a GattServer object associated to this BLE
be_bryan 0:b74591d5ab33 366 * instance.
be_bryan 0:b74591d5ab33 367 */
be_bryan 0:b74591d5ab33 368 const GattServer& gattServer() const;
be_bryan 0:b74591d5ab33 369
be_bryan 0:b74591d5ab33 370 /**
be_bryan 0:b74591d5ab33 371 * Accessors to GattClient. All GattClient related functionality requires
be_bryan 0:b74591d5ab33 372 * going through this accessor.
be_bryan 0:b74591d5ab33 373 *
be_bryan 0:b74591d5ab33 374 * @return A reference to a GattClient object associated to this BLE instance.
be_bryan 0:b74591d5ab33 375 */
be_bryan 0:b74591d5ab33 376 GattClient& gattClient();
be_bryan 0:b74591d5ab33 377
be_bryan 0:b74591d5ab33 378 /**
be_bryan 0:b74591d5ab33 379 * A const alternative to gattClient().
be_bryan 0:b74591d5ab33 380 *
be_bryan 0:b74591d5ab33 381 * @return A const reference to a GattClient object associated to this BLE
be_bryan 0:b74591d5ab33 382 * instance.
be_bryan 0:b74591d5ab33 383 */
be_bryan 0:b74591d5ab33 384 const GattClient& gattClient() const;
be_bryan 0:b74591d5ab33 385
be_bryan 0:b74591d5ab33 386 /**
be_bryan 0:b74591d5ab33 387 * Accessors to SecurityManager. All SecurityManager-related functionality
be_bryan 0:b74591d5ab33 388 * requires going through this accessor.
be_bryan 0:b74591d5ab33 389 *
be_bryan 0:b74591d5ab33 390 * @return A reference to a SecurityManager object associated to this BLE
be_bryan 0:b74591d5ab33 391 * instance.
be_bryan 0:b74591d5ab33 392 */
be_bryan 0:b74591d5ab33 393 SecurityManager& securityManager();
be_bryan 0:b74591d5ab33 394
be_bryan 0:b74591d5ab33 395 /**
be_bryan 0:b74591d5ab33 396 * A const alternative to securityManager().
be_bryan 0:b74591d5ab33 397 *
be_bryan 0:b74591d5ab33 398 * @return A const reference to a SecurityManager object associated to this
be_bryan 0:b74591d5ab33 399 * BLE instance.
be_bryan 0:b74591d5ab33 400 */
be_bryan 0:b74591d5ab33 401 const SecurityManager& securityManager() const;
be_bryan 0:b74591d5ab33 402
be_bryan 0:b74591d5ab33 403 /*
be_bryan 0:b74591d5ab33 404 * Deprecation alert!
be_bryan 0:b74591d5ab33 405 * All of the following are deprecated and may be dropped in a future
be_bryan 0:b74591d5ab33 406 * release. Documentation should refer to alternative APIs.
be_bryan 0:b74591d5ab33 407 */
be_bryan 0:b74591d5ab33 408 public:
be_bryan 0:b74591d5ab33 409 /**
be_bryan 0:b74591d5ab33 410 * Constructor for a handle to a BLE instance (the BLE stack). BLE handles
be_bryan 0:b74591d5ab33 411 * are thin wrappers around a transport object (that is, ptr. to
be_bryan 0:b74591d5ab33 412 * BLEInstanceBase).
be_bryan 0:b74591d5ab33 413 *
be_bryan 0:b74591d5ab33 414 * It is better to create BLE objects as singletons accessed through the
be_bryan 0:b74591d5ab33 415 * Instance() method. If multiple BLE handles are constructed for the same
be_bryan 0:b74591d5ab33 416 * interface (using this constructor), they share the same underlying
be_bryan 0:b74591d5ab33 417 * transport object.
be_bryan 0:b74591d5ab33 418 *
be_bryan 0:b74591d5ab33 419 * @deprecated Use the Instance() function instead of the constructor.
be_bryan 0:b74591d5ab33 420 */
be_bryan 0:b74591d5ab33 421 MBED_DEPRECATED("Use BLE::Instance() instead of BLE constructor.")
be_bryan 0:b74591d5ab33 422 BLE(InstanceID_t instanceID = DEFAULT_INSTANCE);
be_bryan 0:b74591d5ab33 423
be_bryan 0:b74591d5ab33 424 /**
be_bryan 0:b74591d5ab33 425 * Yield control to the BLE stack or to other tasks waiting for events.
be_bryan 0:b74591d5ab33 426 *
be_bryan 0:b74591d5ab33 427 * This is a sleep function that returns when there is an application-specific
be_bryan 0:b74591d5ab33 428 * interrupt. This is not interchangeable with WFE() considering that the
be_bryan 0:b74591d5ab33 429 * MCU might wake up several times to service the stack before returning
be_bryan 0:b74591d5ab33 430 * control to the caller.
be_bryan 0:b74591d5ab33 431 *
be_bryan 0:b74591d5ab33 432 * @deprecated This function block the CPU prefer to use the pair
be_bryan 0:b74591d5ab33 433 * onEventsToProcess() and processEvents().
be_bryan 0:b74591d5ab33 434 */
be_bryan 0:b74591d5ab33 435 MBED_DEPRECATED("Use BLE::processEvents() and BLE::onEventsToProcess().")
be_bryan 0:b74591d5ab33 436 void waitForEvent(void);
be_bryan 0:b74591d5ab33 437
be_bryan 0:b74591d5ab33 438 /**
be_bryan 0:b74591d5ab33 439 * Set the BTLE MAC address and type.
be_bryan 0:b74591d5ab33 440 *
be_bryan 0:b74591d5ab33 441 * @return BLE_ERROR_NONE on success.
be_bryan 0:b74591d5ab33 442 *
be_bryan 0:b74591d5ab33 443 * @deprecated You should use the parallel API from Gap directly, refer to
be_bryan 0:b74591d5ab33 444 * Gap::setAddress(). A former call to ble.setAddress(...) should be
be_bryan 0:b74591d5ab33 445 * replaced with ble.gap().setAddress(...).
be_bryan 0:b74591d5ab33 446 */
be_bryan 0:b74591d5ab33 447 MBED_DEPRECATED("Use ble.gap().setAddress(...)")
be_bryan 0:b74591d5ab33 448 ble_error_t setAddress(
be_bryan 0:b74591d5ab33 449 BLEProtocol::AddressType_t type,
be_bryan 0:b74591d5ab33 450 const BLEProtocol::AddressBytes_t address
be_bryan 0:b74591d5ab33 451 ) {
be_bryan 0:b74591d5ab33 452 return gap().setAddress(type, address);
be_bryan 0:b74591d5ab33 453 }
be_bryan 0:b74591d5ab33 454
be_bryan 0:b74591d5ab33 455 /**
be_bryan 0:b74591d5ab33 456 * Fetch the Bluetooth Low Energy MAC address and type.
be_bryan 0:b74591d5ab33 457 *
be_bryan 0:b74591d5ab33 458 * @return BLE_ERROR_NONE on success.
be_bryan 0:b74591d5ab33 459 *
be_bryan 0:b74591d5ab33 460 * @deprecated You should use the parallel API from Gap directly and refer to
be_bryan 0:b74591d5ab33 461 * Gap::getAddress(). A former call to ble.getAddress(...) should be
be_bryan 0:b74591d5ab33 462 * replaced with ble.gap().getAddress(...).
be_bryan 0:b74591d5ab33 463 */
be_bryan 0:b74591d5ab33 464 MBED_DEPRECATED("Use ble.gap().getAddress(...)")
be_bryan 0:b74591d5ab33 465 ble_error_t getAddress(
be_bryan 0:b74591d5ab33 466 BLEProtocol::AddressType_t *typeP, BLEProtocol::AddressBytes_t address
be_bryan 0:b74591d5ab33 467 ) {
be_bryan 0:b74591d5ab33 468 return gap().getAddress(typeP, address);
be_bryan 0:b74591d5ab33 469 }
be_bryan 0:b74591d5ab33 470
be_bryan 0:b74591d5ab33 471 /**
be_bryan 0:b74591d5ab33 472 * Set the GAP advertising mode to use for this device.
be_bryan 0:b74591d5ab33 473 *
be_bryan 0:b74591d5ab33 474 * @deprecated You should use the parallel API from Gap directly and refer to
be_bryan 0:b74591d5ab33 475 * Gap::setAdvertisingType(). A former call to
be_bryan 0:b74591d5ab33 476 * ble.setAdvertisingType(...) should be replaced with
be_bryan 0:b74591d5ab33 477 * ble.gap().setAdvertisingType(...).
be_bryan 0:b74591d5ab33 478 */
be_bryan 0:b74591d5ab33 479 MBED_DEPRECATED("Use ble.gap().setAdvertisingType(...)")
be_bryan 0:b74591d5ab33 480 void setAdvertisingType(GapAdvertisingParams::AdvertisingType advType) {
be_bryan 0:b74591d5ab33 481 gap().setAdvertisingType(advType);
be_bryan 0:b74591d5ab33 482 }
be_bryan 0:b74591d5ab33 483
be_bryan 0:b74591d5ab33 484 /**
be_bryan 0:b74591d5ab33 485 * @param[in] interval
be_bryan 0:b74591d5ab33 486 * Advertising interval in units of milliseconds. Advertising
be_bryan 0:b74591d5ab33 487 * is disabled if interval is 0. If interval is smaller than
be_bryan 0:b74591d5ab33 488 * the minimum supported value, then the minimum supported
be_bryan 0:b74591d5ab33 489 * value is used instead. This minimum value can be discovered
be_bryan 0:b74591d5ab33 490 * using getMinAdvertisingInterval().
be_bryan 0:b74591d5ab33 491 *
be_bryan 0:b74591d5ab33 492 * This field must be set to 0 if connectionMode is equal
be_bryan 0:b74591d5ab33 493 * to ADV_CONNECTABLE_DIRECTED.
be_bryan 0:b74591d5ab33 494 *
be_bryan 0:b74591d5ab33 495 * @note Decreasing this value allows central devices to detect a
be_bryan 0:b74591d5ab33 496 * peripheral faster at the expense of more power being used by the radio
be_bryan 0:b74591d5ab33 497 * due to the higher data transmit rate.
be_bryan 0:b74591d5ab33 498 *
be_bryan 0:b74591d5ab33 499 * @deprecated You should use the parallel API from Gap directly and refer to
be_bryan 0:b74591d5ab33 500 * Gap::setAdvertisingInterval(). A former call to
be_bryan 0:b74591d5ab33 501 * ble.setAdvertisingInterval(...) should be replaced with
be_bryan 0:b74591d5ab33 502 * ble.gap().setAdvertisingInterval(...).
be_bryan 0:b74591d5ab33 503 *
be_bryan 0:b74591d5ab33 504 * @note WARNING: This API previously used 0.625ms as the unit for its
be_bryan 0:b74591d5ab33 505 * 'interval' argument. That required an explicit conversion from
be_bryan 0:b74591d5ab33 506 * milliseconds using Gap::MSEC_TO_GAP_DURATION_UNITS(). This conversion is
be_bryan 0:b74591d5ab33 507 * no longer required as the new units are milliseconds. Any application
be_bryan 0:b74591d5ab33 508 * code depending on the old semantics needs to be updated accordingly.
be_bryan 0:b74591d5ab33 509 */
be_bryan 0:b74591d5ab33 510 MBED_DEPRECATED("Use ble.gap().setAdvertisingInterval(...)")
be_bryan 0:b74591d5ab33 511 void setAdvertisingInterval(uint16_t interval) {
be_bryan 0:b74591d5ab33 512 gap().setAdvertisingInterval(interval);
be_bryan 0:b74591d5ab33 513 }
be_bryan 0:b74591d5ab33 514
be_bryan 0:b74591d5ab33 515 /**
be_bryan 0:b74591d5ab33 516 * @return Minimum Advertising interval in milliseconds.
be_bryan 0:b74591d5ab33 517 *
be_bryan 0:b74591d5ab33 518 * @deprecated You should use the parallel API from Gap directly, refer to
be_bryan 0:b74591d5ab33 519 * Gap::getMinAdvertisingInterval(). A former call to
be_bryan 0:b74591d5ab33 520 * ble.getMinAdvertisingInterval(...) should be replaced with
be_bryan 0:b74591d5ab33 521 * ble.gap().getMinAdvertisingInterval(...).
be_bryan 0:b74591d5ab33 522 */
be_bryan 0:b74591d5ab33 523 MBED_DEPRECATED("Use ble.gap().getMinAdvertisingInterval(...)")
be_bryan 0:b74591d5ab33 524 uint16_t getMinAdvertisingInterval(void) const {
be_bryan 0:b74591d5ab33 525 return gap().getMinAdvertisingInterval();
be_bryan 0:b74591d5ab33 526 }
be_bryan 0:b74591d5ab33 527
be_bryan 0:b74591d5ab33 528 /**
be_bryan 0:b74591d5ab33 529 * @return Minimum Advertising interval in milliseconds for nonconnectible mode.
be_bryan 0:b74591d5ab33 530 *
be_bryan 0:b74591d5ab33 531 * @deprecated You should use the parallel API from Gap directly, refer to
be_bryan 0:b74591d5ab33 532 * Gap::MinNonConnectableAdvertisingInterval(). A former call to
be_bryan 0:b74591d5ab33 533 * ble.getMinNonConnectableAdvertisingInterval(...) should be replaced with
be_bryan 0:b74591d5ab33 534 * ble.gap().getMinNonConnectableAdvertisingInterval(...).
be_bryan 0:b74591d5ab33 535 */
be_bryan 0:b74591d5ab33 536 MBED_DEPRECATED("Use ble.gap().getMinNonConnectableAdvertisingInterval(...)")
be_bryan 0:b74591d5ab33 537 uint16_t getMinNonConnectableAdvertisingInterval(void) const {
be_bryan 0:b74591d5ab33 538 return gap().getMinNonConnectableAdvertisingInterval();
be_bryan 0:b74591d5ab33 539 }
be_bryan 0:b74591d5ab33 540
be_bryan 0:b74591d5ab33 541 /**
be_bryan 0:b74591d5ab33 542 * @return Maximum Advertising interval in milliseconds.
be_bryan 0:b74591d5ab33 543 *
be_bryan 0:b74591d5ab33 544 * @deprecated You should use the parallel API from Gap directly, refer to
be_bryan 0:b74591d5ab33 545 * Gap::getMaxAdvertisingInterval(). A former call to
be_bryan 0:b74591d5ab33 546 * ble.getMaxAdvertisingInterval(...) should be replaced with
be_bryan 0:b74591d5ab33 547 * ble.gap().getMaxAdvertisingInterval(...).
be_bryan 0:b74591d5ab33 548 */
be_bryan 0:b74591d5ab33 549 MBED_DEPRECATED("Use ble.gap().getMaxAdvertisingInterval(...)")
be_bryan 0:b74591d5ab33 550 uint16_t getMaxAdvertisingInterval(void) const {
be_bryan 0:b74591d5ab33 551 return gap().getMaxAdvertisingInterval();
be_bryan 0:b74591d5ab33 552 }
be_bryan 0:b74591d5ab33 553
be_bryan 0:b74591d5ab33 554 /**
be_bryan 0:b74591d5ab33 555 * @param[in] timeout
be_bryan 0:b74591d5ab33 556 * Advertising timeout (in seconds) between 0x1 and 0x3FFF (1
be_bryan 0:b74591d5ab33 557 * and 16383). Use 0 to disable the advertising timeout.
be_bryan 0:b74591d5ab33 558 *
be_bryan 0:b74591d5ab33 559 * @deprecated You should use the parallel API from Gap directly and refer to
be_bryan 0:b74591d5ab33 560 * Gap::setAdvertisingTimeout(). A former call to
be_bryan 0:b74591d5ab33 561 * ble.setAdvertisingTimeout(...) should be replaced with
be_bryan 0:b74591d5ab33 562 * ble.gap().setAdvertisingTimeout(...).
be_bryan 0:b74591d5ab33 563 */
be_bryan 0:b74591d5ab33 564 MBED_DEPRECATED("Use ble.gap().setAdvertisingTimeout(...)")
be_bryan 0:b74591d5ab33 565 void setAdvertisingTimeout(uint16_t timeout) {
be_bryan 0:b74591d5ab33 566 gap().setAdvertisingTimeout(timeout);
be_bryan 0:b74591d5ab33 567 }
be_bryan 0:b74591d5ab33 568
be_bryan 0:b74591d5ab33 569 /**
be_bryan 0:b74591d5ab33 570 * Set up a particular, user-constructed set of advertisement parameters for
be_bryan 0:b74591d5ab33 571 * the underlying stack. It would be uncommon for this API to be used
be_bryan 0:b74591d5ab33 572 * directly; there are other APIs to tweak advertisement parameters
be_bryan 0:b74591d5ab33 573 * individually (see above).
be_bryan 0:b74591d5ab33 574 *
be_bryan 0:b74591d5ab33 575 * @deprecated You should use the parallel API from Gap directly and refer to
be_bryan 0:b74591d5ab33 576 * Gap::setAdvertisingParams(). A former call to
be_bryan 0:b74591d5ab33 577 * ble.setAdvertisingParams(...) should be replaced with
be_bryan 0:b74591d5ab33 578 * ble.gap().setAdvertisingParams(...).
be_bryan 0:b74591d5ab33 579 */
be_bryan 0:b74591d5ab33 580 MBED_DEPRECATED("Use ble.gap().setAdvertisingParams(...)")
be_bryan 0:b74591d5ab33 581 void setAdvertisingParams(const GapAdvertisingParams &advParams) {
be_bryan 0:b74591d5ab33 582 gap().setAdvertisingParams(advParams);
be_bryan 0:b74591d5ab33 583 }
be_bryan 0:b74591d5ab33 584
be_bryan 0:b74591d5ab33 585 /**
be_bryan 0:b74591d5ab33 586 * @return Read back advertising parameters. Useful for storing and
be_bryan 0:b74591d5ab33 587 * restoring parameters rapidly.
be_bryan 0:b74591d5ab33 588 *
be_bryan 0:b74591d5ab33 589 * @deprecated You should use the parallel API from Gap directly and refer to
be_bryan 0:b74591d5ab33 590 * Gap::getAdvertisingParams(). A former call to
be_bryan 0:b74591d5ab33 591 * ble.getAdvertisingParams(...) should be replaced with
be_bryan 0:b74591d5ab33 592 * ble.gap().getAdvertisingParams(...).
be_bryan 0:b74591d5ab33 593 */
be_bryan 0:b74591d5ab33 594 MBED_DEPRECATED("Use ble.gap().getAdvertisingParams(...)")
be_bryan 0:b74591d5ab33 595 const GapAdvertisingParams &getAdvertisingParams(void) const {
be_bryan 0:b74591d5ab33 596 return gap().getAdvertisingParams();
be_bryan 0:b74591d5ab33 597 }
be_bryan 0:b74591d5ab33 598
be_bryan 0:b74591d5ab33 599 /**
be_bryan 0:b74591d5ab33 600 * Accumulate an AD structure in the advertising payload. Please note that
be_bryan 0:b74591d5ab33 601 * the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used
be_bryan 0:b74591d5ab33 602 * as an additional 31 bytes if the advertising payload is too
be_bryan 0:b74591d5ab33 603 * small.
be_bryan 0:b74591d5ab33 604 *
be_bryan 0:b74591d5ab33 605 * @param[in] flags
be_bryan 0:b74591d5ab33 606 * The flags to add. Please refer to
be_bryan 0:b74591d5ab33 607 * GapAdvertisingData::Flags for valid flags. Multiple
be_bryan 0:b74591d5ab33 608 * flags may be specified in combination.
be_bryan 0:b74591d5ab33 609 *
be_bryan 0:b74591d5ab33 610 * @deprecated You should use the parallel API from Gap directly, refer to
be_bryan 0:b74591d5ab33 611 * Gap::accumulateAdvertisingPayload(uint8_t). A former call to
be_bryan 0:b74591d5ab33 612 * ble.accumulateAdvertisingPayload(flags) should be replaced with
be_bryan 0:b74591d5ab33 613 * ble.gap().accumulateAdvertisingPayload(flags).
be_bryan 0:b74591d5ab33 614 */
be_bryan 0:b74591d5ab33 615 MBED_DEPRECATED("Use ble.gap().accumulateAdvertisingPayload(flags)")
be_bryan 0:b74591d5ab33 616 ble_error_t accumulateAdvertisingPayload(uint8_t flags) {
be_bryan 0:b74591d5ab33 617 return gap().accumulateAdvertisingPayload(flags);
be_bryan 0:b74591d5ab33 618 }
be_bryan 0:b74591d5ab33 619
be_bryan 0:b74591d5ab33 620 /**
be_bryan 0:b74591d5ab33 621 * Accumulate an AD structure in the advertising payload. Please note that
be_bryan 0:b74591d5ab33 622 * the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used
be_bryan 0:b74591d5ab33 623 * as an additional 31 bytes if the advertising payload is too
be_bryan 0:b74591d5ab33 624 * small.
be_bryan 0:b74591d5ab33 625 *
be_bryan 0:b74591d5ab33 626 * @param[in] app
be_bryan 0:b74591d5ab33 627 * The appearance of the peripheral.
be_bryan 0:b74591d5ab33 628 *
be_bryan 0:b74591d5ab33 629 * @deprecated You should use the parallel API from Gap directly and refer to
be_bryan 0:b74591d5ab33 630 * Gap::accumulateAdvertisingPayload(GapAdvertisingData::Appearance).
be_bryan 0:b74591d5ab33 631 * A former call to ble.accumulateAdvertisingPayload(appearance)
be_bryan 0:b74591d5ab33 632 * should be replaced with
be_bryan 0:b74591d5ab33 633 * ble.gap().accumulateAdvertisingPayload(appearance).
be_bryan 0:b74591d5ab33 634 */
be_bryan 0:b74591d5ab33 635 MBED_DEPRECATED("Use ble.gap().accumulateAdvertisingPayload(appearance)")
be_bryan 0:b74591d5ab33 636 ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::Appearance app) {
be_bryan 0:b74591d5ab33 637 return gap().accumulateAdvertisingPayload(app);
be_bryan 0:b74591d5ab33 638 }
be_bryan 0:b74591d5ab33 639
be_bryan 0:b74591d5ab33 640 /**
be_bryan 0:b74591d5ab33 641 * Accumulate an AD structure in the advertising payload. Please note that
be_bryan 0:b74591d5ab33 642 * the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used
be_bryan 0:b74591d5ab33 643 * as an additional 31 bytes if the advertising payload is too
be_bryan 0:b74591d5ab33 644 * small.
be_bryan 0:b74591d5ab33 645 *
be_bryan 0:b74591d5ab33 646 * @param[in] power
be_bryan 0:b74591d5ab33 647 * The max transmit power to be used by the controller. This
be_bryan 0:b74591d5ab33 648 * is only a hint.
be_bryan 0:b74591d5ab33 649 *
be_bryan 0:b74591d5ab33 650 * @deprecated You should use the parallel API from Gap directly and refer to
be_bryan 0:b74591d5ab33 651 * Gap::accumulateAdvertisingPayloadTxPower(). A former call to
be_bryan 0:b74591d5ab33 652 * ble.accumulateAdvertisingPayloadTxPower(txPower) should be replaced with
be_bryan 0:b74591d5ab33 653 * ble.gap().accumulateAdvertisingPayloadTxPower(txPower).
be_bryan 0:b74591d5ab33 654 */
be_bryan 0:b74591d5ab33 655 MBED_DEPRECATED("Use ble.gap().accumulateAdvertisingPayloadTxPower(...)")
be_bryan 0:b74591d5ab33 656 ble_error_t accumulateAdvertisingPayloadTxPower(int8_t power) {
be_bryan 0:b74591d5ab33 657 return gap().accumulateAdvertisingPayloadTxPower(power);
be_bryan 0:b74591d5ab33 658 }
be_bryan 0:b74591d5ab33 659
be_bryan 0:b74591d5ab33 660 /**
be_bryan 0:b74591d5ab33 661 * Accumulate a variable length byte-stream as an AD structure in the
be_bryan 0:b74591d5ab33 662 * advertising payload. Please note that the payload is limited to 31 bytes.
be_bryan 0:b74591d5ab33 663 * The SCAN_RESPONSE message may be used as an additional 31 bytes if the
be_bryan 0:b74591d5ab33 664 * advertising payload is too small.
be_bryan 0:b74591d5ab33 665 *
be_bryan 0:b74591d5ab33 666 * @param type The type that describes the variable length data.
be_bryan 0:b74591d5ab33 667 * @param data Data bytes.
be_bryan 0:b74591d5ab33 668 * @param len Data length.
be_bryan 0:b74591d5ab33 669 *
be_bryan 0:b74591d5ab33 670 * @deprecated You should use the parallel API from Gap directly, refer to
be_bryan 0:b74591d5ab33 671 * Gap::accumulateAdvertisingPayload(GapAdvertisingData::DataType, const uint8_t, uint8_t).
be_bryan 0:b74591d5ab33 672 * A former call to ble.accumulateAdvertisingPayload(...) should
be_bryan 0:b74591d5ab33 673 * be replaced with ble.gap().accumulateAdvertisingPayload(...).
be_bryan 0:b74591d5ab33 674 */
be_bryan 0:b74591d5ab33 675 MBED_DEPRECATED("Use ble.gap().accumulateAdvertisingPayload(...)")
be_bryan 0:b74591d5ab33 676 ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) {
be_bryan 0:b74591d5ab33 677 return gap().accumulateAdvertisingPayload(type, data, len);
be_bryan 0:b74591d5ab33 678 }
be_bryan 0:b74591d5ab33 679
be_bryan 0:b74591d5ab33 680 /**
be_bryan 0:b74591d5ab33 681 * Set up a particular, user-constructed advertisement payload for the
be_bryan 0:b74591d5ab33 682 * underlying stack. It would be uncommon for this API to be used directly;
be_bryan 0:b74591d5ab33 683 * there are other APIs to build an advertisement payload (see above).
be_bryan 0:b74591d5ab33 684 *
be_bryan 0:b74591d5ab33 685 * @deprecated You should use the parallel API from Gap directly, refer to
be_bryan 0:b74591d5ab33 686 * Gap::setAdvertisingData(). A former call to
be_bryan 0:b74591d5ab33 687 * ble.setAdvertisingData(...) should be replaced with
be_bryan 0:b74591d5ab33 688 * ble.gap().setAdvertisingPayload(...).
be_bryan 0:b74591d5ab33 689 */
be_bryan 0:b74591d5ab33 690 MBED_DEPRECATED("Use ble.gap().setAdvertisingData(...)")
be_bryan 0:b74591d5ab33 691 ble_error_t setAdvertisingData(const GapAdvertisingData &advData) {
be_bryan 0:b74591d5ab33 692 return gap().setAdvertisingPayload(advData);
be_bryan 0:b74591d5ab33 693 }
be_bryan 0:b74591d5ab33 694
be_bryan 0:b74591d5ab33 695 /**
be_bryan 0:b74591d5ab33 696 * @return Read back advertising data. Useful for storing and
be_bryan 0:b74591d5ab33 697 * restoring payload.
be_bryan 0:b74591d5ab33 698 *
be_bryan 0:b74591d5ab33 699 * @deprecated You should use the parallel API from Gap directly, refer to
be_bryan 0:b74591d5ab33 700 * Gap::getAdvertisingData(). A former call to
be_bryan 0:b74591d5ab33 701 * ble.getAdvertisingData(...) should be replaced with
be_bryan 0:b74591d5ab33 702 * ble.gap().getAdvertisingPayload()(...).
be_bryan 0:b74591d5ab33 703 */
be_bryan 0:b74591d5ab33 704 MBED_DEPRECATED("Use ble.gap().getAdvertisingData(...)")
be_bryan 0:b74591d5ab33 705 const GapAdvertisingData &getAdvertisingData(void) const {
be_bryan 0:b74591d5ab33 706 return gap().getAdvertisingPayload();
be_bryan 0:b74591d5ab33 707 }
be_bryan 0:b74591d5ab33 708
be_bryan 0:b74591d5ab33 709 /**
be_bryan 0:b74591d5ab33 710 * Reset any advertising payload prepared from prior calls to
be_bryan 0:b74591d5ab33 711 * accumulateAdvertisingPayload(). This automatically propagates the re-
be_bryan 0:b74591d5ab33 712 * initialized advertising payload to the underlying stack.
be_bryan 0:b74591d5ab33 713 *
be_bryan 0:b74591d5ab33 714 * @deprecated You should use the parallel API from Gap directly and refer to
be_bryan 0:b74591d5ab33 715 * Gap::clearAdvertisingPayload(). A former call to
be_bryan 0:b74591d5ab33 716 * ble.clearAdvertisingPayload(...) should be replaced with
be_bryan 0:b74591d5ab33 717 * ble.gap().clearAdvertisingPayload(...).
be_bryan 0:b74591d5ab33 718 */
be_bryan 0:b74591d5ab33 719 MBED_DEPRECATED("Use ble.gap().clearAdvertisingPayload(...)")
be_bryan 0:b74591d5ab33 720 void clearAdvertisingPayload(void) {
be_bryan 0:b74591d5ab33 721 gap().clearAdvertisingPayload();
be_bryan 0:b74591d5ab33 722 }
be_bryan 0:b74591d5ab33 723
be_bryan 0:b74591d5ab33 724 /**
be_bryan 0:b74591d5ab33 725 * Dynamically reset the accumulated advertising
be_bryan 0:b74591d5ab33 726 * payload and scanResponse. The application must clear and re-
be_bryan 0:b74591d5ab33 727 * accumulate a new advertising payload (and scanResponse) before using this
be_bryan 0:b74591d5ab33 728 * API.
be_bryan 0:b74591d5ab33 729 *
be_bryan 0:b74591d5ab33 730 * @return BLE_ERROR_NONE when the advertising payload is set successfully.
be_bryan 0:b74591d5ab33 731 *
be_bryan 0:b74591d5ab33 732 * @deprecated You should use the parallel API from Gap directly, refer to
be_bryan 0:b74591d5ab33 733 * Gap::setAdvertisingPayload().
be_bryan 0:b74591d5ab33 734 *
be_bryan 0:b74591d5ab33 735 * @note The new APIs in Gap update the underlying advertisement payload
be_bryan 0:b74591d5ab33 736 * implicitly.
be_bryan 0:b74591d5ab33 737 */
be_bryan 0:b74591d5ab33 738 MBED_DEPRECATED("Use ble.gap().setAdvertisingPayload(...)")
be_bryan 0:b74591d5ab33 739 ble_error_t setAdvertisingPayload(void) {
be_bryan 0:b74591d5ab33 740 return BLE_ERROR_NONE;
be_bryan 0:b74591d5ab33 741 }
be_bryan 0:b74591d5ab33 742
be_bryan 0:b74591d5ab33 743 /**
be_bryan 0:b74591d5ab33 744 * Accumulate a variable length byte-stream as an AD structure in the
be_bryan 0:b74591d5ab33 745 * scanResponse payload.
be_bryan 0:b74591d5ab33 746 *
be_bryan 0:b74591d5ab33 747 * @param[in] type The type that describes the variable length data.
be_bryan 0:b74591d5ab33 748 * @param[in] data Data bytes.
be_bryan 0:b74591d5ab33 749 * @param[in] len Data length.
be_bryan 0:b74591d5ab33 750 *
be_bryan 0:b74591d5ab33 751 * @deprecated You should use the parallel API from Gap directly and refer to
be_bryan 0:b74591d5ab33 752 * Gap::accumulateScanResponse(). A former call to
be_bryan 0:b74591d5ab33 753 * ble.accumulateScanResponse(...) should be replaced with
be_bryan 0:b74591d5ab33 754 * ble.gap().accumulateScanResponse(...).
be_bryan 0:b74591d5ab33 755 */
be_bryan 0:b74591d5ab33 756 MBED_DEPRECATED("Use ble.gap().accumulateScanResponse(...)")
be_bryan 0:b74591d5ab33 757 ble_error_t accumulateScanResponse(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) {
be_bryan 0:b74591d5ab33 758 return gap().accumulateScanResponse(type, data, len);
be_bryan 0:b74591d5ab33 759 }
be_bryan 0:b74591d5ab33 760
be_bryan 0:b74591d5ab33 761 /**
be_bryan 0:b74591d5ab33 762 * Reset any scan response prepared from prior calls to
be_bryan 0:b74591d5ab33 763 * accumulateScanResponse().
be_bryan 0:b74591d5ab33 764 *
be_bryan 0:b74591d5ab33 765 * @deprecated You should use the parallel API from Gap directly and refer to
be_bryan 0:b74591d5ab33 766 * Gap::clearScanResponse(). A former call to
be_bryan 0:b74591d5ab33 767 * ble.clearScanResponse(...) should be replaced with
be_bryan 0:b74591d5ab33 768 * ble.gap().clearScanResponse(...).
be_bryan 0:b74591d5ab33 769 */
be_bryan 0:b74591d5ab33 770 MBED_DEPRECATED("Use ble.gap().clearScanResponse(...)")
be_bryan 0:b74591d5ab33 771 void clearScanResponse(void) {
be_bryan 0:b74591d5ab33 772 gap().clearScanResponse();
be_bryan 0:b74591d5ab33 773 }
be_bryan 0:b74591d5ab33 774
be_bryan 0:b74591d5ab33 775 /**
be_bryan 0:b74591d5ab33 776 * Start advertising.
be_bryan 0:b74591d5ab33 777 *
be_bryan 0:b74591d5ab33 778 * @deprecated You should use the parallel API from Gap directly and refer to
be_bryan 0:b74591d5ab33 779 * Gap::startAdvertising(). A former call to
be_bryan 0:b74591d5ab33 780 * ble.startAdvertising(...) should be replaced with
be_bryan 0:b74591d5ab33 781 * ble.gap().startAdvertising(...).
be_bryan 0:b74591d5ab33 782 */
be_bryan 0:b74591d5ab33 783 MBED_DEPRECATED("Use ble.gap().startAdvertising(...)")
be_bryan 0:b74591d5ab33 784 ble_error_t startAdvertising(void) {
be_bryan 0:b74591d5ab33 785 return gap().startAdvertising();
be_bryan 0:b74591d5ab33 786 }
be_bryan 0:b74591d5ab33 787
be_bryan 0:b74591d5ab33 788 /**
be_bryan 0:b74591d5ab33 789 * Stop advertising.
be_bryan 0:b74591d5ab33 790 *
be_bryan 0:b74591d5ab33 791 * @deprecated You should use the parallel API from Gap directly and refer to
be_bryan 0:b74591d5ab33 792 * Gap::stopAdvertising(). A former call to
be_bryan 0:b74591d5ab33 793 * ble.stopAdvertising(...) should be replaced with
be_bryan 0:b74591d5ab33 794 * ble.gap().stopAdvertising(...).
be_bryan 0:b74591d5ab33 795 */
be_bryan 0:b74591d5ab33 796 MBED_DEPRECATED("Use ble.gap().stopAdvertising(...)")
be_bryan 0:b74591d5ab33 797 ble_error_t stopAdvertising(void) {
be_bryan 0:b74591d5ab33 798 return gap().stopAdvertising();
be_bryan 0:b74591d5ab33 799 }
be_bryan 0:b74591d5ab33 800
be_bryan 0:b74591d5ab33 801 /**
be_bryan 0:b74591d5ab33 802 * Set up parameters for GAP scanning (observer mode).
be_bryan 0:b74591d5ab33 803 * @param[in] interval
be_bryan 0:b74591d5ab33 804 * Scan interval (in milliseconds) [valid values lie between 2.5ms and 10.24s].
be_bryan 0:b74591d5ab33 805 * @param[in] window
be_bryan 0:b74591d5ab33 806 * Scan Window (in milliseconds) [valid values lie between 2.5ms and 10.24s].
be_bryan 0:b74591d5ab33 807 * @param[in] timeout
be_bryan 0:b74591d5ab33 808 * Scan timeout (in seconds) between 0x0001 and 0xFFFF; 0x0000 disables timeout.
be_bryan 0:b74591d5ab33 809 * @param[in] activeScanning
be_bryan 0:b74591d5ab33 810 * Set to True if active-scanning is required. This is used to fetch the
be_bryan 0:b74591d5ab33 811 * scan response from a peer if possible.
be_bryan 0:b74591d5ab33 812 *
be_bryan 0:b74591d5ab33 813 * The scanning window divided by the interval determines the duty cycle for
be_bryan 0:b74591d5ab33 814 * scanning. For example, if the interval is 100ms and the window is 10ms,
be_bryan 0:b74591d5ab33 815 * then the controller will scan for 10 percent of the time. It is possible
be_bryan 0:b74591d5ab33 816 * to have the interval and window set to the same value. In this case,
be_bryan 0:b74591d5ab33 817 * scanning is continuous, with a change of scanning frequency once every
be_bryan 0:b74591d5ab33 818 * interval.
be_bryan 0:b74591d5ab33 819 *
be_bryan 0:b74591d5ab33 820 * Once the scanning parameters have been configured, scanning can be
be_bryan 0:b74591d5ab33 821 * enabled by using startScan().
be_bryan 0:b74591d5ab33 822 *
be_bryan 0:b74591d5ab33 823 * @note The scan interval and window are recommendations to the BLE stack.
be_bryan 0:b74591d5ab33 824 *
be_bryan 0:b74591d5ab33 825 * @deprecated You should use the parallel API from Gap directly and refer to
be_bryan 0:b74591d5ab33 826 * Gap::setScanParams(). A former call to
be_bryan 0:b74591d5ab33 827 * ble.setScanParams(...) should be replaced with
be_bryan 0:b74591d5ab33 828 * ble.gap().setScanParams(...).
be_bryan 0:b74591d5ab33 829 */
be_bryan 0:b74591d5ab33 830 MBED_DEPRECATED("Use ble.gap().setScanParams(...)")
be_bryan 0:b74591d5ab33 831 ble_error_t setScanParams(uint16_t interval = GapScanningParams::SCAN_INTERVAL_MAX,
be_bryan 0:b74591d5ab33 832 uint16_t window = GapScanningParams::SCAN_WINDOW_MAX,
be_bryan 0:b74591d5ab33 833 uint16_t timeout = 0,
be_bryan 0:b74591d5ab33 834 bool activeScanning = false) {
be_bryan 0:b74591d5ab33 835 return gap().setScanParams(interval, window, timeout, activeScanning);
be_bryan 0:b74591d5ab33 836 }
be_bryan 0:b74591d5ab33 837
be_bryan 0:b74591d5ab33 838 /**
be_bryan 0:b74591d5ab33 839 * Set up the scanInterval parameter for GAP scanning (observer mode).
be_bryan 0:b74591d5ab33 840 * @param[in] interval
be_bryan 0:b74591d5ab33 841 * Scan interval (in milliseconds) [valid values lie between 2.5ms and 10.24s].
be_bryan 0:b74591d5ab33 842 *
be_bryan 0:b74591d5ab33 843 * The scanning window divided by the interval determines the duty cycle for
be_bryan 0:b74591d5ab33 844 * scanning. For example, if the interval is 100ms and the window is 10ms,
be_bryan 0:b74591d5ab33 845 * then the controller will scan for 10 percent of the time. It is possible
be_bryan 0:b74591d5ab33 846 * to have the interval and window set to the same value. In this case,
be_bryan 0:b74591d5ab33 847 * scanning is continuous, with a change of scanning frequency once every
be_bryan 0:b74591d5ab33 848 * interval.
be_bryan 0:b74591d5ab33 849 *
be_bryan 0:b74591d5ab33 850 * Once the scanning parameters have been configured, scanning can be
be_bryan 0:b74591d5ab33 851 * enabled by using startScan().
be_bryan 0:b74591d5ab33 852 *
be_bryan 0:b74591d5ab33 853 * @deprecated You should use the parallel API from Gap directly and refer to
be_bryan 0:b74591d5ab33 854 * Gap::setScanInterval(). A former call to
be_bryan 0:b74591d5ab33 855 * ble.setScanInterval(interval) should be replaced with
be_bryan 0:b74591d5ab33 856 * ble.gap().setScanInterval(interval).
be_bryan 0:b74591d5ab33 857 */
be_bryan 0:b74591d5ab33 858 MBED_DEPRECATED("Use ble.gap().setScanInterval(...)")
be_bryan 0:b74591d5ab33 859 ble_error_t setScanInterval(uint16_t interval) {
be_bryan 0:b74591d5ab33 860 return gap().setScanInterval(interval);
be_bryan 0:b74591d5ab33 861 }
be_bryan 0:b74591d5ab33 862
be_bryan 0:b74591d5ab33 863 /**
be_bryan 0:b74591d5ab33 864 * Set up the scanWindow parameter for GAP scanning (observer mode).
be_bryan 0:b74591d5ab33 865 * @param[in] window
be_bryan 0:b74591d5ab33 866 * Scan Window (in milliseconds) [valid values lie between 2.5ms and 10.24s].
be_bryan 0:b74591d5ab33 867 *
be_bryan 0:b74591d5ab33 868 * The scanning window divided by the interval determines the duty cycle for
be_bryan 0:b74591d5ab33 869 * scanning. For example, if the interval is 100ms and the window is 10ms,
be_bryan 0:b74591d5ab33 870 * then the controller will scan for 10 percent of the time. It is possible
be_bryan 0:b74591d5ab33 871 * to have the interval and window set to the same value. In this case,
be_bryan 0:b74591d5ab33 872 * scanning is continuous, with a change of scanning frequency once every
be_bryan 0:b74591d5ab33 873 * interval.
be_bryan 0:b74591d5ab33 874 *
be_bryan 0:b74591d5ab33 875 * Once the scanning parameters have been configured, scanning can be
be_bryan 0:b74591d5ab33 876 * enabled by using startScan().
be_bryan 0:b74591d5ab33 877 *
be_bryan 0:b74591d5ab33 878 * @deprecated You should use the parallel API from Gap directly and refer to
be_bryan 0:b74591d5ab33 879 * Gap::setScanWindow(). A former call to
be_bryan 0:b74591d5ab33 880 * ble.setScanWindow(window) should be replaced with
be_bryan 0:b74591d5ab33 881 * ble.gap().setScanWindow(window).
be_bryan 0:b74591d5ab33 882 */
be_bryan 0:b74591d5ab33 883 MBED_DEPRECATED("Use ble.gap().setScanWindow(...)")
be_bryan 0:b74591d5ab33 884 ble_error_t setScanWindow(uint16_t window) {
be_bryan 0:b74591d5ab33 885 return gap().setScanWindow(window);
be_bryan 0:b74591d5ab33 886 }
be_bryan 0:b74591d5ab33 887
be_bryan 0:b74591d5ab33 888 /**
be_bryan 0:b74591d5ab33 889 * Set up parameters for GAP scanning (observer mode).
be_bryan 0:b74591d5ab33 890 * @param[in] timeout
be_bryan 0:b74591d5ab33 891 * Scan timeout (in seconds) between 0x0001 and 0xFFFF; 0x0000 disables timeout.
be_bryan 0:b74591d5ab33 892 *
be_bryan 0:b74591d5ab33 893 * The scanning window divided by the interval determines the duty cycle for
be_bryan 0:b74591d5ab33 894 * scanning. For example, if the interval is 100ms and the window is 10ms,
be_bryan 0:b74591d5ab33 895 * then the controller will scan for 10 percent of the time. It is possible
be_bryan 0:b74591d5ab33 896 * to have the interval and window set to the same value. In this case,
be_bryan 0:b74591d5ab33 897 * scanning is continuous, with a change of scanning frequency once every
be_bryan 0:b74591d5ab33 898 * interval.
be_bryan 0:b74591d5ab33 899 *
be_bryan 0:b74591d5ab33 900 * Once the scanning parameters have been configured, scanning can be
be_bryan 0:b74591d5ab33 901 * enabled by using startScan().
be_bryan 0:b74591d5ab33 902 *
be_bryan 0:b74591d5ab33 903 * @note The scan interval and window are recommendations to the BLE stack.
be_bryan 0:b74591d5ab33 904 *
be_bryan 0:b74591d5ab33 905 * @deprecated You should use the parallel API from Gap directly and refer to
be_bryan 0:b74591d5ab33 906 * Gap::setScanTimeout(). A former call to
be_bryan 0:b74591d5ab33 907 * ble.setScanTimeout(...) should be replaced with
be_bryan 0:b74591d5ab33 908 * ble.gap().setScanTimeout(...).
be_bryan 0:b74591d5ab33 909 */
be_bryan 0:b74591d5ab33 910 MBED_DEPRECATED("Use ble.gap().setScanTimeout(...)")
be_bryan 0:b74591d5ab33 911 ble_error_t setScanTimeout(uint16_t timeout) {
be_bryan 0:b74591d5ab33 912 return gap().setScanTimeout(timeout);
be_bryan 0:b74591d5ab33 913 }
be_bryan 0:b74591d5ab33 914
be_bryan 0:b74591d5ab33 915 /**
be_bryan 0:b74591d5ab33 916 * Set up parameters for GAP scanning (observer mode).
be_bryan 0:b74591d5ab33 917 * @param[in] activeScanning
be_bryan 0:b74591d5ab33 918 * Set to True if active-scanning is required. This is used to fetch the
be_bryan 0:b74591d5ab33 919 * scan response from a peer if possible.
be_bryan 0:b74591d5ab33 920 *
be_bryan 0:b74591d5ab33 921 * Once the scanning parameters have been configured, scanning can be
be_bryan 0:b74591d5ab33 922 * enabled by using startScan().
be_bryan 0:b74591d5ab33 923 *
be_bryan 0:b74591d5ab33 924 * @deprecated You should use the parallel API from Gap directly, refer to
be_bryan 0:b74591d5ab33 925 * Gap::setActiveScan(). A former call to
be_bryan 0:b74591d5ab33 926 * ble.setActiveScan(...) should be replaced with
be_bryan 0:b74591d5ab33 927 * ble.gap().setActiveScanning(...).
be_bryan 0:b74591d5ab33 928 */
be_bryan 0:b74591d5ab33 929 MBED_DEPRECATED("Use ble.gap().setActiveScan(...)")
be_bryan 0:b74591d5ab33 930 void setActiveScan(bool activeScanning) {
be_bryan 0:b74591d5ab33 931 gap().setActiveScanning(activeScanning);
be_bryan 0:b74591d5ab33 932 }
be_bryan 0:b74591d5ab33 933
be_bryan 0:b74591d5ab33 934 /**
be_bryan 0:b74591d5ab33 935 * Start scanning (Observer Procedure) based on the parameters currently in
be_bryan 0:b74591d5ab33 936 * effect.
be_bryan 0:b74591d5ab33 937 *
be_bryan 0:b74591d5ab33 938 * @param[in] callback
be_bryan 0:b74591d5ab33 939 * The application-specific callback to be invoked upon
be_bryan 0:b74591d5ab33 940 * receiving every advertisement report. This can be passed in
be_bryan 0:b74591d5ab33 941 * as NULL, in which case scanning may not be enabled at all.
be_bryan 0:b74591d5ab33 942 *
be_bryan 0:b74591d5ab33 943 * @deprecated You should use the parallel API from Gap directly, refer to
be_bryan 0:b74591d5ab33 944 * Gap::startScan(). A former call to
be_bryan 0:b74591d5ab33 945 * ble.startScan(callback) should be replaced with
be_bryan 0:b74591d5ab33 946 * ble.gap().startScan(callback).
be_bryan 0:b74591d5ab33 947 */
be_bryan 0:b74591d5ab33 948 MBED_DEPRECATED("Use ble.gap().startScan(callback)")
be_bryan 0:b74591d5ab33 949 ble_error_t startScan(void (*callback)(const Gap::AdvertisementCallbackParams_t *params)) {
be_bryan 0:b74591d5ab33 950 return gap().startScan(callback);
be_bryan 0:b74591d5ab33 951 }
be_bryan 0:b74591d5ab33 952
be_bryan 0:b74591d5ab33 953 /**
be_bryan 0:b74591d5ab33 954 * Same as above, but this takes an (object, method) pair for a callback.
be_bryan 0:b74591d5ab33 955 *
be_bryan 0:b74591d5ab33 956 * @deprecated You should use the parallel API from Gap directly, refer to
be_bryan 0:b74591d5ab33 957 * Gap::startScan(). A former call to
be_bryan 0:b74591d5ab33 958 * ble.startScan(callback) should be replaced with
be_bryan 0:b74591d5ab33 959 * ble.gap().startScan(object, callback).
be_bryan 0:b74591d5ab33 960 */
be_bryan 0:b74591d5ab33 961 template<typename T>
be_bryan 0:b74591d5ab33 962 MBED_DEPRECATED("Use ble.gap().startScan(object, callback)")
be_bryan 0:b74591d5ab33 963 ble_error_t startScan(T *object, void (T::*memberCallback)(const Gap::AdvertisementCallbackParams_t *params));
be_bryan 0:b74591d5ab33 964
be_bryan 0:b74591d5ab33 965 /**
be_bryan 0:b74591d5ab33 966 * Stop scanning. The current scanning parameters remain in effect.
be_bryan 0:b74591d5ab33 967 *
be_bryan 0:b74591d5ab33 968 * @retval BLE_ERROR_NONE if successfully stopped scanning procedure.
be_bryan 0:b74591d5ab33 969 *
be_bryan 0:b74591d5ab33 970 * @deprecated You should use the parallel API from Gap directly and refer to
be_bryan 0:b74591d5ab33 971 * Gap::stopScan(). A former call to
be_bryan 0:b74591d5ab33 972 * ble.stopScan() should be replaced with
be_bryan 0:b74591d5ab33 973 * ble.gap().stopScan().
be_bryan 0:b74591d5ab33 974 */
be_bryan 0:b74591d5ab33 975 MBED_DEPRECATED("Use ble.gap().stopScan()")
be_bryan 0:b74591d5ab33 976 ble_error_t stopScan(void) {
be_bryan 0:b74591d5ab33 977 return gap().stopScan();
be_bryan 0:b74591d5ab33 978 }
be_bryan 0:b74591d5ab33 979
be_bryan 0:b74591d5ab33 980 /**
be_bryan 0:b74591d5ab33 981 * Create a connection (GAP Link Establishment).
be_bryan 0:b74591d5ab33 982 * @param peerAddr
be_bryan 0:b74591d5ab33 983 * 48-bit address, LSB format.
be_bryan 0:b74591d5ab33 984 * @param peerAddrType
be_bryan 0:b74591d5ab33 985 * Address type of the peer.
be_bryan 0:b74591d5ab33 986 * @param connectionParams
be_bryan 0:b74591d5ab33 987 * Connection parameters.
be_bryan 0:b74591d5ab33 988 * @param scanParams
be_bryan 0:b74591d5ab33 989 * Parameters to use while scanning for the peer.
be_bryan 0:b74591d5ab33 990 * @return BLE_ERROR_NONE if connection establishment procedure is started
be_bryan 0:b74591d5ab33 991 * successfully. The onConnection callback (if set) is invoked upon
be_bryan 0:b74591d5ab33 992 * a connection event.
be_bryan 0:b74591d5ab33 993 *
be_bryan 0:b74591d5ab33 994 * @deprecated You should use the parallel API from Gap directly and refer to
be_bryan 0:b74591d5ab33 995 * Gap::connect(). A former call to
be_bryan 0:b74591d5ab33 996 * ble.connect(...) should be replaced with
be_bryan 0:b74591d5ab33 997 * ble.gap().connect(...).
be_bryan 0:b74591d5ab33 998 */
be_bryan 0:b74591d5ab33 999 MBED_DEPRECATED("Use ble.gap().connect(...)")
be_bryan 0:b74591d5ab33 1000 ble_error_t connect(const BLEProtocol::AddressBytes_t peerAddr,
be_bryan 0:b74591d5ab33 1001 BLEProtocol::AddressType_t peerAddrType = BLEProtocol::AddressType::RANDOM_STATIC,
be_bryan 0:b74591d5ab33 1002 const Gap::ConnectionParams_t *connectionParams = NULL,
be_bryan 0:b74591d5ab33 1003 const GapScanningParams *scanParams = NULL) {
be_bryan 0:b74591d5ab33 1004 return gap().connect(peerAddr, peerAddrType, connectionParams, scanParams);
be_bryan 0:b74591d5ab33 1005 }
be_bryan 0:b74591d5ab33 1006
be_bryan 0:b74591d5ab33 1007 /**
be_bryan 0:b74591d5ab33 1008 * This call initiates the disconnection procedure, and its completion is
be_bryan 0:b74591d5ab33 1009 * communicated to the application with an invocation of the
be_bryan 0:b74591d5ab33 1010 * onDisconnection callback.
be_bryan 0:b74591d5ab33 1011 *
be_bryan 0:b74591d5ab33 1012 * @param[in] connectionHandle
be_bryan 0:b74591d5ab33 1013 * @param[in] reason
be_bryan 0:b74591d5ab33 1014 * The reason for disconnection; sent back to the peer.
be_bryan 0:b74591d5ab33 1015 */
be_bryan 0:b74591d5ab33 1016 MBED_DEPRECATED("Use ble.gap().disconnect(...)")
be_bryan 0:b74591d5ab33 1017 ble_error_t disconnect(Gap::Handle_t connectionHandle, Gap::DisconnectionReason_t reason) {
be_bryan 0:b74591d5ab33 1018 return gap().disconnect(connectionHandle, reason);
be_bryan 0:b74591d5ab33 1019 }
be_bryan 0:b74591d5ab33 1020
be_bryan 0:b74591d5ab33 1021 /**
be_bryan 0:b74591d5ab33 1022 * This call initiates the disconnection procedure, and its completion
be_bryan 0:b74591d5ab33 1023 * is communicated to the application with an invocation of the
be_bryan 0:b74591d5ab33 1024 * onDisconnection callback.
be_bryan 0:b74591d5ab33 1025 *
be_bryan 0:b74591d5ab33 1026 * @param reason
be_bryan 0:b74591d5ab33 1027 * The reason for disconnection; sent back to the peer.
be_bryan 0:b74591d5ab33 1028 *
be_bryan 0:b74591d5ab33 1029 * @deprecated You should use the parallel API from Gap directly and refer to
be_bryan 0:b74591d5ab33 1030 * Gap::disconnect(). A former call to
be_bryan 0:b74591d5ab33 1031 * ble.disconnect(reason) should be replaced with
be_bryan 0:b74591d5ab33 1032 * ble.gap().disconnect(reason).
be_bryan 0:b74591d5ab33 1033 *
be_bryan 0:b74591d5ab33 1034 * @note This version of disconnect() doesn't take a connection handle. It
be_bryan 0:b74591d5ab33 1035 * works reliably only for stacks that are limited to a single
be_bryan 0:b74591d5ab33 1036 * connection.
be_bryan 0:b74591d5ab33 1037 */
be_bryan 0:b74591d5ab33 1038 MBED_DEPRECATED("Use ble.gap().disconnect(...)")
be_bryan 0:b74591d5ab33 1039 ble_error_t disconnect(Gap::DisconnectionReason_t reason) {
be_bryan 0:b74591d5ab33 1040 return gap().disconnect(reason);
be_bryan 0:b74591d5ab33 1041 }
be_bryan 0:b74591d5ab33 1042
be_bryan 0:b74591d5ab33 1043 /**
be_bryan 0:b74591d5ab33 1044 * Returns the current Gap state of the device using a bitmask that
be_bryan 0:b74591d5ab33 1045 * describes whether the device is advertising or connected.
be_bryan 0:b74591d5ab33 1046 *
be_bryan 0:b74591d5ab33 1047 * @deprecated You should use the parallel API from Gap directly and refer to
be_bryan 0:b74591d5ab33 1048 * Gap::getState(). A former call to
be_bryan 0:b74591d5ab33 1049 * ble.getGapState() should be replaced with
be_bryan 0:b74591d5ab33 1050 * ble.gap().getState().
be_bryan 0:b74591d5ab33 1051 */
be_bryan 0:b74591d5ab33 1052 MBED_DEPRECATED("Use ble.gap().getGapState(...)")
be_bryan 0:b74591d5ab33 1053 Gap::GapState_t getGapState(void) const {
be_bryan 0:b74591d5ab33 1054 return gap().getState();
be_bryan 0:b74591d5ab33 1055 }
be_bryan 0:b74591d5ab33 1056
be_bryan 0:b74591d5ab33 1057 /**
be_bryan 0:b74591d5ab33 1058 * Get the GAP peripheral's preferred connection parameters. These are the
be_bryan 0:b74591d5ab33 1059 * defaults that the peripheral would like to have in a connection. The
be_bryan 0:b74591d5ab33 1060 * choice of the connection parameters is eventually up to the central.
be_bryan 0:b74591d5ab33 1061 *
be_bryan 0:b74591d5ab33 1062 * @param[out] params
be_bryan 0:b74591d5ab33 1063 * The structure where the parameters will be stored. The caller owns memory
be_bryan 0:b74591d5ab33 1064 * for this.
be_bryan 0:b74591d5ab33 1065 *
be_bryan 0:b74591d5ab33 1066 * @return BLE_ERROR_NONE if the parameters were successfully filled into
be_bryan 0:b74591d5ab33 1067 * the given structure pointed to by params.
be_bryan 0:b74591d5ab33 1068 *
be_bryan 0:b74591d5ab33 1069 * @deprecated You should use the parallel API from Gap directly and refer to
be_bryan 0:b74591d5ab33 1070 * Gap::getPreferredConnectionParams(). A former call to
be_bryan 0:b74591d5ab33 1071 * ble.getPreferredConnectionParams() should be replaced with
be_bryan 0:b74591d5ab33 1072 * ble.gap().getPreferredConnectionParams().
be_bryan 0:b74591d5ab33 1073 */
be_bryan 0:b74591d5ab33 1074 MBED_DEPRECATED("Use ble.gap().getPreferredConnectionParams(...)")
be_bryan 0:b74591d5ab33 1075 ble_error_t getPreferredConnectionParams(Gap::ConnectionParams_t *params) {
be_bryan 0:b74591d5ab33 1076 return gap().getPreferredConnectionParams(params);
be_bryan 0:b74591d5ab33 1077 }
be_bryan 0:b74591d5ab33 1078
be_bryan 0:b74591d5ab33 1079 /**
be_bryan 0:b74591d5ab33 1080 * Set the GAP peripheral's preferred connection parameters. These are the
be_bryan 0:b74591d5ab33 1081 * defaults that the peripheral would like to have in a connection. The
be_bryan 0:b74591d5ab33 1082 * choice of the connection parameters is eventually up to the central.
be_bryan 0:b74591d5ab33 1083 *
be_bryan 0:b74591d5ab33 1084 * @param[in] params
be_bryan 0:b74591d5ab33 1085 * The structure containing the desired parameters.
be_bryan 0:b74591d5ab33 1086 *
be_bryan 0:b74591d5ab33 1087 * @deprecated You should use the parallel API from Gap directly and refer to
be_bryan 0:b74591d5ab33 1088 * Gap::setPreferredConnectionParams(). A former call to
be_bryan 0:b74591d5ab33 1089 * ble.setPreferredConnectionParams() should be replaced with
be_bryan 0:b74591d5ab33 1090 * ble.gap().setPreferredConnectionParams().
be_bryan 0:b74591d5ab33 1091 */
be_bryan 0:b74591d5ab33 1092 MBED_DEPRECATED("Use ble.gap().setPreferredConnectionParams(...)")
be_bryan 0:b74591d5ab33 1093 ble_error_t setPreferredConnectionParams(const Gap::ConnectionParams_t *params) {
be_bryan 0:b74591d5ab33 1094 return gap().setPreferredConnectionParams(params);
be_bryan 0:b74591d5ab33 1095 }
be_bryan 0:b74591d5ab33 1096
be_bryan 0:b74591d5ab33 1097 /**
be_bryan 0:b74591d5ab33 1098 * Update connection parameters while in the peripheral role.
be_bryan 0:b74591d5ab33 1099 * @details In the peripheral role, this will send the corresponding L2CAP request to the connected peer and wait for
be_bryan 0:b74591d5ab33 1100 * the central to perform the procedure.
be_bryan 0:b74591d5ab33 1101 * @param[in] handle
be_bryan 0:b74591d5ab33 1102 * Connection Handle
be_bryan 0:b74591d5ab33 1103 * @param[in] params
be_bryan 0:b74591d5ab33 1104 * Pointer to desired connection parameters. If NULL is provided on a peripheral role,
be_bryan 0:b74591d5ab33 1105 * the parameters in the PPCP characteristic of the GAP service will be used instead.
be_bryan 0:b74591d5ab33 1106 *
be_bryan 0:b74591d5ab33 1107 * @deprecated You should use the parallel API from Gap directly and refer to
be_bryan 0:b74591d5ab33 1108 * Gap::updateConnectionParams(). A former call to
be_bryan 0:b74591d5ab33 1109 * ble.updateConnectionParams() should be replaced with
be_bryan 0:b74591d5ab33 1110 * ble.gap().updateConnectionParams().
be_bryan 0:b74591d5ab33 1111 */
be_bryan 0:b74591d5ab33 1112 MBED_DEPRECATED("Use ble.gap().updateConnectionParams(...)")
be_bryan 0:b74591d5ab33 1113 ble_error_t updateConnectionParams(Gap::Handle_t handle, const Gap::ConnectionParams_t *params) {
be_bryan 0:b74591d5ab33 1114 return gap().updateConnectionParams(handle, params);
be_bryan 0:b74591d5ab33 1115 }
be_bryan 0:b74591d5ab33 1116
be_bryan 0:b74591d5ab33 1117 /**
be_bryan 0:b74591d5ab33 1118 * Set the device name characteristic in the Gap service.
be_bryan 0:b74591d5ab33 1119 * @param[in] deviceName
be_bryan 0:b74591d5ab33 1120 * The new value for the device-name. This is a UTF-8 encoded, <b>NULL-terminated</b> string.
be_bryan 0:b74591d5ab33 1121 *
be_bryan 0:b74591d5ab33 1122 * @deprecated You should use the parallel API from Gap directly and refer to
be_bryan 0:b74591d5ab33 1123 * Gap::setDeviceName(). A former call to
be_bryan 0:b74591d5ab33 1124 * ble.setDeviceName() should be replaced with
be_bryan 0:b74591d5ab33 1125 * ble.gap().setDeviceName().
be_bryan 0:b74591d5ab33 1126 */
be_bryan 0:b74591d5ab33 1127 MBED_DEPRECATED("Use ble.gap().setDeviceName(...)")
be_bryan 0:b74591d5ab33 1128 ble_error_t setDeviceName(const uint8_t *deviceName) {
be_bryan 0:b74591d5ab33 1129 return gap().setDeviceName(deviceName);
be_bryan 0:b74591d5ab33 1130 }
be_bryan 0:b74591d5ab33 1131
be_bryan 0:b74591d5ab33 1132 /**
be_bryan 0:b74591d5ab33 1133 * Get the value of the device name characteristic in the Gap service.
be_bryan 0:b74591d5ab33 1134 * @param[out] deviceName
be_bryan 0:b74591d5ab33 1135 * Pointer to an empty buffer where the UTF-8 *non NULL-
be_bryan 0:b74591d5ab33 1136 * terminated* string will be placed. Set this
be_bryan 0:b74591d5ab33 1137 * value to NULL to obtain the deviceName-length
be_bryan 0:b74591d5ab33 1138 * from the 'length' parameter.
be_bryan 0:b74591d5ab33 1139 *
be_bryan 0:b74591d5ab33 1140 * @param[in,out] lengthP
be_bryan 0:b74591d5ab33 1141 * (on input) Length of the buffer pointed to by deviceName;
be_bryan 0:b74591d5ab33 1142 * (on output) the complete device name length (without the
be_bryan 0:b74591d5ab33 1143 * null terminator).
be_bryan 0:b74591d5ab33 1144 *
be_bryan 0:b74591d5ab33 1145 * @note If the device name is longer than the size of the supplied buffer,
be_bryan 0:b74591d5ab33 1146 * the length will return the complete device name length and not the
be_bryan 0:b74591d5ab33 1147 * number of bytes actually returned in deviceName. The application may
be_bryan 0:b74591d5ab33 1148 * use this information to retry with a suitable buffer size.
be_bryan 0:b74591d5ab33 1149 *
be_bryan 0:b74591d5ab33 1150 * @deprecated You should use the parallel API from Gap directly and refer to
be_bryan 0:b74591d5ab33 1151 * Gap::getDeviceName(). A former call to
be_bryan 0:b74591d5ab33 1152 * ble.getDeviceName() should be replaced with
be_bryan 0:b74591d5ab33 1153 * ble.gap().getDeviceName().
be_bryan 0:b74591d5ab33 1154 */
be_bryan 0:b74591d5ab33 1155 MBED_DEPRECATED("Use ble.gap().getDeviceName(...)")
be_bryan 0:b74591d5ab33 1156 ble_error_t getDeviceName(uint8_t *deviceName, unsigned *lengthP) {
be_bryan 0:b74591d5ab33 1157 return gap().getDeviceName(deviceName, lengthP);
be_bryan 0:b74591d5ab33 1158 }
be_bryan 0:b74591d5ab33 1159
be_bryan 0:b74591d5ab33 1160 /**
be_bryan 0:b74591d5ab33 1161 * Set the appearance characteristic in the Gap service.
be_bryan 0:b74591d5ab33 1162 * @param[in] appearance
be_bryan 0:b74591d5ab33 1163 * The new value for the device-appearance.
be_bryan 0:b74591d5ab33 1164 *
be_bryan 0:b74591d5ab33 1165 * @deprecated You should use the parallel API from Gap directly and refer to
be_bryan 0:b74591d5ab33 1166 * Gap::setAppearance(). A former call to
be_bryan 0:b74591d5ab33 1167 * ble.setAppearance() should be replaced with
be_bryan 0:b74591d5ab33 1168 * ble.gap().setAppearance().
be_bryan 0:b74591d5ab33 1169 */
be_bryan 0:b74591d5ab33 1170 MBED_DEPRECATED("Use ble.gap().setAppearance(...)")
be_bryan 0:b74591d5ab33 1171 ble_error_t setAppearance(GapAdvertisingData::Appearance appearance) {
be_bryan 0:b74591d5ab33 1172 return gap().setAppearance(appearance);
be_bryan 0:b74591d5ab33 1173 }
be_bryan 0:b74591d5ab33 1174
be_bryan 0:b74591d5ab33 1175 /**
be_bryan 0:b74591d5ab33 1176 * Get the appearance characteristic in the Gap service.
be_bryan 0:b74591d5ab33 1177 * @param[out] appearanceP
be_bryan 0:b74591d5ab33 1178 * The new value for the device-appearance.
be_bryan 0:b74591d5ab33 1179 *
be_bryan 0:b74591d5ab33 1180 * @deprecated You should use the parallel API from Gap directly, refer to
be_bryan 0:b74591d5ab33 1181 * Gap::getAppearance(). A former call to
be_bryan 0:b74591d5ab33 1182 * ble.getAppearance() should be replaced with
be_bryan 0:b74591d5ab33 1183 * ble.gap().getAppearance().
be_bryan 0:b74591d5ab33 1184 */
be_bryan 0:b74591d5ab33 1185 MBED_DEPRECATED("Use ble.gap().getAppearance(...)")
be_bryan 0:b74591d5ab33 1186 ble_error_t getAppearance(GapAdvertisingData::Appearance *appearanceP) {
be_bryan 0:b74591d5ab33 1187 return gap().getAppearance(appearanceP);
be_bryan 0:b74591d5ab33 1188 }
be_bryan 0:b74591d5ab33 1189
be_bryan 0:b74591d5ab33 1190 /**
be_bryan 0:b74591d5ab33 1191 * Set the radio's transmit power.
be_bryan 0:b74591d5ab33 1192 * @param[in] txPower Radio transmit power in dBm.
be_bryan 0:b74591d5ab33 1193 *
be_bryan 0:b74591d5ab33 1194 * @deprecated You should use the parallel API from Gap directly and refer to
be_bryan 0:b74591d5ab33 1195 * Gap::setTxPower(). A former call to
be_bryan 0:b74591d5ab33 1196 * ble.setTxPower() should be replaced with
be_bryan 0:b74591d5ab33 1197 * ble.gap().setTxPower().
be_bryan 0:b74591d5ab33 1198 */
be_bryan 0:b74591d5ab33 1199 MBED_DEPRECATED("Use ble.gap().setTxPower(...)")
be_bryan 0:b74591d5ab33 1200 ble_error_t setTxPower(int8_t txPower) {
be_bryan 0:b74591d5ab33 1201 return gap().setTxPower(txPower);
be_bryan 0:b74591d5ab33 1202 }
be_bryan 0:b74591d5ab33 1203
be_bryan 0:b74591d5ab33 1204 /**
be_bryan 0:b74591d5ab33 1205 * Query the underlying stack for permitted arguments for setTxPower().
be_bryan 0:b74591d5ab33 1206 *
be_bryan 0:b74591d5ab33 1207 * @param[out] valueArrayPP
be_bryan 0:b74591d5ab33 1208 * Out parameter to receive the immutable array of Tx values.
be_bryan 0:b74591d5ab33 1209 * @param[out] countP
be_bryan 0:b74591d5ab33 1210 * Out parameter to receive the array's size.
be_bryan 0:b74591d5ab33 1211 *
be_bryan 0:b74591d5ab33 1212 * @deprecated You should use the parallel API from Gap directly, refer to
be_bryan 0:b74591d5ab33 1213 * Gap::getPermittedTxPowerValues(). A former call to
be_bryan 0:b74591d5ab33 1214 * ble.getPermittedTxPowerValues() should be replaced with
be_bryan 0:b74591d5ab33 1215 * ble.gap().getPermittedTxPowerValues().
be_bryan 0:b74591d5ab33 1216 */
be_bryan 0:b74591d5ab33 1217 MBED_DEPRECATED("Use ble.gap().getPermittedTxPowerValues(...)")
be_bryan 0:b74591d5ab33 1218 void getPermittedTxPowerValues(const int8_t **valueArrayPP, size_t *countP) {
be_bryan 0:b74591d5ab33 1219 gap().getPermittedTxPowerValues(valueArrayPP, countP);
be_bryan 0:b74591d5ab33 1220 }
be_bryan 0:b74591d5ab33 1221
be_bryan 0:b74591d5ab33 1222 /**
be_bryan 0:b74591d5ab33 1223 * Add a service declaration to the local server ATT table. Also add the
be_bryan 0:b74591d5ab33 1224 * characteristics contained within.
be_bryan 0:b74591d5ab33 1225 *
be_bryan 0:b74591d5ab33 1226 * @deprecated You should use the parallel API from GattServer directly, refer to
be_bryan 0:b74591d5ab33 1227 * GattServer::addService(). A former call
be_bryan 0:b74591d5ab33 1228 * to ble.addService() should be replaced with
be_bryan 0:b74591d5ab33 1229 * ble.gattServer().addService().
be_bryan 0:b74591d5ab33 1230 */
be_bryan 0:b74591d5ab33 1231 MBED_DEPRECATED("Use ble.gattServer().addService(...)")
be_bryan 0:b74591d5ab33 1232 ble_error_t addService(GattService &service) {
be_bryan 0:b74591d5ab33 1233 return gattServer().addService(service);
be_bryan 0:b74591d5ab33 1234 }
be_bryan 0:b74591d5ab33 1235
be_bryan 0:b74591d5ab33 1236 /**
be_bryan 0:b74591d5ab33 1237 * Read the value of a characteristic from the local GattServer.
be_bryan 0:b74591d5ab33 1238 * @param[in] attributeHandle
be_bryan 0:b74591d5ab33 1239 * Attribute handle for the value attribute of the characteristic.
be_bryan 0:b74591d5ab33 1240 * @param[out] buffer
be_bryan 0:b74591d5ab33 1241 * A buffer to hold the value being read.
be_bryan 0:b74591d5ab33 1242 * @param[in,out] lengthP
be_bryan 0:b74591d5ab33 1243 * Length of the buffer being supplied. If the attribute
be_bryan 0:b74591d5ab33 1244 * value is longer than the size of the supplied buffer,
be_bryan 0:b74591d5ab33 1245 * this variable will return the total attribute value length
be_bryan 0:b74591d5ab33 1246 * (excluding offset). The application may use this
be_bryan 0:b74591d5ab33 1247 * information to allocate a suitable buffer size.
be_bryan 0:b74591d5ab33 1248 *
be_bryan 0:b74591d5ab33 1249 * @return BLE_ERROR_NONE if a value was read successfully into the buffer.
be_bryan 0:b74591d5ab33 1250 *
be_bryan 0:b74591d5ab33 1251 * @deprecated You should use the parallel API from GattServer directly,
be_bryan 0:b74591d5ab33 1252 * GattServer::read(GattAttribute::Handle_t,uint8_t,uint16_t). A former call
be_bryan 0:b74591d5ab33 1253 * to ble.readCharacteristicValue() should be replaced with
be_bryan 0:b74591d5ab33 1254 * ble.gattServer().read().
be_bryan 0:b74591d5ab33 1255 */
be_bryan 0:b74591d5ab33 1256 MBED_DEPRECATED("Use ble.gattServer().read(...)")
be_bryan 0:b74591d5ab33 1257 ble_error_t readCharacteristicValue(GattAttribute::Handle_t attributeHandle, uint8_t *buffer, uint16_t *lengthP) {
be_bryan 0:b74591d5ab33 1258 return gattServer().read(attributeHandle, buffer, lengthP);
be_bryan 0:b74591d5ab33 1259 }
be_bryan 0:b74591d5ab33 1260
be_bryan 0:b74591d5ab33 1261 /**
be_bryan 0:b74591d5ab33 1262 * Read the value of a characteristic from the local GattServer.
be_bryan 0:b74591d5ab33 1263 * @param[in] connectionHandle
be_bryan 0:b74591d5ab33 1264 * Connection Handle.
be_bryan 0:b74591d5ab33 1265 * @param[in] attributeHandle
be_bryan 0:b74591d5ab33 1266 * Attribute handle for the value attribute of the characteristic.
be_bryan 0:b74591d5ab33 1267 * @param[out] buffer
be_bryan 0:b74591d5ab33 1268 * A buffer to hold the value being read.
be_bryan 0:b74591d5ab33 1269 * @param[in,out] lengthP
be_bryan 0:b74591d5ab33 1270 * Length of the buffer being supplied. If the attribute
be_bryan 0:b74591d5ab33 1271 * value is longer than the size of the supplied buffer,
be_bryan 0:b74591d5ab33 1272 * this variable will return the total attribute value length
be_bryan 0:b74591d5ab33 1273 * (excluding offset). The application may use this
be_bryan 0:b74591d5ab33 1274 * information to allocate a suitable buffer size.
be_bryan 0:b74591d5ab33 1275 *
be_bryan 0:b74591d5ab33 1276 * @return BLE_ERROR_NONE if a value was read successfully into the buffer.
be_bryan 0:b74591d5ab33 1277 *
be_bryan 0:b74591d5ab33 1278 * @note This API is a version of the above, with an additional connection handle
be_bryan 0:b74591d5ab33 1279 * parameter to allow fetches for connection-specific multivalued
be_bryan 0:b74591d5ab33 1280 * attributes (such as the CCCDs).
be_bryan 0:b74591d5ab33 1281 *
be_bryan 0:b74591d5ab33 1282 * @deprecated You should use the parallel API from GattServer directly, refer to
be_bryan 0:b74591d5ab33 1283 * GattServer::read(Gap::Handle_t,GattAttribute::Handle_t,uint8_t,uint16_t).
be_bryan 0:b74591d5ab33 1284 * A former call to ble.readCharacteristicValue() should be replaced with
be_bryan 0:b74591d5ab33 1285 * ble.gattServer().read().
be_bryan 0:b74591d5ab33 1286 */
be_bryan 0:b74591d5ab33 1287 MBED_DEPRECATED("Use ble.gattServer().read(...)")
be_bryan 0:b74591d5ab33 1288 ble_error_t readCharacteristicValue(Gap::Handle_t connectionHandle, GattAttribute::Handle_t attributeHandle, uint8_t *buffer, uint16_t *lengthP) {
be_bryan 0:b74591d5ab33 1289 return gattServer().read(connectionHandle, attributeHandle, buffer, lengthP);
be_bryan 0:b74591d5ab33 1290 }
be_bryan 0:b74591d5ab33 1291
be_bryan 0:b74591d5ab33 1292 /**
be_bryan 0:b74591d5ab33 1293 * Update the value of a characteristic on the local GattServer.
be_bryan 0:b74591d5ab33 1294 *
be_bryan 0:b74591d5ab33 1295 * @param[in] attributeHandle
be_bryan 0:b74591d5ab33 1296 * Handle for the value attribute of the characteristic.
be_bryan 0:b74591d5ab33 1297 * @param[in] value
be_bryan 0:b74591d5ab33 1298 * A pointer to a buffer holding the new value.
be_bryan 0:b74591d5ab33 1299 * @param[in] size
be_bryan 0:b74591d5ab33 1300 * Size of the new value (in bytes).
be_bryan 0:b74591d5ab33 1301 * @param[in] localOnly
be_bryan 0:b74591d5ab33 1302 * Should this update be kept on the local
be_bryan 0:b74591d5ab33 1303 * GattServer regardless of the state of the
be_bryan 0:b74591d5ab33 1304 * notify/indicate flag in the CCCD for this
be_bryan 0:b74591d5ab33 1305 * characteristic? If set to true, no notification
be_bryan 0:b74591d5ab33 1306 * or indication is generated.
be_bryan 0:b74591d5ab33 1307 *
be_bryan 0:b74591d5ab33 1308 * @return BLE_ERROR_NONE if we have successfully set the value of the attribute.
be_bryan 0:b74591d5ab33 1309 *
be_bryan 0:b74591d5ab33 1310 * @deprecated You should use the parallel API from GattServer directly and refer to
be_bryan 0:b74591d5ab33 1311 * GattServer::write(GattAttribute::Handle_t,const uint8_t,uint16_t,bool).
be_bryan 0:b74591d5ab33 1312 * A former call to ble.updateCharacteristicValue() should be replaced with
be_bryan 0:b74591d5ab33 1313 * ble.gattServer().write().
be_bryan 0:b74591d5ab33 1314 */
be_bryan 0:b74591d5ab33 1315 MBED_DEPRECATED("Use ble.gattServer().write(...)")
be_bryan 0:b74591d5ab33 1316 ble_error_t updateCharacteristicValue(GattAttribute::Handle_t attributeHandle,
be_bryan 0:b74591d5ab33 1317 const uint8_t *value,
be_bryan 0:b74591d5ab33 1318 uint16_t size,
be_bryan 0:b74591d5ab33 1319 bool localOnly = false) {
be_bryan 0:b74591d5ab33 1320 return gattServer().write(attributeHandle, value, size, localOnly);
be_bryan 0:b74591d5ab33 1321 }
be_bryan 0:b74591d5ab33 1322
be_bryan 0:b74591d5ab33 1323 /**
be_bryan 0:b74591d5ab33 1324 * Update the value of a characteristic on the local GattServer. A version
be_bryan 0:b74591d5ab33 1325 * of the above, with a connection handle parameter to allow updates
be_bryan 0:b74591d5ab33 1326 * for connection-specific multivalued attributes (such as the CCCDs).
be_bryan 0:b74591d5ab33 1327 *
be_bryan 0:b74591d5ab33 1328 * @param[in] connectionHandle
be_bryan 0:b74591d5ab33 1329 * Connection Handle.
be_bryan 0:b74591d5ab33 1330 * @param[in] attributeHandle
be_bryan 0:b74591d5ab33 1331 * Handle for the value attribute of the Characteristic.
be_bryan 0:b74591d5ab33 1332 * @param[in] value
be_bryan 0:b74591d5ab33 1333 * A pointer to a buffer holding the new value.
be_bryan 0:b74591d5ab33 1334 * @param[in] size
be_bryan 0:b74591d5ab33 1335 * Size of the new value (in bytes).
be_bryan 0:b74591d5ab33 1336 * @param[in] localOnly
be_bryan 0:b74591d5ab33 1337 * Should this update be kept on the local
be_bryan 0:b74591d5ab33 1338 * GattServer regardless of the state of the
be_bryan 0:b74591d5ab33 1339 * notify/indicate flag in the CCCD for this
be_bryan 0:b74591d5ab33 1340 * Characteristic? If set to true, no notification
be_bryan 0:b74591d5ab33 1341 * or indication is generated.
be_bryan 0:b74591d5ab33 1342 *
be_bryan 0:b74591d5ab33 1343 * @return BLE_ERROR_NONE if we have successfully set the value of the attribute.
be_bryan 0:b74591d5ab33 1344 *
be_bryan 0:b74591d5ab33 1345 * @deprecated You should use the parallel API from GattServer directly and refer to
be_bryan 0:b74591d5ab33 1346 * GattServer::write(Gap::Handle_t,GattAttribute::Handle_t,const uint8_t,uint16_t,bool).
be_bryan 0:b74591d5ab33 1347 * A former call to ble.updateCharacteristicValue() should be replaced with
be_bryan 0:b74591d5ab33 1348 * ble.gattServer().write().
be_bryan 0:b74591d5ab33 1349 */
be_bryan 0:b74591d5ab33 1350 MBED_DEPRECATED("Use ble.gattServer().write(...)")
be_bryan 0:b74591d5ab33 1351 ble_error_t updateCharacteristicValue(Gap::Handle_t connectionHandle,
be_bryan 0:b74591d5ab33 1352 GattAttribute::Handle_t attributeHandle,
be_bryan 0:b74591d5ab33 1353 const uint8_t *value,
be_bryan 0:b74591d5ab33 1354 uint16_t size,
be_bryan 0:b74591d5ab33 1355 bool localOnly = false) {
be_bryan 0:b74591d5ab33 1356 return gattServer().write(connectionHandle, attributeHandle, value, size, localOnly);
be_bryan 0:b74591d5ab33 1357 }
be_bryan 0:b74591d5ab33 1358
be_bryan 0:b74591d5ab33 1359 /**
be_bryan 0:b74591d5ab33 1360 * Enable the BLE stack's Security Manager. The Security Manager implements
be_bryan 0:b74591d5ab33 1361 * the cryptographic algorithms and protocol exchanges that allow two
be_bryan 0:b74591d5ab33 1362 * devices to securely exchange data and privately detect each other.
be_bryan 0:b74591d5ab33 1363 * Calling this API is a prerequisite for encryption and pairing (bonding).
be_bryan 0:b74591d5ab33 1364 *
be_bryan 0:b74591d5ab33 1365 * @param[in] enableBonding Allow for bonding.
be_bryan 0:b74591d5ab33 1366 * @param[in] requireMITM Require protection against man-in-the-middle attacks.
be_bryan 0:b74591d5ab33 1367 * @param[in] iocaps To specify the I/O capabilities of this peripheral,
be_bryan 0:b74591d5ab33 1368 * such as availability of a display or keyboard, to
be_bryan 0:b74591d5ab33 1369 * support out-of-band exchanges of security data.
be_bryan 0:b74591d5ab33 1370 * @param[in] passkey To specify a static passkey.
be_bryan 0:b74591d5ab33 1371 *
be_bryan 0:b74591d5ab33 1372 * @return BLE_ERROR_NONE on success.
be_bryan 0:b74591d5ab33 1373 *
be_bryan 0:b74591d5ab33 1374 * @deprecated You should use the parallel API from SecurityManager directly, refer to
be_bryan 0:b74591d5ab33 1375 * SecurityManager.init(). A former
be_bryan 0:b74591d5ab33 1376 * call to ble.initializeSecurity(...) should be replaced with
be_bryan 0:b74591d5ab33 1377 * ble.securityManager().init(...).
be_bryan 0:b74591d5ab33 1378 */
be_bryan 0:b74591d5ab33 1379 MBED_DEPRECATED("Use ble.gattServer().write(...)")
be_bryan 0:b74591d5ab33 1380 ble_error_t initializeSecurity(bool enableBonding = true,
be_bryan 0:b74591d5ab33 1381 bool requireMITM = true,
be_bryan 0:b74591d5ab33 1382 SecurityManager::SecurityIOCapabilities_t iocaps = SecurityManager::IO_CAPS_NONE,
be_bryan 0:b74591d5ab33 1383 const SecurityManager::Passkey_t passkey = NULL) {
be_bryan 0:b74591d5ab33 1384 return securityManager().init(enableBonding, requireMITM, iocaps, passkey);
be_bryan 0:b74591d5ab33 1385 }
be_bryan 0:b74591d5ab33 1386
be_bryan 0:b74591d5ab33 1387 /**
be_bryan 0:b74591d5ab33 1388 * Get the security status of a connection.
be_bryan 0:b74591d5ab33 1389 *
be_bryan 0:b74591d5ab33 1390 * @param[in] connectionHandle Handle to identify the connection.
be_bryan 0:b74591d5ab33 1391 * @param[out] securityStatusP Security status.
be_bryan 0:b74591d5ab33 1392 *
be_bryan 0:b74591d5ab33 1393 * @return BLE_SUCCESS or appropriate error code indicating the reason of failure.
be_bryan 0:b74591d5ab33 1394 *
be_bryan 0:b74591d5ab33 1395 * @deprecated You should use the parallel API from SecurityManager directly, refer to
be_bryan 0:b74591d5ab33 1396 * SecurityManager::getLinkSecurity(). A former
be_bryan 0:b74591d5ab33 1397 * call to ble.getLinkSecurity(...) should be replaced with
be_bryan 0:b74591d5ab33 1398 * ble.securityManager().getLinkSecurity(...).
be_bryan 0:b74591d5ab33 1399 */
be_bryan 0:b74591d5ab33 1400 MBED_DEPRECATED("ble.securityManager().getLinkSecurity(...)")
be_bryan 0:b74591d5ab33 1401 ble_error_t getLinkSecurity(Gap::Handle_t connectionHandle, SecurityManager::LinkSecurityStatus_t *securityStatusP) {
be_bryan 0:b74591d5ab33 1402 return securityManager().getLinkSecurity(connectionHandle, securityStatusP);
be_bryan 0:b74591d5ab33 1403 }
be_bryan 0:b74591d5ab33 1404
be_bryan 0:b74591d5ab33 1405 /**
be_bryan 0:b74591d5ab33 1406 * Delete all peer device context and all related bonding information from
be_bryan 0:b74591d5ab33 1407 * the database within the security manager.
be_bryan 0:b74591d5ab33 1408 *
be_bryan 0:b74591d5ab33 1409 * @retval BLE_ERROR_NONE On success; else returns an error code indicating the reason for the failure.
be_bryan 0:b74591d5ab33 1410 * @retval BLE_ERROR_INVALID_STATE If the API is called without module initialization or
be_bryan 0:b74591d5ab33 1411 * application registration.
be_bryan 0:b74591d5ab33 1412 *
be_bryan 0:b74591d5ab33 1413 * @deprecated You should use the parallel API from SecurityManager directly and refer to
be_bryan 0:b74591d5ab33 1414 * SecurityManager::purgeAllBondingState(). A former
be_bryan 0:b74591d5ab33 1415 * call to ble.purgeAllBondingState() should be replaced with
be_bryan 0:b74591d5ab33 1416 * ble.securityManager().purgeAllBondingState().
be_bryan 0:b74591d5ab33 1417 */
be_bryan 0:b74591d5ab33 1418 MBED_DEPRECATED("ble.securityManager().purgeAllBondingState(...)")
be_bryan 0:b74591d5ab33 1419 ble_error_t purgeAllBondingState(void) {
be_bryan 0:b74591d5ab33 1420 return securityManager().purgeAllBondingState();
be_bryan 0:b74591d5ab33 1421 }
be_bryan 0:b74591d5ab33 1422
be_bryan 0:b74591d5ab33 1423 /**
be_bryan 0:b74591d5ab33 1424 * Set up a callback for timeout events. Refer to Gap::TimeoutSource_t for
be_bryan 0:b74591d5ab33 1425 * possible event types.
be_bryan 0:b74591d5ab33 1426 *
be_bryan 0:b74591d5ab33 1427 * @deprecated You should use the parallel API from Gap directly and refer to
be_bryan 0:b74591d5ab33 1428 * Gap::onTimeout(). A former call
be_bryan 0:b74591d5ab33 1429 * to ble.onTimeout(callback) should be replaced with
be_bryan 0:b74591d5ab33 1430 * ble.gap().onTimeout(callback).
be_bryan 0:b74591d5ab33 1431 */
be_bryan 0:b74591d5ab33 1432 MBED_DEPRECATED("ble.gap().onTimeout(callback)")
be_bryan 0:b74591d5ab33 1433 void onTimeout(Gap::TimeoutEventCallback_t timeoutCallback) {
be_bryan 0:b74591d5ab33 1434 gap().onTimeout(timeoutCallback);
be_bryan 0:b74591d5ab33 1435 }
be_bryan 0:b74591d5ab33 1436
be_bryan 0:b74591d5ab33 1437 /**
be_bryan 0:b74591d5ab33 1438 * Set up a callback for connection events. Refer to Gap::ConnectionEventCallback_t.
be_bryan 0:b74591d5ab33 1439 *
be_bryan 0:b74591d5ab33 1440 * @deprecated You should use the parallel API from Gap directly, refer to
be_bryan 0:b74591d5ab33 1441 * Gap::onConnection(). A former call
be_bryan 0:b74591d5ab33 1442 * to ble.onConnection(callback) should be replaced with
be_bryan 0:b74591d5ab33 1443 * ble.gap().onConnection(callback).
be_bryan 0:b74591d5ab33 1444 */
be_bryan 0:b74591d5ab33 1445 MBED_DEPRECATED("ble.gap().onConnection(callback)")
be_bryan 0:b74591d5ab33 1446 void onConnection(Gap::ConnectionEventCallback_t connectionCallback) {
be_bryan 0:b74591d5ab33 1447 gap().onConnection(connectionCallback);
be_bryan 0:b74591d5ab33 1448 }
be_bryan 0:b74591d5ab33 1449
be_bryan 0:b74591d5ab33 1450 /**
be_bryan 0:b74591d5ab33 1451 * Append to a chain of callbacks to be invoked upon GAP disconnection.
be_bryan 0:b74591d5ab33 1452 *
be_bryan 0:b74591d5ab33 1453 * @deprecated You should use the parallel API from Gap directly and refer to
be_bryan 0:b74591d5ab33 1454 * Gap::onDisconnection(). A former call
be_bryan 0:b74591d5ab33 1455 * to ble.onDisconnection(callback) should be replaced with
be_bryan 0:b74591d5ab33 1456 * ble.gap().onDisconnection(callback).
be_bryan 0:b74591d5ab33 1457 */
be_bryan 0:b74591d5ab33 1458 MBED_DEPRECATED("ble.gap().onDisconnection(callback)")
be_bryan 0:b74591d5ab33 1459 void onDisconnection(Gap::DisconnectionEventCallback_t disconnectionCallback) {
be_bryan 0:b74591d5ab33 1460 gap().onDisconnection(disconnectionCallback);
be_bryan 0:b74591d5ab33 1461 }
be_bryan 0:b74591d5ab33 1462
be_bryan 0:b74591d5ab33 1463 /**
be_bryan 0:b74591d5ab33 1464 * The same as onDisconnection() but allows an object reference and member function
be_bryan 0:b74591d5ab33 1465 * to be added to the chain of callbacks.
be_bryan 0:b74591d5ab33 1466 *
be_bryan 0:b74591d5ab33 1467 * @deprecated You should use the parallel API from Gap directly and refer to
be_bryan 0:b74591d5ab33 1468 * Gap::onDisconnection(). A former call
be_bryan 0:b74591d5ab33 1469 * to ble.onDisconnection(callback) should be replaced with
be_bryan 0:b74591d5ab33 1470 * ble.gap().onDisconnection(callback).
be_bryan 0:b74591d5ab33 1471 */
be_bryan 0:b74591d5ab33 1472 template<typename T>
be_bryan 0:b74591d5ab33 1473 MBED_DEPRECATED("ble.gap().onDisconnection(callback)")
be_bryan 0:b74591d5ab33 1474 void onDisconnection(T *tptr, void (T::*mptr)(const Gap::DisconnectionCallbackParams_t*)) {
be_bryan 0:b74591d5ab33 1475 gap().onDisconnection(tptr, mptr);
be_bryan 0:b74591d5ab33 1476 }
be_bryan 0:b74591d5ab33 1477
be_bryan 0:b74591d5ab33 1478 /**
be_bryan 0:b74591d5ab33 1479 * Radio Notification is a feature that enables ACTIVE and INACTIVE
be_bryan 0:b74591d5ab33 1480 * (nACTIVE) signals from the stack. These notify the application when the
be_bryan 0:b74591d5ab33 1481 * radio is in use. The signal is sent using software interrupt.
be_bryan 0:b74591d5ab33 1482 *
be_bryan 0:b74591d5ab33 1483 * The ACTIVE signal is sent before the radio event starts. The nACTIVE
be_bryan 0:b74591d5ab33 1484 * signal is sent at the end of the radio event. These signals can be used
be_bryan 0:b74591d5ab33 1485 * by the application programmer to synchronize application logic with radio
be_bryan 0:b74591d5ab33 1486 * activity. For example, the ACTIVE signal can be used to shut off external
be_bryan 0:b74591d5ab33 1487 * devices to manage peak current drawn during periods when the radio is on,
be_bryan 0:b74591d5ab33 1488 * or to trigger sensor data collection for transmission in the radio event.
be_bryan 0:b74591d5ab33 1489 *
be_bryan 0:b74591d5ab33 1490 * @param callback
be_bryan 0:b74591d5ab33 1491 * The application handler to be invoked in response to a radio
be_bryan 0:b74591d5ab33 1492 * ACTIVE/INACTIVE event.
be_bryan 0:b74591d5ab33 1493 *
be_bryan 0:b74591d5ab33 1494 * @deprecated You should use the parallel API from Gap directly, refer to
be_bryan 0:b74591d5ab33 1495 * Gap::onRadioNotification(). A former call
be_bryan 0:b74591d5ab33 1496 * to ble.onRadioNotification(...) should be replaced with
be_bryan 0:b74591d5ab33 1497 * ble.gap().onRadioNotification(...).
be_bryan 0:b74591d5ab33 1498 */
be_bryan 0:b74591d5ab33 1499 MBED_DEPRECATED("ble.gap().onRadioNotification(...)")
be_bryan 0:b74591d5ab33 1500 void onRadioNotification(void (*callback)(bool)) {
be_bryan 0:b74591d5ab33 1501 gap().onRadioNotification(callback);
be_bryan 0:b74591d5ab33 1502 }
be_bryan 0:b74591d5ab33 1503
be_bryan 0:b74591d5ab33 1504 /**
be_bryan 0:b74591d5ab33 1505 * Add a callback for the GATT event DATA_SENT (which is triggered when
be_bryan 0:b74591d5ab33 1506 * updates are sent out by GATT in the form of notifications).
be_bryan 0:b74591d5ab33 1507 *
be_bryan 0:b74591d5ab33 1508 * @note It is possible to chain together multiple onDataSent callbacks
be_bryan 0:b74591d5ab33 1509 * (potentially from different modules of an application) to receive updates
be_bryan 0:b74591d5ab33 1510 * to characteristics.
be_bryan 0:b74591d5ab33 1511 *
be_bryan 0:b74591d5ab33 1512 * @note It is also possible to set up a callback into a member function of
be_bryan 0:b74591d5ab33 1513 * some object.
be_bryan 0:b74591d5ab33 1514 *
be_bryan 0:b74591d5ab33 1515 * @deprecated You should use the parallel API from GattServer directly and refer to
be_bryan 0:b74591d5ab33 1516 * GattServer::onDataSent(). A former call
be_bryan 0:b74591d5ab33 1517 * to ble.onDataSent(...) should be replaced with
be_bryan 0:b74591d5ab33 1518 * ble.gattServer().onDataSent(...).
be_bryan 0:b74591d5ab33 1519 */
be_bryan 0:b74591d5ab33 1520 MBED_DEPRECATED("ble.gattServer().onDataSent(...)")
be_bryan 0:b74591d5ab33 1521 void onDataSent(void (*callback)(unsigned count)) {
be_bryan 0:b74591d5ab33 1522 gattServer().onDataSent(callback);
be_bryan 0:b74591d5ab33 1523 }
be_bryan 0:b74591d5ab33 1524
be_bryan 0:b74591d5ab33 1525 /**
be_bryan 0:b74591d5ab33 1526 * The same as onDataSent() but allows an object reference and member function
be_bryan 0:b74591d5ab33 1527 * to be added to the chain of callbacks.
be_bryan 0:b74591d5ab33 1528 *
be_bryan 0:b74591d5ab33 1529 * @deprecated You should use the parallel API from GattServer directly and refer to
be_bryan 0:b74591d5ab33 1530 * GattServer::onDataSent(). A former call
be_bryan 0:b74591d5ab33 1531 * to ble.onDataSent(...) should be replaced with
be_bryan 0:b74591d5ab33 1532 * ble.gattServer().onDataSent(...).
be_bryan 0:b74591d5ab33 1533 */
be_bryan 0:b74591d5ab33 1534 template <typename T>
be_bryan 0:b74591d5ab33 1535 MBED_DEPRECATED("ble.gattServer().onDataSent(...)")
be_bryan 0:b74591d5ab33 1536 void onDataSent(T * objPtr, void (T::*memberPtr)(unsigned count)) {
be_bryan 0:b74591d5ab33 1537 gattServer().onDataSent(objPtr, memberPtr);
be_bryan 0:b74591d5ab33 1538 }
be_bryan 0:b74591d5ab33 1539
be_bryan 0:b74591d5ab33 1540 /**
be_bryan 0:b74591d5ab33 1541 * Set up a callback for when an attribute has its value updated by or at the
be_bryan 0:b74591d5ab33 1542 * connected peer. For a peripheral, this callback is triggered when the local
be_bryan 0:b74591d5ab33 1543 * GATT server has an attribute updated by a write command from the peer.
be_bryan 0:b74591d5ab33 1544 * For a Central, this callback is triggered when a response is received for
be_bryan 0:b74591d5ab33 1545 * a write request.
be_bryan 0:b74591d5ab33 1546 *
be_bryan 0:b74591d5ab33 1547 * @note It is possible to chain together multiple onDataWritten callbacks
be_bryan 0:b74591d5ab33 1548 * (potentially from different modules of an application) to receive updates
be_bryan 0:b74591d5ab33 1549 * to characteristics. Many services, such as DFU and UART, add their own
be_bryan 0:b74591d5ab33 1550 * onDataWritten callbacks behind the scenes to trap interesting events.
be_bryan 0:b74591d5ab33 1551 *
be_bryan 0:b74591d5ab33 1552 * @note It is also possible to set up a callback into a member function of
be_bryan 0:b74591d5ab33 1553 * some object.
be_bryan 0:b74591d5ab33 1554 *
be_bryan 0:b74591d5ab33 1555 * @deprecated You should use the parallel API from GattServer directly and refer to
be_bryan 0:b74591d5ab33 1556 * GattServer::onDataWritten(). A former call
be_bryan 0:b74591d5ab33 1557 * to ble.onDataWritten(...) should be replaced with
be_bryan 0:b74591d5ab33 1558 * ble.gattServer().onDataWritten(...).
be_bryan 0:b74591d5ab33 1559 */
be_bryan 0:b74591d5ab33 1560 MBED_DEPRECATED("ble.gattServer().onDataWritten(...)")
be_bryan 0:b74591d5ab33 1561 void onDataWritten(void (*callback)(const GattWriteCallbackParams *eventDataP)) {
be_bryan 0:b74591d5ab33 1562 gattServer().onDataWritten(callback);
be_bryan 0:b74591d5ab33 1563 }
be_bryan 0:b74591d5ab33 1564
be_bryan 0:b74591d5ab33 1565 /**
be_bryan 0:b74591d5ab33 1566 * The same as onDataWritten() but allows an object reference and member function
be_bryan 0:b74591d5ab33 1567 * to be added to the chain of callbacks.
be_bryan 0:b74591d5ab33 1568 *
be_bryan 0:b74591d5ab33 1569 * @deprecated You should use the parallel API from GattServer directly, refer to
be_bryan 0:b74591d5ab33 1570 * GattServer::onDataWritten(). A former call
be_bryan 0:b74591d5ab33 1571 * to ble.onDataWritten(...) should be replaced with
be_bryan 0:b74591d5ab33 1572 * ble.gattServer().onDataWritten(...).
be_bryan 0:b74591d5ab33 1573 */
be_bryan 0:b74591d5ab33 1574 template <typename T>
be_bryan 0:b74591d5ab33 1575 MBED_DEPRECATED("ble.gattServer().onDataWritten(...)")
be_bryan 0:b74591d5ab33 1576 void onDataWritten(T * objPtr, void (T::*memberPtr)(const GattWriteCallbackParams *context)) {
be_bryan 0:b74591d5ab33 1577 gattServer().onDataWritten(objPtr, memberPtr);
be_bryan 0:b74591d5ab33 1578 }
be_bryan 0:b74591d5ab33 1579
be_bryan 0:b74591d5ab33 1580 /**
be_bryan 0:b74591d5ab33 1581 * Set up a callback to be invoked on the peripheral when an attribute is
be_bryan 0:b74591d5ab33 1582 * being read by a remote client.
be_bryan 0:b74591d5ab33 1583 *
be_bryan 0:b74591d5ab33 1584 * @note This functionality may not be available on all underlying stacks.
be_bryan 0:b74591d5ab33 1585 * You could use GattCharacteristic::setReadAuthorizationCallback() as an
be_bryan 0:b74591d5ab33 1586 * alternative.
be_bryan 0:b74591d5ab33 1587 *
be_bryan 0:b74591d5ab33 1588 * @note It is possible to chain together multiple onDataRead callbacks
be_bryan 0:b74591d5ab33 1589 * (potentially from different modules of an application) to receive updates
be_bryan 0:b74591d5ab33 1590 * to characteristics. Services may add their own onDataRead callbacks
be_bryan 0:b74591d5ab33 1591 * behind the scenes to trap interesting events.
be_bryan 0:b74591d5ab33 1592 *
be_bryan 0:b74591d5ab33 1593 * @note It is also possible to set up a callback into a member function of
be_bryan 0:b74591d5ab33 1594 * some object.
be_bryan 0:b74591d5ab33 1595 *
be_bryan 0:b74591d5ab33 1596 * @return BLE_ERROR_NOT_IMPLEMENTED if this functionality isn't available;
be_bryan 0:b74591d5ab33 1597 * else BLE_ERROR_NONE.
be_bryan 0:b74591d5ab33 1598 *
be_bryan 0:b74591d5ab33 1599 * @deprecated You should use the parallel API from GattServer directly and refer to
be_bryan 0:b74591d5ab33 1600 * GattServer::onDataRead(). A former call
be_bryan 0:b74591d5ab33 1601 * to ble.onDataRead(...) should be replaced with
be_bryan 0:b74591d5ab33 1602 * ble.gattServer().onDataRead(...).
be_bryan 0:b74591d5ab33 1603 */
be_bryan 0:b74591d5ab33 1604 MBED_DEPRECATED("ble.gattServer().onDataRead(...)")
be_bryan 0:b74591d5ab33 1605 ble_error_t onDataRead(void (*callback)(const GattReadCallbackParams *eventDataP)) {
be_bryan 0:b74591d5ab33 1606 return gattServer().onDataRead(callback);
be_bryan 0:b74591d5ab33 1607 }
be_bryan 0:b74591d5ab33 1608
be_bryan 0:b74591d5ab33 1609 /**
be_bryan 0:b74591d5ab33 1610 * The same as onDataRead() but allows an object reference and member function
be_bryan 0:b74591d5ab33 1611 * to be added to the chain of callbacks.
be_bryan 0:b74591d5ab33 1612 *
be_bryan 0:b74591d5ab33 1613 * @deprecated You should use the parallel API from GattServer directly and refer to
be_bryan 0:b74591d5ab33 1614 * GattServer::onDataRead(). A former call
be_bryan 0:b74591d5ab33 1615 * to ble.onDataRead(...) should be replaced with
be_bryan 0:b74591d5ab33 1616 * ble.gattServer().onDataRead(...).
be_bryan 0:b74591d5ab33 1617 */
be_bryan 0:b74591d5ab33 1618 template <typename T>
be_bryan 0:b74591d5ab33 1619 MBED_DEPRECATED("ble.gattServer().onDataRead(...)")
be_bryan 0:b74591d5ab33 1620 ble_error_t onDataRead(T * objPtr, void (T::*memberPtr)(const GattReadCallbackParams *context)) {
be_bryan 0:b74591d5ab33 1621 return gattServer().onDataRead(objPtr, memberPtr);
be_bryan 0:b74591d5ab33 1622 }
be_bryan 0:b74591d5ab33 1623
be_bryan 0:b74591d5ab33 1624 /**
be_bryan 0:b74591d5ab33 1625 * Set up a callback for when notifications or indications are enabled for a
be_bryan 0:b74591d5ab33 1626 * characteristic on the local GattServer.
be_bryan 0:b74591d5ab33 1627 *
be_bryan 0:b74591d5ab33 1628 * @deprecated You should use the parallel API from GattServer directly and refer to
be_bryan 0:b74591d5ab33 1629 * GattServer::onUpdatesEnabled(). A former call
be_bryan 0:b74591d5ab33 1630 * to ble.onUpdatesEnabled(callback) should be replaced with
be_bryan 0:b74591d5ab33 1631 * ble.gattServer().onUpdatesEnabled(callback).
be_bryan 0:b74591d5ab33 1632 */
be_bryan 0:b74591d5ab33 1633 MBED_DEPRECATED("ble.gattServer().onUpdatesEnabled(...)")
be_bryan 0:b74591d5ab33 1634 void onUpdatesEnabled(GattServer::EventCallback_t callback) {
be_bryan 0:b74591d5ab33 1635 gattServer().onUpdatesEnabled(callback);
be_bryan 0:b74591d5ab33 1636 }
be_bryan 0:b74591d5ab33 1637
be_bryan 0:b74591d5ab33 1638 /**
be_bryan 0:b74591d5ab33 1639 * Set up a callback for when notifications or indications are disabled for a
be_bryan 0:b74591d5ab33 1640 * characteristic on the local GattServer.
be_bryan 0:b74591d5ab33 1641 *
be_bryan 0:b74591d5ab33 1642 * @deprecated You should use the parallel API from GattServer directly and refer to
be_bryan 0:b74591d5ab33 1643 * GattServer::onUpdatesDisabled(). A former call
be_bryan 0:b74591d5ab33 1644 * to ble.onUpdatesDisabled(callback) should be replaced with
be_bryan 0:b74591d5ab33 1645 * ble.gattServer().onUpdatesDisabled(callback).
be_bryan 0:b74591d5ab33 1646 */
be_bryan 0:b74591d5ab33 1647 MBED_DEPRECATED("ble.gattServer().onUpdatesDisabled(...)")
be_bryan 0:b74591d5ab33 1648 void onUpdatesDisabled(GattServer::EventCallback_t callback) {
be_bryan 0:b74591d5ab33 1649 gattServer().onUpdatesDisabled(callback);
be_bryan 0:b74591d5ab33 1650 }
be_bryan 0:b74591d5ab33 1651
be_bryan 0:b74591d5ab33 1652 /**
be_bryan 0:b74591d5ab33 1653 * Set up a callback for when the GATT server receives a response for an
be_bryan 0:b74591d5ab33 1654 * indication event sent previously.
be_bryan 0:b74591d5ab33 1655 *
be_bryan 0:b74591d5ab33 1656 * @deprecated You should use the parallel API from GattServer directly and refer to
be_bryan 0:b74591d5ab33 1657 * GattServer::onConfirmationReceived(). A former call
be_bryan 0:b74591d5ab33 1658 * to ble.onConfirmationReceived(callback) should be replaced with
be_bryan 0:b74591d5ab33 1659 * ble.gattServer().onConfirmationReceived(callback).
be_bryan 0:b74591d5ab33 1660 */
be_bryan 0:b74591d5ab33 1661 MBED_DEPRECATED("ble.gattServer().onConfirmationReceived(...)")
be_bryan 0:b74591d5ab33 1662 void onConfirmationReceived(GattServer::EventCallback_t callback) {
be_bryan 0:b74591d5ab33 1663 gattServer().onConfirmationReceived(callback);
be_bryan 0:b74591d5ab33 1664 }
be_bryan 0:b74591d5ab33 1665
be_bryan 0:b74591d5ab33 1666 /**
be_bryan 0:b74591d5ab33 1667 * Set up a callback for when the security setup procedure (key generation
be_bryan 0:b74591d5ab33 1668 * and exchange) for a link has started. This will be skipped for bonded
be_bryan 0:b74591d5ab33 1669 * devices. The callback is passed in parameters received from the peer's
be_bryan 0:b74591d5ab33 1670 * security request: bool allowBonding, bool requireMITM and
be_bryan 0:b74591d5ab33 1671 * SecurityIOCapabilities_t.
be_bryan 0:b74591d5ab33 1672 *
be_bryan 0:b74591d5ab33 1673 * @deprecated You should use the parallel API from SecurityManager directly and refer to
be_bryan 0:b74591d5ab33 1674 * SecurityManager::onSecuritySetupInitiated(). A former
be_bryan 0:b74591d5ab33 1675 * call to ble.onSecuritySetupInitiated(callback) should be replaced with
be_bryan 0:b74591d5ab33 1676 * ble.securityManager().onSecuritySetupInitiated(callback).
be_bryan 0:b74591d5ab33 1677 */
be_bryan 0:b74591d5ab33 1678 MBED_DEPRECATED("ble.securityManager().onSecuritySetupInitiated(callback)")
be_bryan 0:b74591d5ab33 1679 void onSecuritySetupInitiated(SecurityManager::SecuritySetupInitiatedCallback_t callback) {
be_bryan 0:b74591d5ab33 1680 securityManager().onSecuritySetupInitiated(callback);
be_bryan 0:b74591d5ab33 1681 }
be_bryan 0:b74591d5ab33 1682
be_bryan 0:b74591d5ab33 1683 /**
be_bryan 0:b74591d5ab33 1684 * Set up a callback for when the security setup procedure (key generation
be_bryan 0:b74591d5ab33 1685 * and exchange) for a link has completed. This will be skipped for bonded
be_bryan 0:b74591d5ab33 1686 * devices. The callback is passed in the success/failure status of the
be_bryan 0:b74591d5ab33 1687 * security setup procedure.
be_bryan 0:b74591d5ab33 1688 *
be_bryan 0:b74591d5ab33 1689 * @deprecated You should use the parallel API from SecurityManager directly and refer to
be_bryan 0:b74591d5ab33 1690 * SecurityManager::onSecuritySetupCompleted(). A former
be_bryan 0:b74591d5ab33 1691 * call to ble.onSecuritySetupCompleted(callback) should be replaced with
be_bryan 0:b74591d5ab33 1692 * ble.securityManager().onSecuritySetupCompleted(callback).
be_bryan 0:b74591d5ab33 1693 */
be_bryan 0:b74591d5ab33 1694 MBED_DEPRECATED("ble.securityManager().onSecuritySetupCompleted(callback)")
be_bryan 0:b74591d5ab33 1695 void onSecuritySetupCompleted(SecurityManager::SecuritySetupCompletedCallback_t callback) {
be_bryan 0:b74591d5ab33 1696 securityManager().onSecuritySetupCompleted(callback);
be_bryan 0:b74591d5ab33 1697 }
be_bryan 0:b74591d5ab33 1698
be_bryan 0:b74591d5ab33 1699 /**
be_bryan 0:b74591d5ab33 1700 * Set up a callback for when a link with the peer is secured. For bonded
be_bryan 0:b74591d5ab33 1701 * devices, subsequent reconnections with a bonded peer will result only in
be_bryan 0:b74591d5ab33 1702 * this callback when the link is secured, and setup procedures will not
be_bryan 0:b74591d5ab33 1703 * occur unless the bonding information is either lost or deleted on either
be_bryan 0:b74591d5ab33 1704 * or both sides. The callback is passed in a SecurityManager::SecurityMode_t according
be_bryan 0:b74591d5ab33 1705 * to the level of security in effect for the secured link.
be_bryan 0:b74591d5ab33 1706 *
be_bryan 0:b74591d5ab33 1707 * @deprecated You should use the parallel API from SecurityManager directly and refer to
be_bryan 0:b74591d5ab33 1708 * SecurityManager::onLinkSecured(). A former
be_bryan 0:b74591d5ab33 1709 * call to ble.onLinkSecured(callback) should be replaced with
be_bryan 0:b74591d5ab33 1710 * ble.securityManager().onLinkSecured(callback).
be_bryan 0:b74591d5ab33 1711 */
be_bryan 0:b74591d5ab33 1712 MBED_DEPRECATED("ble.securityManager().onLinkSecured(callback)")
be_bryan 0:b74591d5ab33 1713 void onLinkSecured(SecurityManager::LinkSecuredCallback_t callback) {
be_bryan 0:b74591d5ab33 1714 securityManager().onLinkSecured(callback);
be_bryan 0:b74591d5ab33 1715 }
be_bryan 0:b74591d5ab33 1716
be_bryan 0:b74591d5ab33 1717 /**
be_bryan 0:b74591d5ab33 1718 * Set up a callback for successful bonding, meaning that link-specific security
be_bryan 0:b74591d5ab33 1719 * context is stored persistently for a peer device.
be_bryan 0:b74591d5ab33 1720 *
be_bryan 0:b74591d5ab33 1721 * @deprecated You should use the parallel API from SecurityManager directly and refer to
be_bryan 0:b74591d5ab33 1722 * SecurityManager::onSecurityContextStored(). A former
be_bryan 0:b74591d5ab33 1723 * call to ble.onSecurityContextStored(callback) should be replaced with
be_bryan 0:b74591d5ab33 1724 * ble.securityManager().onSecurityContextStored(callback).
be_bryan 0:b74591d5ab33 1725 */
be_bryan 0:b74591d5ab33 1726 MBED_DEPRECATED("ble.securityManager().onSecurityContextStored(callback)")
be_bryan 0:b74591d5ab33 1727 void onSecurityContextStored(SecurityManager::HandleSpecificEvent_t callback) {
be_bryan 0:b74591d5ab33 1728 securityManager().onSecurityContextStored(callback);
be_bryan 0:b74591d5ab33 1729 }
be_bryan 0:b74591d5ab33 1730
be_bryan 0:b74591d5ab33 1731 /**
be_bryan 0:b74591d5ab33 1732 * Set up a callback for when the passkey needs to be displayed on a
be_bryan 0:b74591d5ab33 1733 * peripheral with DISPLAY capability. This happens when security is
be_bryan 0:b74591d5ab33 1734 * configured to prevent man-in-the-middle attacks, and the peers need to exchange
be_bryan 0:b74591d5ab33 1735 * a passkey (or PIN) to authenticate the connection
be_bryan 0:b74591d5ab33 1736 * attempt.
be_bryan 0:b74591d5ab33 1737 *
be_bryan 0:b74591d5ab33 1738 * @deprecated You should use the parallel API from SecurityManager directly and refer to
be_bryan 0:b74591d5ab33 1739 * SecurityManager::onPasskeyDisplay(). A former
be_bryan 0:b74591d5ab33 1740 * call to ble.onPasskeyDisplay(callback) should be replaced with
be_bryan 0:b74591d5ab33 1741 * ble.securityManager().onPasskeyDisplay(callback).
be_bryan 0:b74591d5ab33 1742 */
be_bryan 0:b74591d5ab33 1743 MBED_DEPRECATED("ble.securityManager().onPasskeyDisplay(callback)")
be_bryan 0:b74591d5ab33 1744 void onPasskeyDisplay(SecurityManager::PasskeyDisplayCallback_t callback) {
be_bryan 0:b74591d5ab33 1745 return securityManager().onPasskeyDisplay(callback);
be_bryan 0:b74591d5ab33 1746 }
be_bryan 0:b74591d5ab33 1747
be_bryan 0:b74591d5ab33 1748 private:
be_bryan 0:b74591d5ab33 1749 friend class BLEInstanceBase;
be_bryan 0:b74591d5ab33 1750
be_bryan 0:b74591d5ab33 1751 /**
be_bryan 0:b74591d5ab33 1752 * This function allows the BLE stack to signal that there is work to do and
be_bryan 0:b74591d5ab33 1753 * event processing should be done (BLE::processEvent()).
be_bryan 0:b74591d5ab33 1754 *
be_bryan 0:b74591d5ab33 1755 * @note This function should be called by the port of BLE_API. It is not
be_bryan 0:b74591d5ab33 1756 * meant to be used by end users.
be_bryan 0:b74591d5ab33 1757 */
be_bryan 0:b74591d5ab33 1758 void signalEventsToProcess();
be_bryan 0:b74591d5ab33 1759
be_bryan 0:b74591d5ab33 1760 /**
be_bryan 0:b74591d5ab33 1761 * Implementation of init() [internal to BLE_API].
be_bryan 0:b74591d5ab33 1762 *
be_bryan 0:b74591d5ab33 1763 * The implementation is separated into a private method because it isn't
be_bryan 0:b74591d5ab33 1764 * suitable to be included in the header.
be_bryan 0:b74591d5ab33 1765 */
be_bryan 0:b74591d5ab33 1766 ble_error_t initImplementation(
be_bryan 0:b74591d5ab33 1767 FunctionPointerWithContext<InitializationCompleteCallbackContext *> callback
be_bryan 0:b74591d5ab33 1768 );
be_bryan 0:b74591d5ab33 1769
be_bryan 0:b74591d5ab33 1770 private:
be_bryan 0:b74591d5ab33 1771 // Prevent copy construction and copy assignment of BLE.
be_bryan 0:b74591d5ab33 1772 BLE(const BLE&);
be_bryan 0:b74591d5ab33 1773 BLE &operator=(const BLE &);
be_bryan 0:b74591d5ab33 1774
be_bryan 0:b74591d5ab33 1775 private:
be_bryan 0:b74591d5ab33 1776 InstanceID_t instanceID;
be_bryan 0:b74591d5ab33 1777 BLEInstanceBase *transport; /* The device-specific backend */
be_bryan 0:b74591d5ab33 1778 OnEventsToProcessCallback_t whenEventsToProcess;
be_bryan 0:b74591d5ab33 1779 bool event_signaled;
be_bryan 0:b74591d5ab33 1780 };
be_bryan 0:b74591d5ab33 1781
be_bryan 0:b74591d5ab33 1782 /**
be_bryan 0:b74591d5ab33 1783 * @deprecated This type alias is retained for the sake of compatibility with
be_bryan 0:b74591d5ab33 1784 * older code. This will be dropped at some point.
be_bryan 0:b74591d5ab33 1785 */
be_bryan 0:b74591d5ab33 1786 typedef BLE BLEDevice;
be_bryan 0:b74591d5ab33 1787
be_bryan 0:b74591d5ab33 1788 /**
be_bryan 0:b74591d5ab33 1789 * @namespace ble Entry namespace for all %BLE API definitions.
be_bryan 0:b74591d5ab33 1790 */
be_bryan 0:b74591d5ab33 1791
be_bryan 0:b74591d5ab33 1792 /**
be_bryan 0:b74591d5ab33 1793 * @}
be_bryan 0:b74591d5ab33 1794 */
be_bryan 0:b74591d5ab33 1795
be_bryan 0:b74591d5ab33 1796 #endif /* ifndef MBED_BLE_H__ */