BLE.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2006-2013 ARM Limited
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 #ifndef MBED_BLE_H__
00018 #define MBED_BLE_H__
00019 
00020 #include "BLERoles.h"
00021 
00022 #include "blecommon.h"
00023 #include "ble/Gap.h"
00024 #include "ble/GattServer.h"
00025 #include "ble/GattClient.h"
00026 #include "ble/SecurityManager.h"
00027 
00028 #include "ble/FunctionPointerWithContext.h "
00029 
00030 #ifdef YOTTA_CFG_MBED_OS
00031 #include "mbed-drivers/mbed_error.h"
00032 #else
00033 
00034 #include "platform/mbed_error.h"
00035 
00036 #endif
00037 
00038 #include "platform/mbed_toolchain.h"
00039 
00040 /* Forward declaration for the implementation class */
00041 class BLEInstanceBase;
00042 
00043 /**
00044  * @addtogroup ble
00045  * @{
00046  */
00047 
00048 /**
00049  * Abstract away BLE-capable radio transceivers or SOCs.
00050  *
00051  * Instances of this class have three responsibilities:
00052  *   - Initialize the inner BLE subsystem.
00053  *   - Signal user code that BLE events are available and an API to process them.
00054  *   - Manage access to the instances abstracting each BLE layer:
00055  *        + GAP: Handle advertising and scan, as well as connection and
00056  *          disconnection.
00057  *        + GATTServer: API to construct and manage a GATT server, which connected peers can
00058  *          access.
00059  *        + GATTClient: API to interact with a peer GATT server.
00060  *        + SecurityManager: API to manage security.
00061  *
00062  * The user should not create BLE instances directly but rather access to the
00063  * singleton(s) holding the BLE interfaces present in the system by using the
00064  * static function Instance().
00065  *
00066  * @code
00067  * #include "ble/BLE.h"
00068  *
00069  * BLE& ble_interface = BLE::Instance();
00070  * @endcode
00071  *
00072  * Next, the signal handling/process mechanism should be set up. By design,
00073  * Mbed BLE does not impose to the user an event handling/processing mechanism;
00074  * however, it exposes APIs, which allows an application to compose its own:
00075  *   - onEventsToProcess(), which registers a callback that
00076  *     the BLE subsystem will call when there is an event ready to be processed.
00077  *   - processEvents(), which processes all the events present in the BLE subsystem.
00078  *
00079  * It is common to bind BLE event mechanism with Mbed EventQueue:
00080  *
00081  * @code
00082  * #include <events/mbed_events.h>
00083  * #include "ble/BLE.h"
00084  *
00085  * // declare the event queue, which the whole application will share.
00086  * static EventQueue event_queue(4 * EVENTS_EVENT_SIZE);
00087  *
00088  * // Function invoked when there is a BLE event available.
00089  * // Event processing is put into the event queue.
00090  * void schedule_ble_processing(BLE::OnEventsToProcessCallbackContext* context) {
00091  *   event_queue.call(callback(&(context->ble), &BLE::processEvents));
00092  * }
00093  *
00094  * int main()
00095  * {
00096  *   BLE &ble_interface = BLE::Instance();
00097  *
00098  *   // Bind event signaling to schedule_ble_processing
00099  *   ble_interface.onEventsToProcess(schedule_ble_processing);
00100  *
00101  *   // Launch BLE initialisation
00102  *
00103  *   // Dispatch events in the event queue
00104  *   event_queue.dispatch_forever();
00105  *   return 0;
00106  * }
00107  * @endcode
00108  *
00109  * Once the event processing mechanism is in place, the Bluetooth subsystem can
00110  * be initialized with the init() function. That function accepts in input a
00111  * callback, which will be invoked once the initialization process has finished.
00112  *
00113  * @code
00114  * void on_ble_init_complete(BLE::InitializationCompleteCallbackContext *context)
00115  * {
00116  *   BLE& ble_interface = context->ble;
00117  *   ble_error_t initialization_error = context->error;
00118  *
00119  *   if (initialization_error) {
00120  *     // handle error
00121  *     return;
00122  *   }
00123  *
00124  *   // The BLE interface can be accessed now.
00125  * }
00126  *
00127  * int main() {
00128  *   BLE &ble_interface = BLE::Instance();
00129  *   ble_interface.onEventsToProcess(schedule_ble_processing);
00130  *
00131  *   // Initialize the BLE interface
00132  *   ble_interface.init(on_ble_init_complete);
00133  *
00134  *   event_queue.dispatch_forever();
00135  *   return 0;
00136  * }
00137  * @endcode
00138  */
00139 class BLE {
00140 public:
00141     /**
00142      * Opaque type used to store the ID of a BLE instance.
00143      */
00144     typedef unsigned InstanceID_t;
00145 
00146     /**
00147      * The value of the BLE::InstanceID_t for the default BLE instance.
00148      */
00149     static const InstanceID_t DEFAULT_INSTANCE = 0;
00150 
00151 #ifndef YOTTA_CFG_BLE_INSTANCES_COUNT
00152     /**
00153      * The number of permitted BLE instances for the application.
00154      */
00155     static const InstanceID_t NUM_INSTANCES = 1;
00156 #else
00157     /**
00158      * The number of permitted BLE instances for the application.
00159      */
00160     static const InstanceID_t NUM_INSTANCES = YOTTA_CFG_BLE_INSTANCES_COUNT;
00161 #endif
00162 
00163     /**
00164      * Get a reference to the BLE singleton corresponding to a given interface.
00165      *
00166      * There is a static array of BLE singletons.
00167      *
00168      * @note Calling Instance() is preferred over constructing a BLE object
00169      * directly because it returns references to singletons.
00170      *
00171      * @param[in] id BLE Instance ID to get.
00172      *
00173      * @return A reference to a single object.
00174      *
00175      * @pre id shall be less than NUM_INSTANCES.
00176      */
00177     static BLE &Instance(InstanceID_t id = DEFAULT_INSTANCE);
00178 
00179     /**
00180      * Fetch the ID of a BLE instance.
00181      *
00182      * @return Instance id of this BLE instance.
00183      */
00184     InstanceID_t getInstanceID(void) const
00185     {
00186         return instanceID;
00187     }
00188 
00189     /**
00190      * Events to process event.
00191      *
00192      * Instances of OnEventsToProcessCallbackContext are passed to the event
00193      * handler registered with onEventsToProcess().
00194      */
00195     struct OnEventsToProcessCallbackContext {
00196         /**
00197          * The ble instance which have events to process.
00198          */
00199         BLE &ble;
00200     };
00201 
00202     /**
00203      * Events to process event handler
00204      */
00205     typedef FunctionPointerWithContext<OnEventsToProcessCallbackContext *> 
00206         OnEventsToProcessCallback_t;
00207 
00208     /**
00209      * Register a callback called when the BLE stack has pending work.
00210      *
00211      * By registering a callback, application code can know when event processing
00212      * has to be scheduled.
00213      *
00214      * @param on_event_cb Callback invoked when there are new events to process.
00215      */
00216     void onEventsToProcess(const OnEventsToProcessCallback_t  &on_event_cb);
00217 
00218     /**
00219      * Process ALL pending events living in the BLE stack and return once all
00220      * events have been consumed.
00221      *
00222      * @see onEventsToProcess()
00223      */
00224     void processEvents();
00225 
00226     /**
00227      * Initialization complete event.
00228      *
00229      * This event is generated at the end of the init() procedure and is passed
00230      * to the completion callback passed to init().
00231      */
00232     struct InitializationCompleteCallbackContext {
00233         /**
00234          * Reference to the BLE object that has been initialized
00235          */
00236         BLE &ble;
00237 
00238         /**
00239          * Error status of the initialization.
00240          *
00241          * That value is set to BLE_ERROR_NONE if initialization completed
00242          * successfully or the appropriate error code otherwise.
00243          * */
00244         ble_error_t error;
00245     };
00246 
00247     /**
00248      * Initialization complete event handler.
00249      *
00250      * @note There are two versions of init(). In addition to the
00251      * function-pointer, init() can also take an <Object, member> tuple as its
00252      * callback target. In case of the latter, the following declaration doesn't
00253      * apply.
00254      */
00255     typedef void (*InitializationCompleteCallback_t)(
00256         InitializationCompleteCallbackContext *context
00257     );
00258 
00259     /**
00260      * Initialize the BLE controller/stack.
00261      *
00262      * init() hands control to the underlying BLE module to accomplish
00263      * initialization. This initialization may tacitly depend on other hardware
00264      * setup (such as clocks or power-modes) that happens early on during system
00265      * startup. It may not be safe to call init() from a global static context
00266      * where ordering is compiler-specific and can't be guaranteed - it is safe
00267      * to call BLE::init() from within main().
00268      *
00269      * @param[in] completion_cb A callback for when initialization completes for
00270      * a BLE instance. This is an optional parameter; if no callback is set up,
00271      * the application can still determine the status of initialization using
00272      * BLE::hasInitialized() (see below).
00273      *
00274      * @return BLE_ERROR_NONE if the initialization procedure started
00275      * successfully.
00276      *
00277      * @note If init() returns BLE_ERROR_NONE, the underlying stack must invoke
00278      * the initialization completion callback at some point.
00279      *
00280      * @note Nearly all BLE APIs would return BLE_ERROR_INITIALIZATION_INCOMPLETE
00281      * if used on an instance before the corresponding transport is initialized.
00282      *
00283      * @note There are two versions of init(). In addition to the
00284      * function-pointer, init() can also take an <Object, member> pair as its
00285      * callback target.
00286      *
00287      * @attention This should be called before using anything else in the BLE
00288      * API.
00289      */
00290     ble_error_t init(InitializationCompleteCallback_t completion_cb = NULL)
00291     {
00292         FunctionPointerWithContext<InitializationCompleteCallbackContext *> callback(completion_cb);
00293         return initImplementation(callback);
00294     }
00295 
00296     /**
00297      * Initialize the BLE controller/stack.
00298      *
00299      * This is an alternate declaration for init(). This one takes an
00300      * <Object, member> pair as its callback target.
00301      *
00302      * @param[in] object Object, which will be used to invoke the completion callback.
00303      * @param[in] completion_cb Member function pointer, which will be invoked when
00304      * initialization is complete.
00305      */
00306     template<typename T>
00307     ble_error_t init(T *object, void (T::*completion_cb)(InitializationCompleteCallbackContext *context))
00308     {
00309         FunctionPointerWithContext<InitializationCompleteCallbackContext *> callback(object, completion_cb);
00310         return initImplementation(callback);
00311     }
00312 
00313     /**
00314      * Indicate if the BLE instance has been initialized.
00315      *
00316      * @return true if initialization has completed for the underlying BLE
00317      * transport.
00318      *
00319      * @note The application should set up a callback to signal completion of
00320      * initialization when using init().
00321      */
00322     bool hasInitialized(void) const;
00323 
00324     /**
00325      * Shut down the underlying stack, and reset state of this BLE instance.
00326      *
00327      * @return BLE_ERROR_NONE if the instance was shut down without error or the
00328      * appropriate error code.
00329      *
00330      * @attention init() must be called afterward to reinstate services and
00331      * GAP state. This API offers a way to repopulate the GATT database with new
00332      * services and characteristics.
00333      */
00334     ble_error_t shutdown(void);
00335 
00336     /**
00337      * This call allows the application to get the BLE stack version information.
00338      *
00339      * @return A pointer to a const string representing the version.
00340      *
00341      * @note The BLE API owns the string returned.
00342      */
00343     const char *getVersion(void);
00344 
00345     /**
00346      * Accessor to Gap. All Gap-related functionality requires going through
00347      * this accessor.
00348      *
00349      * @return A reference to a Gap object associated to this BLE instance.
00350      */
00351     Gap &gap();
00352 
00353     /**
00354      * A const alternative to gap().
00355      *
00356      * @return A const reference to a Gap object associated to this BLE instance.
00357      */
00358     const Gap &gap() const;
00359 
00360 #if BLE_FEATURE_GATT_SERVER
00361     /**
00362      * Accessor to GattServer. All GattServer related functionality requires
00363      * going through this accessor.
00364      *
00365      * @return A reference to a GattServer object associated to this BLE instance.
00366      */
00367     GattServer &gattServer();
00368 
00369     /**
00370      * A const alternative to gattServer().
00371      *
00372      * @return A const reference to a GattServer object associated to this BLE
00373      * instance.
00374      */
00375     const GattServer &gattServer() const;
00376 #endif // BLE_FEATURE_GATT_SERVER
00377 
00378 #if BLE_FEATURE_GATT_CLIENT
00379     /**
00380      * Accessors to GattClient. All GattClient related functionality requires
00381      * going through this accessor.
00382      *
00383      * @return A reference to a GattClient object associated to this BLE instance.
00384      */
00385     GattClient &gattClient();
00386 
00387     /**
00388      * A const alternative to gattClient().
00389      *
00390      * @return A const reference to a GattClient object associated to this BLE
00391      * instance.
00392      */
00393     const GattClient &gattClient() const;
00394 #endif // BLE_FEATURE_GATT_CLIENT
00395 
00396 #if BLE_FEATURE_SECURITY
00397     /**
00398      * Accessors to SecurityManager. All SecurityManager-related functionality
00399      * requires going through this accessor.
00400      *
00401      * @return A reference to a SecurityManager object associated to this BLE
00402      * instance.
00403      */
00404     SecurityManager &securityManager();
00405 
00406     /**
00407      * A const alternative to securityManager().
00408      *
00409      * @return A const reference to a SecurityManager object associated to this
00410      * BLE instance.
00411      */
00412     const SecurityManager &securityManager() const;
00413 #endif // BLE_FEATURE_SECURITY
00414 
00415     /**
00416      * Translate error code into a printable string.
00417      *
00418      * @param[in] error Error code returned by BLE functions.
00419      *
00420      * @return A pointer to a const string describing the error.
00421      */
00422     static const char *errorToString(ble_error_t error);
00423 
00424     /*
00425      * Deprecation alert!
00426      * All of the following are deprecated and may be dropped in a future
00427      * release. Documentation should refer to alternative APIs.
00428      */
00429 public:
00430     /**
00431      * Constructor for a handle to a BLE instance (the BLE stack). BLE handles
00432      * are thin wrappers around a transport object (that is, ptr. to
00433      * BLEInstanceBase).
00434      *
00435      * @param[in] instanceID BLE Instance ID to get. 
00436      *
00437      * It is better to create BLE objects as singletons accessed through the
00438      * Instance() method. If multiple BLE handles are constructed for the same
00439      * interface (using this constructor), they share the same underlying
00440      * transport object.
00441      *
00442      * @deprecated Use the Instance() function instead of the constructor.
00443      */
00444     MBED_DEPRECATED("Use BLE::Instance() instead of BLE constructor.")
00445     BLE(InstanceID_t instanceID = DEFAULT_INSTANCE);
00446 
00447     /**
00448      * Yield control to the BLE stack or to other tasks waiting for events.
00449      *
00450      * This is a sleep function that returns when there is an application-specific
00451      * interrupt. This is not interchangeable with WFE() considering that the
00452      * MCU might wake up several times to service the stack before returning
00453      * control to the caller.
00454      *
00455      * @deprecated This function blocks the CPU. Use the pair
00456      * onEventsToProcess() and processEvents().
00457      */
00458     MBED_DEPRECATED("Use BLE::processEvents() and BLE::onEventsToProcess().")
00459     void waitForEvent(void);
00460 
00461     /**
00462      * Set the BTLE MAC address and type.
00463      *
00464      * @param[in] type Type of the address to set.
00465      * @param[in] address Value of the address to set. It is ordered in
00466      * little endian.
00467      *
00468      * @return BLE_ERROR_NONE on success.
00469      *
00470      * @deprecated You should use the parallel API from Gap directly, refer to
00471      * Gap::setAddress(). A former call to ble.setAddress(...) should be
00472      * replaced with ble.gap().setAddress(...).
00473      */
00474     MBED_DEPRECATED("Use ble.gap().setAddress(...)")
00475     ble_error_t setAddress(
00476         BLEProtocol::AddressType_t type,
00477         const BLEProtocol::AddressBytes_t address
00478     );
00479 
00480     /**
00481      * Fetch the Bluetooth Low Energy MAC address and type.
00482      *
00483      * @param[out] typeP Type of the current address set.
00484      * @param[out] address Value of the current address.
00485      *
00486      * @return BLE_ERROR_NONE on success.
00487      *
00488      * @deprecated You should use the parallel API from Gap directly and refer to
00489      * Gap::getAddress(). A former call to ble.getAddress(...) should be
00490      * replaced with ble.gap().getAddress(...).
00491      */
00492     MBED_DEPRECATED("Use ble.gap().getAddress(...)")
00493     ble_error_t getAddress(
00494         BLEProtocol::AddressType_t *typeP, BLEProtocol::AddressBytes_t address
00495     )
00496     {
00497         return gap().getAddress(typeP, address);
00498     }
00499 
00500 #if BLE_ROLE_BROADCASTER
00501     /**
00502      * Set the GAP advertising mode to use for this device.
00503      *
00504      * @param[in] advType New type of advertising to use.
00505      *
00506      * @deprecated You should use the parallel API from Gap directly and refer to
00507      *             Gap::setAdvertisingType(). A former call to
00508      *             ble.setAdvertisingType(...) should be replaced with
00509      *             ble.gap().setAdvertisingType(...).
00510      */
00511     MBED_DEPRECATED("Use ble.gap().setAdvertisingType(...)")
00512     void setAdvertisingType(GapAdvertisingParams::AdvertisingType advType);
00513 
00514     /**
00515      * Set the advertising interval.
00516      *
00517      * @param[in] interval
00518      *              Advertising interval in units of milliseconds. Advertising
00519      *              is disabled if interval is 0. If interval is smaller than
00520      *              the minimum supported value, then the minimum supported
00521      *              value is used instead. This minimum value can be discovered
00522      *              using getMinAdvertisingInterval().
00523      *
00524      *              This field must be set to 0 if connectionMode is equal
00525      *              to ADV_CONNECTABLE_DIRECTED.
00526      *
00527      * @note Decreasing this value allows central devices to detect a
00528      * peripheral faster at the expense of more power being used by the radio
00529      * due to the higher data transmit rate.
00530      *
00531      * @deprecated You should use the parallel API from Gap directly and refer to
00532      *             Gap::setAdvertisingInterval(). A former call to
00533      *             ble.setAdvertisingInterval(...) should be replaced with
00534      *             ble.gap().setAdvertisingInterval(...).
00535      *
00536      * @note WARNING: This API previously used 0.625ms as the unit for its
00537      * 'interval' argument. That required an explicit conversion from
00538      * milliseconds using Gap::MSEC_TO_GAP_DURATION_UNITS(). This conversion is
00539      * no longer required as the new units are milliseconds. Any application
00540      * code depending on the old semantics needs to be updated accordingly.
00541      */
00542     MBED_DEPRECATED("Use ble.gap().setAdvertisingInterval(...)")
00543     void setAdvertisingInterval(uint16_t interval);
00544 
00545     /**
00546      * Get the minimum advertising interval in milliseconds, which can be used
00547      * for connectable advertising types.
00548      *
00549      * @return Minimum Advertising interval in milliseconds.
00550      *
00551      * @deprecated You should use the parallel API from Gap directly, refer to
00552      *             Gap::getMinAdvertisingInterval(). A former call to
00553      *             ble.getMinAdvertisingInterval(...) should be replaced with
00554      *             ble.gap().getMinAdvertisingInterval(...).
00555      */
00556     MBED_DEPRECATED("Use ble.gap().getMinAdvertisingInterval(...)")
00557     uint16_t getMinAdvertisingInterval(void) const
00558     {
00559         return gap().getMinAdvertisingInterval();
00560     }
00561 
00562     /**
00563      * Get the minimum advertising interval in milliseconds, which can be
00564      * used for nonconnectable advertising type.
00565      *
00566      * @return Minimum Advertising interval in milliseconds for nonconnectible mode.
00567      *
00568      * @deprecated You should use the parallel API from Gap directly, refer to
00569      *             Gap::MinNonConnectableAdvertisingInterval(). A former call to
00570      *             ble.getMinNonConnectableAdvertisingInterval(...) should be replaced with
00571      *             ble.gap().getMinNonConnectableAdvertisingInterval(...).
00572      */
00573     MBED_DEPRECATED("Use ble.gap().getMinNonConnectableAdvertisingInterval(...)")
00574     uint16_t getMinNonConnectableAdvertisingInterval(void) const
00575     {
00576         return gap().getMinNonConnectableAdvertisingInterval();
00577     }
00578 
00579     /**
00580      * Get the maximum advertising interval in milliseconds.
00581      *
00582      * @return Maximum Advertising interval in milliseconds.
00583      *
00584      * @deprecated You should use the parallel API from Gap directly, refer to
00585      *             Gap::getMaxAdvertisingInterval(). A former call to
00586      *             ble.getMaxAdvertisingInterval(...) should be replaced with
00587      *             ble.gap().getMaxAdvertisingInterval(...).
00588      */
00589     MBED_DEPRECATED("Use ble.gap().getMaxAdvertisingInterval(...)")
00590     uint16_t getMaxAdvertisingInterval(void) const
00591     {
00592         return gap().getMaxAdvertisingInterval();
00593     }
00594 
00595     /**
00596      * Set the advertising duration.
00597      *
00598      * A timeout event is genenerated once the advertising period expired.
00599      *
00600      * @param[in] timeout
00601      *              Advertising timeout (in seconds) between 0x1 and 0x3FFF (1
00602      *              and 16383). Use 0 to disable the advertising timeout.
00603      *
00604      * @deprecated You should use the parallel API from Gap directly and refer to
00605      *             Gap::setAdvertisingTimeout(). A former call to
00606      *             ble.setAdvertisingTimeout(...) should be replaced with
00607      *             ble.gap().setAdvertisingTimeout(...).
00608      */
00609     MBED_DEPRECATED("Use ble.gap().setAdvertisingTimeout(...)")
00610     void setAdvertisingTimeout(uint16_t timeout);
00611 
00612     /**
00613      * Set up a particular, user-constructed set of advertisement parameters for
00614      * the underlying stack. It would be uncommon for this API to be used
00615      * directly; there are other APIs to tweak advertisement parameters
00616      * individually (see above).
00617      *
00618      * @param[in] advParams The new advertising parameters.
00619      *
00620      * @deprecated You should use the parallel API from Gap directly and refer to
00621      *             Gap::setAdvertisingParams(). A former call to
00622      *             ble.setAdvertisingParams(...) should be replaced with
00623      *             ble.gap().setAdvertisingParams(...).
00624      */
00625     MBED_DEPRECATED("Use ble.gap().setAdvertisingParams(...)")
00626     void setAdvertisingParams(const GapAdvertisingParams &advParams);
00627 
00628     /**
00629      * Get the current advertising parameters.
00630      *
00631      * @return  Read back advertising parameters. Useful for storing and
00632      *          restoring parameters rapidly.
00633      *
00634      * @deprecated You should use the parallel API from Gap directly and refer to
00635      *             Gap::getAdvertisingParams(). A former call to
00636      *             ble.getAdvertisingParams(...) should be replaced with
00637      *             ble.gap().getAdvertisingParams(...).
00638      */
00639     MBED_DEPRECATED("Use ble.gap().getAdvertisingParams(...)")
00640     const GapAdvertisingParams &getAdvertisingParams(void) const;
00641 
00642     /**
00643      * Accumulate an AD structure in the advertising payload. Please note that
00644      * the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used
00645      * as an additional 31 bytes if the advertising payload is too
00646      * small.
00647      *
00648      * @param[in] flags
00649      *              The flags to add. Please refer to
00650      *              GapAdvertisingData::Flags for valid flags. Multiple
00651      *              flags may be specified in combination.
00652      *
00653      * @return BLE_ERROR_NONE if the data was successfully added to the
00654      * advertising payload.
00655      *
00656      * @deprecated You should use the parallel API from Gap directly, refer to
00657      *             Gap::accumulateAdvertisingPayload(uint8_t). A former call to
00658      *             ble.accumulateAdvertisingPayload(flags) should be replaced with
00659      *             ble.gap().accumulateAdvertisingPayload(flags).
00660      */
00661     MBED_DEPRECATED("Use ble.gap().accumulateAdvertisingPayload(flags)")
00662     ble_error_t accumulateAdvertisingPayload(uint8_t flags);
00663 
00664     /**
00665      * Accumulate an AD structure in the advertising payload. Please note that
00666      * the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used
00667      * as an additional 31 bytes if the advertising payload is too
00668      * small.
00669      *
00670      * @param[in] app
00671      *              The appearance of the peripheral.
00672      *
00673      * @return BLE_ERROR_NONE if the data was successfully added to the
00674      * advertising payload.
00675      *
00676      * @deprecated You should use the parallel API from Gap directly and refer to
00677      *             Gap::accumulateAdvertisingPayload(GapAdvertisingData::Appearance).
00678      *             A former call to ble.accumulateAdvertisingPayload(appearance)
00679      *             should be replaced with
00680      *             ble.gap().accumulateAdvertisingPayload(appearance).
00681      */
00682     MBED_DEPRECATED("Use ble.gap().accumulateAdvertisingPayload(appearance)")
00683     ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::Appearance app);
00684 
00685     /**
00686      * Accumulate an AD structure in the advertising payload. Please note that
00687      * the payload is limited to 31 bytes. The SCAN_RESPONSE message may be used
00688      * as an additional 31 bytes if the advertising payload is too
00689      * small.
00690      *
00691      * @param[in] power
00692      *              The max transmit power to be used by the controller. This
00693      *              is only a hint.
00694      *
00695      * @return BLE_ERROR_NONE if the data was successfully added to the
00696      * advertising payload.
00697      *
00698      * @deprecated You should use the parallel API from Gap directly and refer to
00699      *             Gap::accumulateAdvertisingPayloadTxPower(). A former call to
00700      *             ble.accumulateAdvertisingPayloadTxPower(txPower) should be replaced with
00701      *             ble.gap().accumulateAdvertisingPayloadTxPower(txPower).
00702      */
00703     MBED_DEPRECATED("Use ble.gap().accumulateAdvertisingPayloadTxPower(...)")
00704     ble_error_t accumulateAdvertisingPayloadTxPower(int8_t power);
00705 
00706     /**
00707      * Accumulate a variable length byte-stream as an AD structure in the
00708      * advertising payload. Please note that the payload is limited to 31 bytes.
00709      * The SCAN_RESPONSE message may be used as an additional 31 bytes if the
00710      * advertising payload is too small.
00711      *
00712      * @param  type The type that describes the variable length data.
00713      * @param  data Data bytes.
00714      * @param  len  Data length.
00715      *
00716      * @return BLE_ERROR_NONE if the advertisement payload was updated based on
00717      * matching AD type; otherwise, an appropriate error.
00718      *
00719      * @deprecated You should use the parallel API from Gap directly, refer to
00720      *             Gap::accumulateAdvertisingPayload(GapAdvertisingData::DataType, const uint8_t, uint8_t).
00721      *             A former call to ble.accumulateAdvertisingPayload(...) should
00722      *             be replaced with ble.gap().accumulateAdvertisingPayload(...).
00723      */
00724     MBED_DEPRECATED("Use ble.gap().accumulateAdvertisingPayload(...)")
00725     ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len);
00726 
00727     /**
00728      * Set up a particular, user-constructed advertisement payload for the
00729      * underlying stack. It would be uncommon for this API to be used directly;
00730      * there are other APIs to build an advertisement payload (see above).
00731      *
00732      * @param[in] advData Advertising data to set.
00733      *
00734      * @return BLE_ERROR_NONE if the advertising data was set successfully.
00735      *
00736      * @deprecated You should use the parallel API from Gap directly, refer to
00737      *             Gap::setAdvertisingData(). A former call to
00738      *             ble.setAdvertisingData(...) should be replaced with
00739      *             ble.gap().setAdvertisingPayload(...).
00740      */
00741     MBED_DEPRECATED("Use ble.gap().setAdvertisingData(...)")
00742     ble_error_t setAdvertisingData(const GapAdvertisingData &advData);
00743 
00744     /**
00745      * Get a reference to the current advertising payload.
00746      *
00747      * @return  Read back advertising data. Useful for storing and
00748      *          restoring payload.
00749      *
00750      * @deprecated You should use the parallel API from Gap directly, refer to
00751      *             Gap::getAdvertisingData(). A former call to
00752      *             ble.getAdvertisingData(...) should be replaced with
00753      *             ble.gap().getAdvertisingPayload()(...).
00754      */
00755     MBED_DEPRECATED("Use ble.gap().getAdvertisingData(...)")
00756     const GapAdvertisingData &getAdvertisingData(void) const;
00757 
00758     /**
00759      * Reset any advertising payload prepared from prior calls to
00760      * accumulateAdvertisingPayload(). This automatically propagates the re-
00761      * initialized advertising payload to the underlying stack.
00762      *
00763      * @deprecated You should use the parallel API from Gap directly and refer to
00764      *             Gap::clearAdvertisingPayload(). A former call to
00765      *             ble.clearAdvertisingPayload(...) should be replaced with
00766      *             ble.gap().clearAdvertisingPayload(...).
00767      */
00768     MBED_DEPRECATED("Use ble.gap().clearAdvertisingPayload(...)")
00769     void clearAdvertisingPayload(void);
00770 
00771     /**
00772      * Dynamically reset the accumulated advertising
00773      * payload and scanResponse. The application must clear and re-
00774      * accumulate a new advertising payload (and scanResponse) before using this
00775      * API.
00776      *
00777      * @return BLE_ERROR_NONE when the advertising payload is set successfully.
00778      *
00779      * @deprecated You should use the parallel API from Gap directly, refer to
00780      *             Gap::setAdvertisingPayload().
00781      *
00782      * @note The new APIs in Gap update the underlying advertisement payload
00783      * implicitly.
00784      */
00785     MBED_DEPRECATED("Use ble.gap().setAdvertisingPayload(...)")
00786     ble_error_t setAdvertisingPayload(void);
00787 
00788     /**
00789      * Accumulate a variable length byte-stream as an AD structure in the
00790      * scanResponse payload.
00791      *
00792      * @param[in] type The type that describes the variable length data.
00793      * @param[in] data Data bytes.
00794      * @param[in] len  Data length.
00795      *
00796      * @return BLE_ERROR_NONE if the data was successfully added to the scan
00797      * response payload.
00798      *
00799      * @deprecated You should use the parallel API from Gap directly and refer to
00800      *             Gap::accumulateScanResponse(). A former call to
00801      *             ble.accumulateScanResponse(...) should be replaced with
00802      *             ble.gap().accumulateScanResponse(...).
00803      */
00804     MBED_DEPRECATED("Use ble.gap().accumulateScanResponse(...)")
00805     ble_error_t accumulateScanResponse(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len);
00806 
00807     /**
00808      * Reset any scan response prepared from prior calls to
00809      * accumulateScanResponse().
00810      *
00811      * @deprecated You should use the parallel API from Gap directly and refer to
00812      *             Gap::clearScanResponse(). A former call to
00813      *             ble.clearScanResponse(...) should be replaced with
00814      *             ble.gap().clearScanResponse(...).
00815      */
00816     MBED_DEPRECATED("Use ble.gap().clearScanResponse(...)")
00817     void clearScanResponse(void);
00818 
00819     /**
00820      * Start advertising.
00821      *
00822      * @return BLE_ERROR_NONE if the advertising procedure successfully
00823      * started.
00824      *
00825      * @deprecated You should use the parallel API from Gap directly and refer to
00826      *             Gap::startAdvertising(). A former call to
00827      *             ble.startAdvertising(...) should be replaced with
00828      *             ble.gap().startAdvertising(...).
00829      */
00830     MBED_DEPRECATED("Use ble.gap().startAdvertising(...)")
00831     ble_error_t startAdvertising(void);
00832 
00833     /**
00834      * Stop advertising.
00835      *
00836      * @return BLE_ERROR_NONE if the advertising procedure has been successfully
00837      * stopped.
00838      *
00839      * @deprecated You should use the parallel API from Gap directly and refer to
00840      *             Gap::stopAdvertising(). A former call to
00841      *             ble.stopAdvertising(...) should be replaced with
00842      *             ble.gap().stopAdvertising(...).
00843      */
00844     MBED_DEPRECATED("Use ble.gap().stopAdvertising(...)")
00845     ble_error_t stopAdvertising(void);
00846 #endif // BLE_ROLE_BROADCASTER
00847 
00848 #if BLE_ROLE_OBSERVER
00849     /**
00850      * Set up parameters for GAP scanning (observer mode).
00851      *
00852      * @param[in] interval
00853      *              Scan interval (in milliseconds) [valid values lie between 2.5ms and 10.24s].
00854      * @param[in] window
00855      *              Scan Window (in milliseconds) [valid values lie between 2.5ms and 10.24s].
00856      * @param[in] timeout
00857      *              Scan timeout (in seconds) between 0x0001 and 0xFFFF; 0x0000 disables timeout.
00858      * @param[in] activeScanning
00859      *              Set to True if active-scanning is required. This is used to fetch the
00860      *              scan response from a peer if possible.
00861      *
00862      * @return BLE_ERROR_NONE if the scan parameters were correctly set.
00863      *
00864      * The scanning window divided by the interval determines the duty cycle for
00865      * scanning. For example, if the interval is 100ms and the window is 10ms,
00866      * then the controller will scan for 10 percent of the time. It is possible
00867      * to have the interval and window set to the same value. In this case,
00868      * scanning is continuous, with a change of scanning frequency once every
00869      * interval.
00870      *
00871      * Once the scanning parameters have been configured, scanning can be
00872      * enabled by using startScan().
00873      *
00874      * @note The scan interval and window are recommendations to the BLE stack.
00875      *
00876      * @deprecated You should use the parallel API from Gap directly and refer to
00877      *             Gap::setScanParams(). A former call to
00878      *             ble.setScanParams(...) should be replaced with
00879      *             ble.gap().setScanParams(...).
00880      */
00881     MBED_DEPRECATED("Use ble.gap().setScanParams(...)")
00882     ble_error_t setScanParams(
00883         uint16_t interval = GapScanningParams::SCAN_INTERVAL_MAX,
00884         uint16_t window = GapScanningParams::SCAN_WINDOW_MAX,
00885         uint16_t timeout = 0,
00886         bool activeScanning = false
00887     );
00888 
00889     /**
00890      * Set up the scanInterval parameter for GAP scanning (observer mode).
00891      *
00892      * @param[in] interval
00893      *              Scan interval (in milliseconds) [valid values lie between 2.5ms and 10.24s].
00894      *
00895      * @return BLE_ERROR_NONE if the scan interval was correctly set.
00896      *
00897      * The scanning window divided by the interval determines the duty cycle for
00898      * scanning. For example, if the interval is 100ms and the window is 10ms,
00899      * then the controller will scan for 10 percent of the time. It is possible
00900      * to have the interval and window set to the same value. In this case,
00901      * scanning is continuous, with a change of scanning frequency once every
00902      * interval.
00903      *
00904      * Once the scanning parameters have been configured, scanning can be
00905      * enabled by using startScan().
00906      *
00907      * @deprecated You should use the parallel API from Gap directly and refer to
00908      *             Gap::setScanInterval(). A former call to
00909      *             ble.setScanInterval(interval) should be replaced with
00910      *             ble.gap().setScanInterval(interval).
00911      */
00912     MBED_DEPRECATED("Use ble.gap().setScanInterval(...)")
00913     ble_error_t setScanInterval(uint16_t interval);
00914 
00915     /**
00916      * Set up the scanWindow parameter for GAP scanning (observer mode).
00917      *
00918      * @param[in] window
00919      *              Scan Window (in milliseconds) [valid values lie between 2.5ms and 10.24s].
00920      *
00921      * @return BLE_ERROR_NONE if the scan window was correctly set.
00922      *
00923      * The scanning window divided by the interval determines the duty cycle for
00924      * scanning. For example, if the interval is 100ms and the window is 10ms,
00925      * then the controller will scan for 10 percent of the time. It is possible
00926      * to have the interval and window set to the same value. In this case,
00927      * scanning is continuous, with a change of scanning frequency once every
00928      * interval.
00929      *
00930      * Once the scanning parameters have been configured, scanning can be
00931      * enabled by using startScan().
00932      *
00933      * @deprecated You should use the parallel API from Gap directly and refer to
00934      *             Gap::setScanWindow(). A former call to
00935      *             ble.setScanWindow(window) should be replaced with
00936      *             ble.gap().setScanWindow(window).
00937      */
00938     MBED_DEPRECATED("Use ble.gap().setScanWindow(...)")
00939     ble_error_t setScanWindow(uint16_t window);
00940 
00941     /**
00942      * Set up parameters for GAP scanning (observer mode).
00943      *
00944      * @param[in] timeout
00945      *              Scan timeout (in seconds) between 0x0001 and 0xFFFF; 0x0000 disables timeout.
00946      *
00947      * @return BLE_ERROR_NONE if the scan timeout was correctly set.
00948      *
00949      * The scanning window divided by the interval determines the duty cycle for
00950      * scanning. For example, if the interval is 100ms and the window is 10ms,
00951      * then the controller will scan for 10 percent of the time. It is possible
00952      * to have the interval and window set to the same value. In this case,
00953      * scanning is continuous, with a change of scanning frequency once every
00954      * interval.
00955      *
00956      * Once the scanning parameters have been configured, scanning can be
00957      * enabled by using startScan().
00958      *
00959      * @note The scan interval and window are recommendations to the BLE stack.
00960      *
00961      * @deprecated You should use the parallel API from Gap directly and refer to
00962      *             Gap::setScanTimeout(). A former call to
00963      *             ble.setScanTimeout(...) should be replaced with
00964      *             ble.gap().setScanTimeout(...).
00965      */
00966     MBED_DEPRECATED("Use ble.gap().setScanTimeout(...)")
00967     ble_error_t setScanTimeout(uint16_t timeout);
00968 
00969     /**
00970      * Set up parameters for GAP scanning (observer mode).
00971      *
00972      * @param[in] activeScanning
00973      *              Set to True if active-scanning is required. This is used to fetch the
00974      *              scan response from a peer if possible.
00975      *
00976      * Once the scanning parameters have been configured, scanning can be
00977      * enabled by using startScan().
00978      *
00979      * @deprecated You should use the parallel API from Gap directly, refer to
00980      *             Gap::setActiveScan(). A former call to
00981      *             ble.setActiveScan(...) should be replaced with
00982      *             ble.gap().setActiveScanning(...).
00983      */
00984     MBED_DEPRECATED("Use ble.gap().setActiveScan(...)")
00985     void setActiveScan(bool activeScanning);
00986 
00987     /**
00988      * Start scanning (Observer Procedure) based on the parameters currently in
00989      * effect.
00990      *
00991      * @param[in] callback
00992      *              The application-specific callback to be invoked upon
00993      *              receiving every advertisement report. This can be passed in
00994      *              as NULL, in which case scanning may not be enabled at all.
00995      *
00996      * @return BLE_ERROR_NONE if the device successfully started the scan
00997      *         procedure.
00998      *
00999      * @deprecated You should use the parallel API from Gap directly, refer to
01000      *             Gap::startScan(). A former call to
01001      *             ble.startScan(callback) should be replaced with
01002      *             ble.gap().startScan(callback).
01003      */
01004     MBED_DEPRECATED("Use ble.gap().startScan(callback)")
01005     ble_error_t startScan(void (*callback)(const Gap::AdvertisementCallbackParams_t *params));
01006 
01007     /**
01008      * Start the scanning procedure.
01009      *
01010      * Packets received during the scan procedure are forwarded to the
01011      * scan packet handler passed as argument to this function.
01012      *
01013      * @param[in] object Instance used to invoke @p callbackMember.
01014      *
01015      * @param[in] memberCallback Advertisement packet event handler. Upon
01016      * reception of an advertising packet, the packet is forwarded to @p
01017      * callback invoked from @p object.
01018      *
01019      * @return BLE_ERROR_NONE if the device successfully started the scan
01020      * procedure.
01021      *
01022      * @deprecated You should use the parallel API from Gap directly, refer to
01023      *             Gap::startScan(). A former call to
01024      *             ble.startScan(callback) should be replaced with
01025      *             ble.gap().startScan(object, callback).
01026      */
01027     template<typename T>
01028     MBED_DEPRECATED("Use ble.gap().startScan(object, callback)")
01029     ble_error_t startScan(T *object, void (T::*memberCallback)(const Gap::AdvertisementCallbackParams_t *params));
01030 
01031     /**
01032      * Stop scanning. The current scanning parameters remain in effect.
01033      *
01034      * @return BLE_ERROR_NONE if successfully stopped scanning procedure.
01035      *
01036      * @deprecated You should use the parallel API from Gap directly and refer to
01037      *             Gap::stopScan(). A former call to
01038      *             ble.stopScan() should be replaced with
01039      *             ble.gap().stopScan().
01040      */
01041     MBED_DEPRECATED("Use ble.gap().stopScan()")
01042     ble_error_t stopScan(void)
01043     {
01044         return gap().stopScan();
01045     }
01046 #endif // BLE_ROLE_OBSERVER
01047 
01048 #if BLE_ROLE_CENTRAL
01049     /**
01050      * Create a connection (GAP Link Establishment).
01051      *
01052      * @param peerAddr
01053      *          48-bit address, LSB format.
01054      * @param peerAddrType
01055      *          Address type of the peer.
01056      * @param connectionParams
01057      *         Connection parameters.
01058      * @param scanParams
01059      *          Parameters to use while scanning for the peer.
01060      *
01061      * @return  BLE_ERROR_NONE if connection establishment procedure is started
01062      *     successfully. The onConnection callback (if set) is invoked upon
01063      *     a connection event.
01064      *
01065      * @deprecated You should use the parallel API from Gap directly and refer to
01066      *             Gap::connect(). A former call to
01067      *             ble.connect(...) should be replaced with
01068      *             ble.gap().connect(...).
01069      */
01070     MBED_DEPRECATED("Use ble.gap().connect(...)")
01071     ble_error_t connect(
01072         const BLEProtocol::AddressBytes_t peerAddr,
01073         BLEProtocol::AddressType_t peerAddrType = BLEProtocol::AddressType::RANDOM_STATIC,
01074         const Gap::ConnectionParams_t *connectionParams = NULL,
01075         const GapScanningParams *scanParams = NULL
01076     );
01077 #endif // BLE_ROLE_CENTRAL
01078 
01079 #if BLE_FEATURE_CONNECTABLE
01080     /**
01081      * This call initiates the disconnection procedure, and its completion is
01082      * communicated to the application with an invocation of the
01083      * onDisconnection callback.
01084      *
01085      * @param[in] connectionHandle
01086      * @param[in] reason
01087      *              The reason for disconnection; sent back to the peer.
01088      *
01089      * @return  BLE_ERROR_NONE if the disconnection procedure successfully
01090      * started.
01091      *
01092      * @deprecated You should use the parallel API from Gap directly and refer to
01093      *             GAP::disconnect(). A former call to
01094      *             ble.disconnect(...) should be replaced with
01095      *             ble.gap().disconnect(...).
01096      */
01097     MBED_DEPRECATED("Use ble.gap().disconnect(...)")
01098     ble_error_t disconnect(Gap::Handle_t connectionHandle, Gap::DisconnectionReason_t reason);
01099 
01100     /**
01101      * This call initiates the disconnection procedure, and its completion
01102      * is communicated to the application with an invocation of the
01103      * onDisconnection callback.
01104      *
01105      * @param  reason
01106      *           The reason for disconnection; sent back to the peer.
01107      *
01108      * @return  BLE_ERROR_NONE if the disconnection procedure successfully
01109      * started.
01110      *
01111      * @deprecated You should use the parallel API from Gap directly and refer to
01112      *             Gap::disconnect(). A former call to
01113      *             ble.disconnect(reason) should be replaced with
01114      *             ble.gap().disconnect(reason).
01115      *
01116      * @note This version of disconnect() doesn't take a connection handle. It
01117      * works reliably only for stacks that are limited to a single
01118      * connection.
01119      */
01120     MBED_DEPRECATED("Use ble.gap().disconnect(...)")
01121     ble_error_t disconnect(Gap::DisconnectionReason_t reason);
01122 #endif // BLE_FEATURE_CONNECTABLE
01123 
01124     /**
01125      * Returns the current Gap state of the device using a bitmask that
01126      * describes whether the device is advertising or connected.
01127      *
01128      * @return The current GAP state of the device.
01129      *
01130      * @deprecated You should use the parallel API from Gap directly and refer to
01131      *             Gap::getState(). A former call to
01132      *             ble.getGapState() should be replaced with
01133      *             ble.gap().getState().
01134      */
01135     MBED_DEPRECATED("Use ble.gap().getState()")
01136     Gap::GapState_t getGapState(void) const;
01137 
01138 #if BLE_FEATURE_CONNECTABLE
01139 #if BLE_FEATURE_GATT_SERVER
01140     /**
01141      * Get the GAP peripheral's preferred connection parameters. These are the
01142      * defaults that the peripheral would like to have in a connection. The
01143      * choice of the connection parameters is eventually up to the central.
01144      *
01145      * @param[out] params
01146      *               The structure where the parameters will be stored. The caller owns memory
01147      *               for this.
01148      *
01149      * @return BLE_ERROR_NONE if the parameters were successfully filled into
01150      * the given structure pointed to by params.
01151      *
01152      * @deprecated You should use the parallel API from Gap directly and refer to
01153      *             Gap::getPreferredConnectionParams(). A former call to
01154      *             ble.getPreferredConnectionParams() should be replaced with
01155      *             ble.gap().getPreferredConnectionParams().
01156      */
01157     MBED_DEPRECATED("Use ble.gap().getPreferredConnectionParams(...)")
01158     ble_error_t getPreferredConnectionParams(Gap::ConnectionParams_t *params)
01159     {
01160         return gap().getPreferredConnectionParams(params);
01161     }
01162 
01163     /**
01164      * Set the GAP peripheral's preferred connection parameters. These are the
01165      * defaults that the peripheral would like to have in a connection. The
01166      * choice of the connection parameters is eventually up to the central.
01167      *
01168      * @param[in] params
01169      *               The structure containing the desired parameters.
01170      *
01171      * @return BLE_ERROR_NONE if the preferred connection parameters were set
01172      * correctly.
01173      *
01174      * @deprecated You should use the parallel API from Gap directly and refer to
01175      *             Gap::setPreferredConnectionParams(). A former call to
01176      *             ble.setPreferredConnectionParams() should be replaced with
01177      *             ble.gap().setPreferredConnectionParams().
01178      */
01179     MBED_DEPRECATED("Use ble.gap().setPreferredConnectionParams(...)")
01180     ble_error_t setPreferredConnectionParams(const Gap::ConnectionParams_t *params)
01181     {
01182         return gap().setPreferredConnectionParams(params);
01183     }
01184 #endif // BLE_FEATURE_GATT_SERVER
01185 
01186     /**
01187      * Update connection parameters while in the peripheral role.
01188      *
01189      * @details In the peripheral role, this will send the corresponding L2CAP request to the connected peer and wait for
01190      *          the central to perform the procedure.
01191      *
01192      * @param[in] handle
01193      *              Connection Handle
01194      * @param[in] params
01195      *              Pointer to desired connection parameters. If NULL is provided on a peripheral role,
01196      *              the parameters in the PPCP characteristic of the GAP service will be used instead.
01197      *
01198      * @return BLE_ERROR_NONE if the connection parameters were updated correctly.
01199      *
01200      * @deprecated You should use the parallel API from Gap directly and refer to
01201      *             Gap::updateConnectionParams(). A former call to
01202      *             ble.updateConnectionParams() should be replaced with
01203      *             ble.gap().updateConnectionParams().
01204      */
01205     MBED_DEPRECATED("Use ble.gap().updateConnectionParams(...)")
01206     ble_error_t updateConnectionParams(Gap::Handle_t handle, const Gap::ConnectionParams_t *params);
01207 #endif // BLE_FEATURE_CONNECTABLE
01208 
01209 #if BLE_FEATURE_GATT_SERVER
01210     /**
01211      * Set the device name characteristic in the Gap service.
01212      *
01213      * @param[in] deviceName
01214      *              The new value for the device-name. This is a UTF-8 encoded, <b>NULL-terminated</b> string.
01215      *
01216      * @return BLE_ERROR_NONE if the device name was set correctly.
01217      *
01218      * @deprecated You should use the parallel API from Gap directly and refer to
01219      *             Gap::setDeviceName(). A former call to
01220      *             ble.setDeviceName() should be replaced with
01221      *             ble.gap().setDeviceName().
01222      */
01223     MBED_DEPRECATED("Use ble.gap().setDeviceName(...)")
01224     ble_error_t setDeviceName(const uint8_t *deviceName)
01225     {
01226         return gap().setDeviceName(deviceName);
01227     }
01228 
01229     /**
01230      * Get the value of the device name characteristic in the Gap service.
01231      *
01232      * @param[out]    deviceName
01233      *                  Pointer to an empty buffer where the UTF-8 *non NULL-
01234      *                  terminated* string will be placed. Set this
01235      *                  value to NULL to obtain the deviceName-length
01236      *                  from the 'length' parameter.
01237      *
01238      * @param[in,out] lengthP
01239      *                  (on input) Length of the buffer pointed to by deviceName;
01240      *                  (on output) the complete device name length (without the
01241      *                     null terminator).
01242      *
01243      * @return BLE_ERROR_NONE if the device name was fetched correctly from the
01244      * underlying BLE stack.
01245      *
01246      * @note If the device name is longer than the size of the supplied buffer,
01247      *     the length will return the complete device name length and not the
01248      *     number of bytes actually returned in deviceName. The application may
01249      *     use this information to retry with a suitable buffer size.
01250      *
01251      * @deprecated You should use the parallel API from Gap directly and refer to
01252      *             Gap::getDeviceName(). A former call to
01253      *             ble.getDeviceName() should be replaced with
01254      *             ble.gap().getDeviceName().
01255      */
01256     MBED_DEPRECATED("Use ble.gap().getDeviceName(...)")
01257     ble_error_t getDeviceName(uint8_t *deviceName, unsigned *lengthP)
01258     {
01259         return gap().getDeviceName(deviceName, lengthP);
01260     }
01261 
01262     /**
01263      * Set the appearance characteristic in the Gap service.
01264      *
01265      * @param[in] appearance
01266      *              The new value for the device-appearance.
01267      *
01268      * @return BLE_ERROR_NONE if the new appearance was set correctly.
01269      *
01270      * @deprecated You should use the parallel API from Gap directly and refer to
01271      *             Gap::setAppearance(). A former call to
01272      *             ble.setAppearance() should be replaced with
01273      *             ble.gap().setAppearance().
01274      */
01275     MBED_DEPRECATED("Use ble.gap().setAppearance(...)")
01276     ble_error_t setAppearance(GapAdvertisingData::Appearance appearance)
01277     {
01278         return gap().setAppearance(appearance);
01279     }
01280 
01281     /**
01282      * Get the appearance characteristic in the Gap service.
01283      *
01284      * @param[out] appearanceP
01285      *               The new value for the device-appearance.
01286      *
01287      * @return BLE_ERROR_NONE if the device-appearance was fetched correctly
01288      * from the underlying BLE stack.
01289      *
01290      * @deprecated You should use the parallel API from Gap directly, refer to
01291      *             Gap::getAppearance(). A former call to
01292      *             ble.getAppearance() should be replaced with
01293      *             ble.gap().getAppearance().
01294      */
01295     MBED_DEPRECATED("Use ble.gap().getAppearance(...)")
01296     ble_error_t getAppearance(GapAdvertisingData::Appearance *appearanceP)
01297     {
01298         return gap().getAppearance(appearanceP);
01299     }
01300 #endif // BLE_FEATURE_GATT_SERVER
01301 
01302     /**
01303      * Set the radio's transmit power.
01304      *
01305      * @param[in] txPower Radio transmit power in dBm.
01306      *
01307      * @return BLE_ERROR_NONE if the new radio's transmit power was set
01308      * correctly.
01309      *
01310      * @deprecated You should use the parallel API from Gap directly and refer to
01311      *             Gap::setTxPower(). A former call to
01312      *             ble.setTxPower() should be replaced with
01313      *             ble.gap().setTxPower().
01314      */
01315     MBED_DEPRECATED("Use ble.gap().setTxPower(...)")
01316     ble_error_t setTxPower(int8_t txPower);
01317 
01318     /**
01319      * Query the underlying stack for permitted arguments for setTxPower().
01320      *
01321      * @param[out] valueArrayPP
01322      *                 Out parameter to receive the immutable array of Tx values.
01323      * @param[out] countP
01324      *                 Out parameter to receive the array's size.
01325      *
01326      * @deprecated You should use the parallel API from Gap directly, refer to
01327      *             Gap::getPermittedTxPowerValues(). A former call to
01328      *             ble.getPermittedTxPowerValues() should be replaced with
01329      *             ble.gap().getPermittedTxPowerValues().
01330      */
01331     MBED_DEPRECATED("Use ble.gap().getPermittedTxPowerValues(...)")
01332     void getPermittedTxPowerValues(const int8_t **valueArrayPP, size_t *countP);
01333 
01334 #if BLE_FEATURE_GATT_SERVER
01335     /**
01336      * Add a service declaration to the local server ATT table. Also add the
01337      * characteristics contained within.
01338      *
01339      * @param[in] service The service to be added; attribute handle of services,
01340      * characteristic and characteristic descriptors are updated by the
01341      * process.
01342      *
01343      * @return BLE_ERROR_NONE if the service was successfully added.
01344      *
01345      * @deprecated You should use the parallel API from GattServer directly, refer to
01346      *             GattServer::addService(). A former call
01347      *             to ble.addService() should be replaced with
01348      *             ble.gattServer().addService().
01349      */
01350     MBED_DEPRECATED("Use ble.gattServer().addService(...)")
01351     ble_error_t addService(GattService &service)
01352     {
01353         return gattServer().addService(service);
01354     }
01355 
01356     /**
01357      * Read the value of a characteristic from the local GattServer.
01358      *
01359      * @param[in]     attributeHandle
01360      *                  Attribute handle for the value attribute of the characteristic.
01361      * @param[out]    buffer
01362      *                  A buffer to hold the value being read.
01363      * @param[in,out] lengthP
01364      *                  Length of the buffer being supplied. If the attribute
01365      *                  value is longer than the size of the supplied buffer,
01366      *                  this variable will return the total attribute value length
01367      *                  (excluding offset). The application may use this
01368      *                  information to allocate a suitable buffer size.
01369      *
01370      * @return BLE_ERROR_NONE if a value was read successfully into the buffer.
01371      *
01372      * @deprecated You should use the parallel API from GattServer directly,
01373      *             GattServer::read(GattAttribute::Handle_t,uint8_t,uint16_t). A former call
01374      *             to ble.readCharacteristicValue() should be replaced with
01375      *             ble.gattServer().read().
01376      */
01377     MBED_DEPRECATED("Use ble.gattServer().read(...)")
01378     ble_error_t readCharacteristicValue(GattAttribute::Handle_t attributeHandle, uint8_t *buffer, uint16_t *lengthP)
01379     {
01380         return gattServer().read(attributeHandle, buffer, lengthP);
01381     }
01382 
01383     /**
01384      * Read the value of a characteristic from the local GattServer.
01385      *
01386      * @param[in]     connectionHandle
01387      *                  Connection Handle.
01388      * @param[in]     attributeHandle
01389      *                  Attribute handle for the value attribute of the characteristic.
01390      * @param[out]    buffer
01391      *                  A buffer to hold the value being read.
01392      * @param[in,out] lengthP
01393      *                  Length of the buffer being supplied. If the attribute
01394      *                  value is longer than the size of the supplied buffer,
01395      *                  this variable will return the total attribute value length
01396      *                  (excluding offset). The application may use this
01397      *                  information to allocate a suitable buffer size.
01398      *
01399      * @return BLE_ERROR_NONE if a value was read successfully into the buffer.
01400      *
01401      * @note This API is a version of the above, with an additional connection handle
01402      *     parameter to allow fetches for connection-specific multivalued
01403      *     attributes (such as the CCCDs).
01404      *
01405      * @deprecated You should use the parallel API from GattServer directly, refer to
01406      *             GattServer::read(Gap::Handle_t,GattAttribute::Handle_t,uint8_t,uint16_t).
01407      *             A former call to ble.readCharacteristicValue() should be replaced with
01408      *             ble.gattServer().read().
01409      */
01410     MBED_DEPRECATED("Use ble.gattServer().read(...)")
01411     ble_error_t readCharacteristicValue(
01412         Gap::Handle_t connectionHandle,
01413         GattAttribute::Handle_t attributeHandle,
01414         uint8_t *buffer,
01415         uint16_t *lengthP
01416     )
01417     {
01418         return gattServer().read(connectionHandle, attributeHandle, buffer, lengthP);
01419     }
01420 
01421     /**
01422      * Update the value of a characteristic on the local GattServer.
01423      *
01424      * @param[in] attributeHandle
01425      *              Handle for the value attribute of the characteristic.
01426      * @param[in] value
01427      *              A pointer to a buffer holding the new value.
01428      * @param[in] size
01429      *              Size of the new value (in bytes).
01430      * @param[in] localOnly
01431      *              Should this update be kept on the local
01432      *              GattServer regardless of the state of the
01433      *              notify/indicate flag in the CCCD for this
01434      *              characteristic? If set to true, no notification
01435      *              or indication is generated.
01436      *
01437      * @return BLE_ERROR_NONE if we have successfully set the value of the attribute.
01438      *
01439      * @deprecated You should use the parallel API from GattServer directly and refer to
01440      *             GattServer::write(GattAttribute::Handle_t,const uint8_t,uint16_t,bool).
01441      *             A former call to ble.updateCharacteristicValue() should be replaced with
01442      *             ble.gattServer().write().
01443      */
01444     MBED_DEPRECATED("Use ble.gattServer().write(...)")
01445     ble_error_t updateCharacteristicValue(
01446         GattAttribute::Handle_t attributeHandle,
01447         const uint8_t *value,
01448         uint16_t size,
01449         bool localOnly = false
01450     )
01451     {
01452         return gattServer().write(attributeHandle, value, size, localOnly);
01453     }
01454 
01455     /**
01456      * Update the value of a characteristic on the local GattServer. A version
01457      * of the above, with a connection handle parameter to allow updates
01458      * for connection-specific multivalued attributes (such as the CCCDs).
01459      *
01460      * @param[in] connectionHandle
01461      *              Connection Handle.
01462      * @param[in] attributeHandle
01463      *              Handle for the value attribute of the Characteristic.
01464      * @param[in] value
01465      *              A pointer to a buffer holding the new value.
01466      * @param[in] size
01467      *              Size of the new value (in bytes).
01468      * @param[in] localOnly
01469      *              Should this update be kept on the local
01470      *              GattServer regardless of the state of the
01471      *              notify/indicate flag in the CCCD for this
01472      *              Characteristic? If set to true, no notification
01473      *              or indication is generated.
01474      *
01475      * @return BLE_ERROR_NONE if we have successfully set the value of the attribute.
01476      *
01477      * @deprecated You should use the parallel API from GattServer directly and refer to
01478      *             GattServer::write(Gap::Handle_t,GattAttribute::Handle_t,const uint8_t,uint16_t,bool).
01479      *             A former call to ble.updateCharacteristicValue() should be replaced with
01480      *             ble.gattServer().write().
01481      */
01482     MBED_DEPRECATED("Use ble.gattServer().write(...)")
01483     ble_error_t updateCharacteristicValue(
01484         Gap::Handle_t connectionHandle,
01485         GattAttribute::Handle_t attributeHandle,
01486         const uint8_t *value,
01487         uint16_t size,
01488         bool localOnly = false
01489     )
01490     {
01491         return gattServer().write(connectionHandle, attributeHandle, value, size, localOnly);
01492     }
01493 #endif // BLE_FEATURE_GATT_SERVER
01494 
01495 #if BLE_FEATURE_SECURITY
01496     /**
01497      * Enable the BLE stack's Security Manager. The Security Manager implements
01498      * the cryptographic algorithms and protocol exchanges that allow two
01499      * devices to securely exchange data and privately detect each other.
01500      * Calling this API is a prerequisite for encryption and pairing (bonding).
01501      *
01502      * @param[in]  enableBonding Allow for bonding.
01503      * @param[in]  requireMITM   Require protection against man-in-the-middle attacks.
01504      * @param[in]  iocaps        To specify the I/O capabilities of this peripheral,
01505      *                           such as availability of a display or keyboard, to
01506      *                           support out-of-band exchanges of security data.
01507      * @param[in]  passkey       To specify a static passkey.
01508      *
01509      * @return BLE_ERROR_NONE on success.
01510      *
01511      * @deprecated You should use the parallel API from SecurityManager directly, refer to
01512      *             SecurityManager.init(). A former
01513      *             call to ble.initializeSecurity(...) should be replaced with
01514      *             ble.securityManager().init(...).
01515      */
01516     MBED_DEPRECATED("Use ble.securityManager().init(...)")
01517     ble_error_t initializeSecurity(
01518         bool enableBonding = true,
01519         bool requireMITM = true,
01520         SecurityManager::SecurityIOCapabilities_t iocaps = SecurityManager::IO_CAPS_NONE,
01521         const SecurityManager::Passkey_t passkey = NULL
01522     )
01523     {
01524         return securityManager().init(enableBonding, requireMITM, iocaps, passkey);
01525     }
01526 
01527     /**
01528      * Get the security status of a connection.
01529      *
01530      * @param[in]  connectionHandle   Handle to identify the connection.
01531      * @param[out] securityStatusP    Security status.
01532      *
01533      * @return BLE_SUCCESS or appropriate error code indicating the reason of failure.
01534      *
01535      * @deprecated You should use the parallel API from SecurityManager directly, refer to
01536      *             SecurityManager::getLinkSecurity(). A former
01537      *             call to ble.getLinkSecurity(...) should be replaced with
01538      *             ble.securityManager().getLinkSecurity(...).
01539      */
01540     MBED_DEPRECATED("ble.securityManager().getLinkSecurity(...)")
01541     ble_error_t getLinkSecurity(Gap::Handle_t connectionHandle, SecurityManager::LinkSecurityStatus_t *securityStatusP)
01542     {
01543         return securityManager().getLinkSecurity(connectionHandle, securityStatusP);
01544     }
01545 
01546     /**
01547      * Delete all peer device context and all related bonding information from
01548      * the database within the security manager.
01549      *
01550      * @retval BLE_ERROR_NONE             On success; else returns an error code indicating the reason for the failure.
01551      * @retval BLE_ERROR_INVALID_STATE    If the API is called without module initialization or
01552      *                                    application registration.
01553      *
01554      * @deprecated You should use the parallel API from SecurityManager directly and refer to
01555      *             SecurityManager::purgeAllBondingState(). A former
01556      *             call to ble.purgeAllBondingState() should be replaced with
01557      *             ble.securityManager().purgeAllBondingState().
01558      */
01559     MBED_DEPRECATED("ble.securityManager().purgeAllBondingState(...)")
01560     ble_error_t purgeAllBondingState(void)
01561     {
01562         return securityManager().purgeAllBondingState();
01563     }
01564 #endif // BLE_FEATURE_SECURITY
01565 
01566     /**
01567      * Set up a callback for timeout events. Refer to Gap::TimeoutSource_t for
01568      * possible event types.
01569      *
01570      * @param[in] timeoutCallback Event handler being registered.
01571      *
01572      * @deprecated You should use the parallel API from Gap directly and refer to
01573      *             Gap::onTimeout(). A former call
01574      *             to ble.onTimeout(callback) should be replaced with
01575      *             ble.gap().onTimeout(callback).
01576      */
01577     MBED_DEPRECATED("ble.gap().onTimeout(callback)")
01578     void onTimeout(Gap::TimeoutEventCallback_t timeoutCallback);
01579 
01580 #if BLE_FEATURE_CONNECTABLE
01581     /**
01582      * Set up a callback for connection events. Refer to Gap::ConnectionEventCallback_t.
01583      *
01584      * @param[in] connectionCallback Event handler being registered.
01585      *
01586      * @deprecated You should use the parallel API from Gap directly, refer to
01587      *             Gap::onConnection(). A former call
01588      *             to ble.onConnection(callback) should be replaced with
01589      *             ble.gap().onConnection(callback).
01590      */
01591     MBED_DEPRECATED("ble.gap().onConnection(callback)")
01592     void onConnection(Gap::ConnectionEventCallback_t connectionCallback);
01593 
01594     /**
01595      * Append to a chain of callbacks to be invoked upon GAP disconnection.
01596      *
01597      * @param[in] disconnectionCallback Event handler being registered.
01598      *
01599      * @deprecated You should use the parallel API from Gap directly and refer to
01600      *             Gap::onDisconnection(). A former call
01601      *             to ble.onDisconnection(callback) should be replaced with
01602      *             ble.gap().onDisconnection(callback).
01603      */
01604     MBED_DEPRECATED("ble.gap().onDisconnectionComplete(callback)")
01605     void onDisconnection(Gap::DisconnectionEventCallback_t disconnectionCallback);
01606 
01607     /**
01608      * The same as onDisconnection() but allows an object reference and member function
01609      * to be added to the chain of callbacks.
01610      *
01611      * @param[in] tptr Instance used to invoke mptr.
01612      * @param[in] mptr Event handler being registered.
01613      *
01614      * @deprecated You should use the parallel API from Gap directly and refer to
01615      *             Gap::onDisconnection(). A former call
01616      *             to ble.onDisconnection(callback) should be replaced with
01617      *             ble.gap().onDisconnection(callback).
01618      */
01619     template<typename T>
01620     MBED_DEPRECATED("ble.gap().onDisconnectionComplete(callback)")
01621     void onDisconnection(T *tptr, void (T::*mptr)(const Gap::DisconnectionCallbackParams_t *))
01622     {
01623         gap().onDisconnection(tptr, mptr);
01624     }
01625 #endif // BLE_FEATURE_CONNECTABLE
01626 
01627     /**
01628      * Radio Notification is a feature that enables ACTIVE and INACTIVE
01629      * (nACTIVE) signals from the stack. These notify the application when the
01630      * radio is in use. The signal is sent using software interrupt.
01631      *
01632      * The ACTIVE signal is sent before the radio event starts. The nACTIVE
01633      * signal is sent at the end of the radio event. These signals can be used
01634      * by the application programmer to synchronize application logic with radio
01635      * activity. For example, the ACTIVE signal can be used to shut off external
01636      * devices to manage peak current drawn during periods when the radio is on,
01637      * or to trigger sensor data collection for transmission in the radio event.
01638      *
01639      * @param callback
01640      *          The application handler to be invoked in response to a radio
01641      *          ACTIVE/INACTIVE event.
01642      *
01643      * @deprecated You should use the parallel API from Gap directly, refer to
01644      *             Gap::onRadioNotification(). A former call
01645      *             to ble.onRadioNotification(...) should be replaced with
01646      *             ble.gap().onRadioNotification(...).
01647      */
01648     MBED_DEPRECATED("ble.gap().onRadioNotification(...)")
01649     void onRadioNotification(void (*callback)(bool));
01650 
01651 #if BLE_FEATURE_GATT_SERVER
01652     /**
01653      * Add a callback for the GATT event DATA_SENT (which is triggered when
01654      * updates are sent out by GATT in the form of notifications).
01655      *
01656      * @param[in] callback Event handler being registered.
01657      *
01658      * @note It is possible to chain together multiple onDataSent callbacks
01659      * (potentially from different modules of an application) to receive updates
01660      * to characteristics.
01661      *
01662      * @note It is also possible to set up a callback into a member function of
01663      * some object.
01664      *
01665      * @deprecated You should use the parallel API from GattServer directly and refer to
01666      *             GattServer::onDataSent(). A former call
01667      *             to ble.onDataSent(...) should be replaced with
01668      *             ble.gattServer().onDataSent(...).
01669      */
01670     MBED_DEPRECATED("ble.gattServer().onDataSent(...)")
01671     void onDataSent(void (*callback)(unsigned count))
01672     {
01673         gattServer().onDataSent(callback);
01674     }
01675 
01676     /**
01677      * The same as onDataSent() but allows an object reference and member function
01678      * to be added to the chain of callbacks.
01679      *
01680      * @param[in] objPtr Pointer to the instance that is used to invoke the
01681      * event handler.
01682      * @param[in] memberPtr Event handler being registered. It is a member
01683      * function.
01684      *
01685      * @deprecated You should use the parallel API from GattServer directly and refer to
01686      *             GattServer::onDataSent(). A former call
01687      *             to ble.onDataSent(...) should be replaced with
01688      *             ble.gattServer().onDataSent(...).
01689      */
01690     template<typename T>
01691     MBED_DEPRECATED("ble.gattServer().onDataSent(...)")
01692     void onDataSent(T *objPtr, void (T::*memberPtr)(unsigned count))
01693     {
01694         gattServer().onDataSent(objPtr, memberPtr);
01695     }
01696 
01697     /**
01698      * Set up a callback for when an attribute has its value updated by or at the
01699      * connected peer. For a peripheral, this callback is triggered when the local
01700      * GATT server has an attribute updated by a write command from the peer.
01701      * For a Central, this callback is triggered when a response is received for
01702      * a write request.
01703      *
01704      * @param[in] callback The event handler being registered.
01705      *
01706      * @note It is possible to chain together multiple onDataWritten callbacks
01707      * (potentially from different modules of an application) to receive updates
01708      * to characteristics. Many services, such as DFU and UART, add their own
01709      * onDataWritten callbacks behind the scenes to trap interesting events.
01710      *
01711      * @note It is also possible to set up a callback into a member function of
01712      * some object.
01713      *
01714      * @deprecated You should use the parallel API from GattServer directly and refer to
01715      *             GattServer::onDataWritten(). A former call
01716      *             to ble.onDataWritten(...) should be replaced with
01717      *             ble.gattServer().onDataWritten(...).
01718      */
01719     MBED_DEPRECATED("ble.gattServer().onDataWritten(...)")
01720     void onDataWritten(void (*callback)(const GattWriteCallbackParams *eventDataP))
01721     {
01722         gattServer().onDataWritten(callback);
01723     }
01724 
01725     /**
01726      * The same as onDataWritten() but allows an object reference and member function
01727      * to be added to the chain of callbacks.
01728      *
01729      * @param[in] objPtr Pointer to the instance that is used to invoke the
01730      * event handler (@p memberPtr).
01731      * @param[in] memberPtr Event handler being registered. It is a member
01732      * function.
01733      *
01734      *
01735      * @deprecated You should use the parallel API from GattServer directly, refer to
01736      *             GattServer::onDataWritten(). A former call
01737      *             to ble.onDataWritten(...) should be replaced with
01738      *             ble.gattServer().onDataWritten(...).
01739      */
01740     template<typename T>
01741     MBED_DEPRECATED("ble.gattServer().onDataWritten(...)")
01742     void onDataWritten(T *objPtr, void (T::*memberPtr)(const GattWriteCallbackParams *context))
01743     {
01744         gattServer().onDataWritten(objPtr, memberPtr);
01745     }
01746 
01747     /**
01748      * Set up a callback to be invoked on the peripheral when an attribute is
01749      * being read by a remote client.
01750      *
01751      * @note This functionality may not be available on all underlying stacks.
01752      * You could use GattCharacteristic::setReadAuthorizationCallback() as an
01753      * alternative.
01754      *
01755      * @note It is possible to chain together multiple onDataRead callbacks
01756      * (potentially from different modules of an application) to receive updates
01757      * to characteristics. Services may add their own onDataRead callbacks
01758      * behind the scenes to trap interesting events.
01759      *
01760      * @note It is also possible to set up a callback into a member function of
01761      * some object.
01762      *
01763      * @param[in] callback Event handler being registered.
01764      *
01765      * @return BLE_ERROR_NOT_IMPLEMENTED if this functionality isn't available;
01766      *         else BLE_ERROR_NONE.
01767      *
01768      * @deprecated You should use the parallel API from GattServer directly and refer to
01769      *             GattServer::onDataRead(). A former call
01770      *             to ble.onDataRead(...) should be replaced with
01771      *             ble.gattServer().onDataRead(...).
01772      */
01773     MBED_DEPRECATED("ble.gattServer().onDataRead(...)")
01774     ble_error_t onDataRead(void (*callback)(const GattReadCallbackParams *eventDataP))
01775     {
01776         return gattServer().onDataRead(callback);
01777     }
01778 
01779     /**
01780      * The same as onDataRead() but allows an object reference and member function
01781      * to be added to the chain of callbacks.
01782      *
01783      * @param[in] objPtr Pointer to the instance that is used to invoke the
01784      * event handler (@p memberPtr).
01785      * @param[in] memberPtr Event handler being registered. It is a member
01786      * function.
01787      *
01788      * @return BLE_ERROR_NOT_IMPLEMENTED if this functionality isn't available;
01789      *         else BLE_ERROR_NONE.
01790      *
01791      * @deprecated You should use the parallel API from GattServer directly and refer to
01792      *             GattServer::onDataRead(). A former call
01793      *             to ble.onDataRead(...) should be replaced with
01794      *             ble.gattServer().onDataRead(...).
01795      */
01796     template<typename T>
01797     MBED_DEPRECATED("ble.gattServer().onDataRead(...)")
01798     ble_error_t onDataRead(T *objPtr, void (T::*memberPtr)(const GattReadCallbackParams *context))
01799     {
01800         return gattServer().onDataRead(objPtr, memberPtr);
01801     }
01802 
01803     /**
01804      * Set up a callback for when notifications or indications are enabled for a
01805      * characteristic on the local GattServer.
01806      *
01807      * @param[in] callback Event handler being registered.
01808      *
01809      * @deprecated You should use the parallel API from GattServer directly and refer to
01810      *             GattServer::onUpdatesEnabled(). A former call
01811      *             to ble.onUpdatesEnabled(callback) should be replaced with
01812      *             ble.gattServer().onUpdatesEnabled(callback).
01813      */
01814     MBED_DEPRECATED("ble.gattServer().onUpdatesEnabled(...)")
01815     void onUpdatesEnabled(GattServer::EventCallback_t callback)
01816     {
01817         gattServer().onUpdatesEnabled(callback);
01818     }
01819 
01820     /**
01821      * Set up a callback for when notifications or indications are disabled for a
01822      * characteristic on the local GattServer.
01823      *
01824      * @param[in] callback Event handler being registered.
01825      *
01826      * @deprecated You should use the parallel API from GattServer directly and refer to
01827      *             GattServer::onUpdatesDisabled(). A former call
01828      *             to ble.onUpdatesDisabled(callback) should be replaced with
01829      *             ble.gattServer().onUpdatesDisabled(callback).
01830      */
01831     MBED_DEPRECATED("ble.gattServer().onUpdatesDisabled(...)")
01832     void onUpdatesDisabled(GattServer::EventCallback_t callback)
01833     {
01834         gattServer().onUpdatesDisabled(callback);
01835     }
01836 
01837     /**
01838      * Set up a callback for when the GATT server receives a response for an
01839      * indication event sent previously.
01840      *
01841      * @param[in] callback Event handler being registered.
01842      *
01843      * @deprecated You should use the parallel API from GattServer directly and refer to
01844      *             GattServer::onConfirmationReceived(). A former call
01845      *             to ble.onConfirmationReceived(callback) should be replaced with
01846      *             ble.gattServer().onConfirmationReceived(callback).
01847      */
01848     MBED_DEPRECATED("ble.gattServer().onConfirmationReceived(...)")
01849     void onConfirmationReceived(GattServer::EventCallback_t callback)
01850     {
01851         gattServer().onConfirmationReceived(callback);
01852     }
01853 #endif // BLE_FEATURE_GATT_SERVER
01854 
01855 #if BLE_FEATURE_SECURITY
01856     /**
01857      * Set up a callback for when the security setup procedure (key generation
01858      * and exchange) for a link has started. This will be skipped for bonded
01859      * devices. The callback is passed in parameters received from the peer's
01860      * security request: bool allowBonding, bool requireMITM and
01861      * SecurityIOCapabilities_t.
01862      *
01863      * @param[in] callback Event handler being registered.
01864      *
01865      * @deprecated You should use the parallel API from SecurityManager directly and refer to
01866      *             SecurityManager::onSecuritySetupInitiated(). A former
01867      *             call to ble.onSecuritySetupInitiated(callback) should be replaced with
01868      *             ble.securityManager().onSecuritySetupInitiated(callback).
01869      */
01870     MBED_DEPRECATED("ble.securityManager().onSecuritySetupInitiated(callback)")
01871     void onSecuritySetupInitiated(SecurityManager::SecuritySetupInitiatedCallback_t callback)
01872     {
01873         securityManager().onSecuritySetupInitiated(callback);
01874     }
01875 
01876     /**
01877      * Set up a callback for when the security setup procedure (key generation
01878      * and exchange) for a link has completed. This will be skipped for bonded
01879      * devices. The callback is passed in the success/failure status of the
01880      * security setup procedure.
01881      *
01882      * @param[in] callback Event handler being registered.
01883      *
01884      * @deprecated You should use the parallel API from SecurityManager directly and refer to
01885      *             SecurityManager::onSecuritySetupCompleted(). A former
01886      *             call to ble.onSecuritySetupCompleted(callback) should be replaced with
01887      *             ble.securityManager().onSecuritySetupCompleted(callback).
01888      */
01889     MBED_DEPRECATED("ble.securityManager().onSecuritySetupCompleted(callback)")
01890     void onSecuritySetupCompleted(SecurityManager::SecuritySetupCompletedCallback_t callback)
01891     {
01892         securityManager().onSecuritySetupCompleted(callback);
01893     }
01894 
01895     /**
01896      * Set up a callback for when a link with the peer is secured. For bonded
01897      * devices, subsequent reconnections with a bonded peer will result only in
01898      * this callback when the link is secured, and setup procedures will not
01899      * occur unless the bonding information is either lost or deleted on either
01900      * or both sides. The callback is passed in a SecurityManager::SecurityMode_t according
01901      * to the level of security in effect for the secured link.
01902      *
01903      * @param[in] callback Event handler being registered.
01904      *
01905      * @deprecated You should use the parallel API from SecurityManager directly and refer to
01906      *             SecurityManager::onLinkSecured(). A former
01907      *             call to ble.onLinkSecured(callback) should be replaced with
01908      *             ble.securityManager().onLinkSecured(callback).
01909      */
01910     MBED_DEPRECATED("ble.securityManager().onLinkSecured(callback)")
01911     void onLinkSecured(SecurityManager::LinkSecuredCallback_t callback)
01912     {
01913         securityManager().onLinkSecured(callback);
01914     }
01915 
01916     /**
01917      * Set up a callback for successful bonding, meaning that link-specific security
01918      * context is stored persistently for a peer device.
01919      *
01920      * @param[in] callback Event handler being registered.
01921      *
01922      * @deprecated You should use the parallel API from SecurityManager directly and refer to
01923      *             SecurityManager::onSecurityContextStored(). A former
01924      *             call to ble.onSecurityContextStored(callback) should be replaced with
01925      *             ble.securityManager().onSecurityContextStored(callback).
01926      */
01927     MBED_DEPRECATED("ble.securityManager().onSecurityContextStored(callback)")
01928     void onSecurityContextStored(SecurityManager::HandleSpecificEvent_t callback)
01929     {
01930         securityManager().onSecurityContextStored(callback);
01931     }
01932 
01933     /**
01934      * Set up a callback for when the passkey needs to be displayed on a
01935      * peripheral with DISPLAY capability. This happens when security is
01936      * configured to prevent man-in-the-middle attacks, and the peers need to exchange
01937      * a passkey (or PIN) to authenticate the connection
01938      * attempt.
01939      *
01940      * @param[in] callback Event handler being registered.
01941      *
01942      * @deprecated You should use the parallel API from SecurityManager directly and refer to
01943      *             SecurityManager::onPasskeyDisplay(). A former
01944      *             call to ble.onPasskeyDisplay(callback) should be replaced with
01945      *             ble.securityManager().onPasskeyDisplay(callback).
01946      */
01947     MBED_DEPRECATED("ble.securityManager().onPasskeyDisplay(callback)")
01948     void onPasskeyDisplay(SecurityManager::PasskeyDisplayCallback_t callback)
01949     {
01950         return securityManager().onPasskeyDisplay(callback);
01951     }
01952 #endif // BLE_FEATURE_SECURITY
01953 
01954 private:
01955     friend class BLEInstanceBase;
01956 
01957     /**
01958      * This function allows the BLE stack to signal that there is work to do and
01959      * event processing should be done (BLE::processEvent()).
01960      *
01961      * @note This function should be called by the port of BLE_API. It is not
01962      * meant to be used by end users.
01963      */
01964     void signalEventsToProcess();
01965 
01966     /**
01967      * Implementation of init() [internal to BLE_API].
01968      *
01969      * The implementation is separated into a private method because it isn't
01970      * suitable to be included in the header.
01971      */
01972     ble_error_t initImplementation(
01973         FunctionPointerWithContext<InitializationCompleteCallbackContext *> callback
01974     );
01975 
01976 private:
01977     // Prevent copy construction and copy assignment of BLE.
01978     BLE(const BLE &);
01979 
01980     BLE &operator=(const BLE &);
01981 
01982 private:
01983     InstanceID_t instanceID;
01984     BLEInstanceBase *transport; /* The device-specific backend */
01985     OnEventsToProcessCallback_t whenEventsToProcess;
01986     bool event_signaled;
01987 };
01988 
01989 /**
01990  * @deprecated This type alias is retained for the sake of compatibility with
01991  * older code. This will be dropped at some point.
01992  */
01993 typedef BLE BLEDevice ;
01994 
01995 /**
01996  * @namespace ble Entry namespace for all %BLE API definitions.
01997  */
01998 
01999 /**
02000  * @}
02001  */
02002 
02003 #endif /* ifndef MBED_BLE_H__ */