Glimworm Beacons / nRF51822

test

Fork of nRF51822 by Nordic Semiconductor

source/nordic-sdk/components/ble/common/ble_conn_params.h@448:b71e96a821de, 2015-10-10 (annotated)

Committer:
GlimwormBeacons
Date:
Sat Oct 10 09:19:50 2015 +0000
Revision:
448:b71e96a821de
Parent:
387:b13ab9a7ddb9 
test

Who changed what in which revision?

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