mbed official / mbed

The official Mbed 2 C/C++ SDK provides the software platform and libraries to build your applications.

Dependents:   hello SerialTestv11 SerialTestv12 Sierpinski ... more

mbed 2

This is the mbed 2 library. If you'd like to learn about Mbed OS please see the mbed-os docs.

TARGET_SDT51822B/TOOLCHAIN_GCC_ARM/ble_conn_params.h@172:65be27845400, 2019-02-20 (annotated)

Committer:
AnnaBridge
Date:
Wed Feb 20 20:53:29 2019 +0000
Revision:
172:65be27845400
Parent:
171:3a7713b1edbc 
mbed library release version 165

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Kojto 148:fd96258d940d 1 /*
Kojto 148:fd96258d940d 2 * Copyright (c) 2012 Nordic Semiconductor ASA
Kojto 148:fd96258d940d 3 * All rights reserved.
Kojto 148:fd96258d940d 4 *
Kojto 148:fd96258d940d 5 * Redistribution and use in source and binary forms, with or without modification,
Kojto 148:fd96258d940d 6 * are permitted provided that the following conditions are met:
Kojto 148:fd96258d940d 7 *
Kojto 148:fd96258d940d 8 * 1. Redistributions of source code must retain the above copyright notice, this list
Kojto 148:fd96258d940d 9 * of conditions and the following disclaimer.
Kojto 148:fd96258d940d 10 *
Kojto 148:fd96258d940d 11 * 2. Redistributions in binary form, except as embedded into a Nordic Semiconductor ASA
Kojto 148:fd96258d940d 12 * integrated circuit in a product or a software update for such product, must reproduce
Kojto 148:fd96258d940d 13 * the above copyright notice, this list of conditions and the following disclaimer in
Kojto 148:fd96258d940d 14 * the documentation and/or other materials provided with the distribution.
Kojto 148:fd96258d940d 15 *
Kojto 148:fd96258d940d 16 * 3. Neither the name of Nordic Semiconductor ASA nor the names of its contributors may be
Kojto 148:fd96258d940d 17 * used to endorse or promote products derived from this software without specific prior
Kojto 148:fd96258d940d 18 * written permission.
Kojto 148:fd96258d940d 19 *
Kojto 148:fd96258d940d 20 * 4. This software, with or without modification, must only be used with a
Kojto 148:fd96258d940d 21 * Nordic Semiconductor ASA integrated circuit.
Kojto 148:fd96258d940d 22 *
Kojto 148:fd96258d940d 23 * 5. Any software provided in binary or object form under this license must not be reverse
Kojto 148:fd96258d940d 24 * engineered, decompiled, modified and/or disassembled.
Kojto 148:fd96258d940d 25 *
Kojto 148:fd96258d940d 26 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
Kojto 148:fd96258d940d 27 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
Kojto 148:fd96258d940d 28 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
Kojto 148:fd96258d940d 29 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
Kojto 148:fd96258d940d 30 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
Kojto 148:fd96258d940d 31 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
Kojto 148:fd96258d940d 32 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
Kojto 148:fd96258d940d 33 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
Kojto 148:fd96258d940d 34 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
Kojto 148:fd96258d940d 35 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Kojto 148:fd96258d940d 36 *
Kojto 148:fd96258d940d 37 */
Kojto 148:fd96258d940d 38
Kojto 148:fd96258d940d 39
Kojto 148:fd96258d940d 40 /** @file
Kojto 148:fd96258d940d 41 *
Kojto 148:fd96258d940d 42 * @defgroup ble_sdk_lib_conn_params Connection Parameters Negotiation
Kojto 148:fd96258d940d 43 * @{
Kojto 148:fd96258d940d 44 * @ingroup ble_sdk_lib
Kojto 148:fd96258d940d 45 * @brief Module for initiating and executing a connection parameters negotiation procedure.
Kojto 148:fd96258d940d 46 */
Kojto 148:fd96258d940d 47
Kojto 148:fd96258d940d 48 #ifndef BLE_CONN_PARAMS_H__
Kojto 148:fd96258d940d 49 #define BLE_CONN_PARAMS_H__
Kojto 148:fd96258d940d 50
Kojto 148:fd96258d940d 51 #include <stdint.h>
Kojto 148:fd96258d940d 52 #include "nrf_ble.h"
Kojto 148:fd96258d940d 53 #include "ble_srv_common.h"
Kojto 148:fd96258d940d 54
Kojto 148:fd96258d940d 55 /**@brief Connection Parameters Module event type. */
Kojto 148:fd96258d940d 56 typedef enum
Kojto 148:fd96258d940d 57 {
Kojto 148:fd96258d940d 58 BLE_CONN_PARAMS_EVT_FAILED , /**< Negotiation procedure failed. */
Kojto 148:fd96258d940d 59 BLE_CONN_PARAMS_EVT_SUCCEEDED /**< Negotiation procedure succeeded. */
Kojto 148:fd96258d940d 60 } ble_conn_params_evt_type_t;
Kojto 148:fd96258d940d 61
Kojto 148:fd96258d940d 62 /**@brief Connection Parameters Module event. */
Kojto 148:fd96258d940d 63 typedef struct
Kojto 148:fd96258d940d 64 {
Kojto 148:fd96258d940d 65 ble_conn_params_evt_type_t evt_type; /**< Type of event. */
Kojto 148:fd96258d940d 66 } ble_conn_params_evt_t;
Kojto 148:fd96258d940d 67
Kojto 148:fd96258d940d 68 /**@brief Connection Parameters Module event handler type. */
Kojto 148:fd96258d940d 69 typedef void (*ble_conn_params_evt_handler_t) (ble_conn_params_evt_t * p_evt);
Kojto 148:fd96258d940d 70
Kojto 148:fd96258d940d 71 /**@brief Connection Parameters Module init structure. This contains all options and data needed for
Kojto 148:fd96258d940d 72 * initialization of the connection parameters negotiation module. */
Kojto 148:fd96258d940d 73 typedef struct
Kojto 148:fd96258d940d 74 {
Kojto 148:fd96258d940d 75 ble_gap_conn_params_t * p_conn_params; /**< Pointer to the connection parameters desired by the application. When calling ble_conn_params_init, if this parameter is set to NULL, the connection parameters will be fetched from host. */
Kojto 148:fd96258d940d 76 uint32_t first_conn_params_update_delay; /**< Time from initiating event (connect or start of notification) to first time sd_ble_gap_conn_param_update is called (in number of timer ticks). */
Kojto 148:fd96258d940d 77 uint32_t next_conn_params_update_delay; /**< Time between each call to sd_ble_gap_conn_param_update after the first (in number of timer ticks). Recommended value 30 seconds as per BLUETOOTH SPECIFICATION Version 4.0. */
Kojto 148:fd96258d940d 78 uint8_t max_conn_params_update_count; /**< Number of attempts before giving up the negotiation. */
Kojto 148:fd96258d940d 79 uint16_t start_on_notify_cccd_handle; /**< If procedure is to be started when notification is started, set this to the handle of the corresponding CCCD. Set to BLE_GATT_HANDLE_INVALID if procedure is to be started on connect event. */
Kojto 148:fd96258d940d 80 bool disconnect_on_fail; /**< Set to TRUE if a failed connection parameters update shall cause an automatic disconnection, set to FALSE otherwise. */
Kojto 148:fd96258d940d 81 ble_conn_params_evt_handler_t evt_handler; /**< Event handler to be called for handling events in the Connection Parameters. */
Kojto 148:fd96258d940d 82 ble_srv_error_handler_t error_handler; /**< Function to be called in case of an error. */
Kojto 148:fd96258d940d 83 } ble_conn_params_init_t;
Kojto 148:fd96258d940d 84
Kojto 148:fd96258d940d 85
Kojto 148:fd96258d940d 86 /**@brief Function for initializing the Connection Parameters module.
Kojto 148:fd96258d940d 87 *
Kojto 148:fd96258d940d 88 * @note If the negotiation procedure should be triggered when notification/indication of
Kojto 148:fd96258d940d 89 * any characteristic is enabled by the peer, then this function must be called after
Kojto 148:fd96258d940d 90 * having initialized the services.
Kojto 148:fd96258d940d 91 *
Kojto 148:fd96258d940d 92 * @param[in] p_init This contains information needed to initialize this module.
Kojto 148:fd96258d940d 93 *
Kojto 148:fd96258d940d 94 * @return NRF_SUCCESS on successful initialization, otherwise an error code.
Kojto 148:fd96258d940d 95 */
Kojto 148:fd96258d940d 96 uint32_t ble_conn_params_init(const ble_conn_params_init_t * p_init);
Kojto 148:fd96258d940d 97
Kojto 148:fd96258d940d 98 /**@brief Function for stopping the Connection Parameters module.
Kojto 148:fd96258d940d 99 *
Kojto 148:fd96258d940d 100 * @details This function is intended to be used by the application to clean up the connection
Kojto 148:fd96258d940d 101 * parameters update module. This will stop the connection parameters update timer if
Kojto 148:fd96258d940d 102 * running, thereby preventing any impending connection parameters update procedure. This
Kojto 148:fd96258d940d 103 * function must be called by the application when it needs to clean itself up (for
Kojto 148:fd96258d940d 104 * example, before disabling the bluetooth SoftDevice) so that an unwanted timer expiry
Kojto 148:fd96258d940d 105 * event can be avoided.
Kojto 148:fd96258d940d 106 *
Kojto 148:fd96258d940d 107 * @return NRF_SUCCESS on successful initialization, otherwise an error code.
Kojto 148:fd96258d940d 108 */
Kojto 148:fd96258d940d 109 uint32_t ble_conn_params_stop(void);
Kojto 148:fd96258d940d 110
Kojto 148:fd96258d940d 111 /**@brief Function for changing the current connection parameters to a new set.
Kojto 148:fd96258d940d 112 *
Kojto 148:fd96258d940d 113 * @details Use this function to change the connection parameters to a new set of parameter
Kojto 148:fd96258d940d 114 * (ie different from the ones given at init of the module).
Kojto 148:fd96258d940d 115 * This function is usefull for scenario where most of the time the application
Kojto 148:fd96258d940d 116 * needs a relatively big connection interval, and just sometimes, for a temporary
Kojto 148:fd96258d940d 117 * period requires shorter connection interval, for example to transfer a higher
Kojto 148:fd96258d940d 118 * amount of data.
Kojto 148:fd96258d940d 119 * If the given parameters does not match the current connection's parameters
Kojto 148:fd96258d940d 120 * this function initiates a new negotiation.
Kojto 148:fd96258d940d 121 *
Kojto 148:fd96258d940d 122 * @param[in] new_params This contains the new connections parameters to setup.
Kojto 148:fd96258d940d 123 *
Kojto 148:fd96258d940d 124 * @return NRF_SUCCESS on successful initialization, otherwise an error code.
Kojto 148:fd96258d940d 125 */
Kojto 148:fd96258d940d 126 uint32_t ble_conn_params_change_conn_params(ble_gap_conn_params_t *new_params);
Kojto 148:fd96258d940d 127
Kojto 148:fd96258d940d 128 /**@brief Function for handling the Application's BLE Stack events.
Kojto 148:fd96258d940d 129 *
Kojto 148:fd96258d940d 130 * @details Handles all events from the BLE stack that are of interest to this module.
Kojto 148:fd96258d940d 131 *
Kojto 148:fd96258d940d 132 * @param[in] p_ble_evt The event received from the BLE stack.
Kojto 148:fd96258d940d 133 */
Kojto 148:fd96258d940d 134 void ble_conn_params_on_ble_evt(ble_evt_t * p_ble_evt);
Kojto 148:fd96258d940d 135
Kojto 148:fd96258d940d 136 #endif // BLE_CONN_PARAMS_H__
Kojto 148:fd96258d940d 137
Kojto 148:fd96258d940d 138 /** @} */