Microbug / nRF51822_FOTA

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Fork of nRF51822 by Nordic Semiconductor

nordic-sdk/components/softdevice/s110/headers/ble.h@112:737b08b3b995, 2015-04-30 (annotated)

Committer:
rgrover1
Date:
Thu Apr 30 08:34:37 2015 +0100
Revision:
112:737b08b3b995
Parent:
103:138bdc859cc9 
Synchronized with git rev 4ae92f89

Author: Rohit Grover

porting to v8.0 of the SDK

Who changed what in which revision?

UserRevisionLine numberNew contents of line
rgrover1 112:737b08b3b995 1 /*
rgrover1 112:737b08b3b995 2 * Copyright (c) Nordic Semiconductor ASA
rgrover1 112:737b08b3b995 3 * All rights reserved.
rgrover1 112:737b08b3b995 4 *
rgrover1 112:737b08b3b995 5 * Redistribution and use in source and binary forms, with or without modification,
rgrover1 112:737b08b3b995 6 * are permitted provided that the following conditions are met:
rgrover1 112:737b08b3b995 7 *
rgrover1 112:737b08b3b995 8 * 1. Redistributions of source code must retain the above copyright notice, this
rgrover1 112:737b08b3b995 9 * list of conditions and the following disclaimer.
rgrover1 112:737b08b3b995 10 *
rgrover1 112:737b08b3b995 11 * 2. Redistributions in binary form must reproduce the above copyright notice, this
rgrover1 112:737b08b3b995 12 * list of conditions and the following disclaimer in the documentation and/or
rgrover1 112:737b08b3b995 13 * other materials provided with the distribution.
rgrover1 112:737b08b3b995 14 *
rgrover1 112:737b08b3b995 15 * 3. Neither the name of Nordic Semiconductor ASA nor the names of other
rgrover1 112:737b08b3b995 16 * contributors to this software may be used to endorse or promote products
rgrover1 112:737b08b3b995 17 * derived from this software without specific prior written permission.
rgrover1 112:737b08b3b995 18 *
rgrover1 112:737b08b3b995 19 * 4. This software must only be used in a processor manufactured by Nordic
rgrover1 112:737b08b3b995 20 * Semiconductor ASA, or in a processor manufactured by a third party that
rgrover1 112:737b08b3b995 21 * is used in combination with a processor manufactured by Nordic Semiconductor.
rgrover1 112:737b08b3b995 22 *
rgrover1 112:737b08b3b995 23 *
rgrover1 112:737b08b3b995 24 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
rgrover1 112:737b08b3b995 25 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
rgrover1 112:737b08b3b995 26 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
rgrover1 112:737b08b3b995 27 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
rgrover1 112:737b08b3b995 28 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
rgrover1 112:737b08b3b995 29 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
rgrover1 112:737b08b3b995 30 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
rgrover1 112:737b08b3b995 31 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
rgrover1 112:737b08b3b995 32 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
rgrover1 112:737b08b3b995 33 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
rgrover1 112:737b08b3b995 34 *
rgrover1 103:138bdc859cc9 35 */
rgrover1 112:737b08b3b995 36
rgrover1 103:138bdc859cc9 37 /**
rgrover1 103:138bdc859cc9 38 @addtogroup BLE_COMMON BLE SoftDevice Common
rgrover1 103:138bdc859cc9 39 @{
rgrover1 103:138bdc859cc9 40 @defgroup ble_api Events, type definitions and API calls
rgrover1 103:138bdc859cc9 41 @{
rgrover1 103:138bdc859cc9 42
rgrover1 112:737b08b3b995 43 @brief Module independent events, type definitions and API calls for the BLE SoftDevice.
rgrover1 103:138bdc859cc9 44
rgrover1 103:138bdc859cc9 45 */
rgrover1 103:138bdc859cc9 46
rgrover1 103:138bdc859cc9 47 #ifndef BLE_H__
rgrover1 103:138bdc859cc9 48 #define BLE_H__
rgrover1 103:138bdc859cc9 49
rgrover1 103:138bdc859cc9 50 #include "ble_ranges.h"
rgrover1 103:138bdc859cc9 51 #include "ble_types.h"
rgrover1 103:138bdc859cc9 52 #include "ble_gap.h"
rgrover1 103:138bdc859cc9 53 #include "ble_l2cap.h"
rgrover1 103:138bdc859cc9 54 #include "ble_gatt.h"
rgrover1 103:138bdc859cc9 55 #include "ble_gattc.h"
rgrover1 103:138bdc859cc9 56 #include "ble_gatts.h"
rgrover1 103:138bdc859cc9 57
rgrover1 103:138bdc859cc9 58 /** @addtogroup BLE_COMMON_ENUMERATIONS Enumerations
rgrover1 103:138bdc859cc9 59 * @{ */
rgrover1 103:138bdc859cc9 60
rgrover1 103:138bdc859cc9 61 /**
rgrover1 103:138bdc859cc9 62 * @brief Common API SVC numbers.
rgrover1 103:138bdc859cc9 63 */
rgrover1 103:138bdc859cc9 64 enum BLE_COMMON_SVCS
rgrover1 103:138bdc859cc9 65 {
rgrover1 103:138bdc859cc9 66 SD_BLE_ENABLE = BLE_SVC_BASE, /**< Enable and initialize the BLE stack */
rgrover1 103:138bdc859cc9 67 SD_BLE_EVT_GET, /**< Get an event from the pending events queue. */
rgrover1 112:737b08b3b995 68 SD_BLE_TX_BUFFER_COUNT_GET, /**< Get the total number of available application transmission buffers from the BLE stack. */
rgrover1 103:138bdc859cc9 69 SD_BLE_UUID_VS_ADD, /**< Add a Vendor Specific UUID. */
rgrover1 103:138bdc859cc9 70 SD_BLE_UUID_DECODE, /**< Decode UUID bytes. */
rgrover1 103:138bdc859cc9 71 SD_BLE_UUID_ENCODE, /**< Encode UUID bytes. */
rgrover1 103:138bdc859cc9 72 SD_BLE_VERSION_GET, /**< Get the local version information (company id, Link Layer Version, Link Layer Subversion). */
rgrover1 103:138bdc859cc9 73 SD_BLE_USER_MEM_REPLY, /**< User Memory Reply. */
rgrover1 103:138bdc859cc9 74 SD_BLE_OPT_SET, /**< Set a BLE option. */
rgrover1 103:138bdc859cc9 75 SD_BLE_OPT_GET, /**< Get a BLE option. */
rgrover1 103:138bdc859cc9 76 };
rgrover1 103:138bdc859cc9 77
rgrover1 112:737b08b3b995 78 /**
rgrover1 112:737b08b3b995 79 * @brief BLE Module Independent Event IDs.
rgrover1 112:737b08b3b995 80 */
rgrover1 112:737b08b3b995 81 enum BLE_COMMON_EVTS
rgrover1 112:737b08b3b995 82 {
rgrover1 112:737b08b3b995 83 BLE_EVT_TX_COMPLETE = BLE_EVT_BASE, /**< Transmission Complete. @ref ble_evt_tx_complete_t */
rgrover1 112:737b08b3b995 84 BLE_EVT_USER_MEM_REQUEST, /**< User Memory request. @ref ble_evt_user_mem_request_t */
rgrover1 112:737b08b3b995 85 BLE_EVT_USER_MEM_RELEASE /**< User Memory release. @ref ble_evt_user_mem_release_t */
rgrover1 112:737b08b3b995 86 };
rgrover1 112:737b08b3b995 87
rgrover1 103:138bdc859cc9 88 /**@brief Common Option IDs.
rgrover1 103:138bdc859cc9 89 * IDs that uniquely identify a common option.
rgrover1 103:138bdc859cc9 90 */
rgrover1 103:138bdc859cc9 91 enum BLE_COMMON_OPTS
rgrover1 103:138bdc859cc9 92 {
rgrover1 103:138bdc859cc9 93 BLE_COMMON_OPT_RADIO_CPU_MUTEX = BLE_OPT_BASE /**< Radio CPU mutex option. @ref ble_common_opt_radio_cpu_mutex_t */
rgrover1 103:138bdc859cc9 94 };
rgrover1 103:138bdc859cc9 95 /** @} */
rgrover1 103:138bdc859cc9 96
rgrover1 103:138bdc859cc9 97 /** @addtogroup BLE_COMMON_DEFINES Defines
rgrover1 103:138bdc859cc9 98 * @{ */
rgrover1 103:138bdc859cc9 99
rgrover1 103:138bdc859cc9 100 /** @brief Required pointer alignment for BLE Events.
rgrover1 103:138bdc859cc9 101 */
rgrover1 103:138bdc859cc9 102 #define BLE_EVTS_PTR_ALIGNMENT 4
rgrover1 103:138bdc859cc9 103
rgrover1 103:138bdc859cc9 104 /** @defgroup BLE_USER_MEM_TYPES User Memory Types
rgrover1 103:138bdc859cc9 105 * @{ */
rgrover1 103:138bdc859cc9 106 #define BLE_USER_MEM_TYPE_INVALID 0x00 /**< Invalid User Memory Types. */
rgrover1 103:138bdc859cc9 107 #define BLE_USER_MEM_TYPE_GATTS_QUEUED_WRITES 0x01 /**< User Memory for GATTS queued writes. */
rgrover1 103:138bdc859cc9 108 /** @} */
rgrover1 103:138bdc859cc9 109
rgrover1 103:138bdc859cc9 110 /** @brief Maximum number of Vendor Specific UUIDs.
rgrover1 103:138bdc859cc9 111 */
rgrover1 103:138bdc859cc9 112 #define BLE_UUID_VS_MAX_COUNT 10
rgrover1 103:138bdc859cc9 113
rgrover1 103:138bdc859cc9 114 /** @} */
rgrover1 103:138bdc859cc9 115
rgrover1 103:138bdc859cc9 116 /** @addtogroup BLE_COMMON_STRUCTURES Structures
rgrover1 103:138bdc859cc9 117 * @{ */
rgrover1 103:138bdc859cc9 118
rgrover1 103:138bdc859cc9 119 /**@brief User Memory Block. */
rgrover1 103:138bdc859cc9 120 typedef struct
rgrover1 103:138bdc859cc9 121 {
rgrover1 112:737b08b3b995 122 uint8_t *p_mem; /**< Pointer to the start of the user memory block. */
rgrover1 103:138bdc859cc9 123 uint16_t len; /**< Length in bytes of the user memory block. */
rgrover1 103:138bdc859cc9 124 } ble_user_mem_block_t;
rgrover1 103:138bdc859cc9 125
rgrover1 103:138bdc859cc9 126 /**
rgrover1 112:737b08b3b995 127 * @brief Event structure for @ref BLE_EVT_TX_COMPLETE.
rgrover1 103:138bdc859cc9 128 */
rgrover1 103:138bdc859cc9 129 typedef struct
rgrover1 103:138bdc859cc9 130 {
rgrover1 103:138bdc859cc9 131 uint8_t count; /**< Number of packets transmitted. */
rgrover1 103:138bdc859cc9 132 } ble_evt_tx_complete_t;
rgrover1 103:138bdc859cc9 133
rgrover1 112:737b08b3b995 134 /**@brief Event structure for @ref BLE_EVT_USER_MEM_REQUEST. */
rgrover1 103:138bdc859cc9 135 typedef struct
rgrover1 103:138bdc859cc9 136 {
rgrover1 103:138bdc859cc9 137 uint8_t type; /**< User memory type, see @ref BLE_USER_MEM_TYPES. */
rgrover1 103:138bdc859cc9 138 } ble_evt_user_mem_request_t;
rgrover1 103:138bdc859cc9 139
rgrover1 112:737b08b3b995 140 /**@brief Event structure for @ref BLE_EVT_USER_MEM_RELEASE. */
rgrover1 103:138bdc859cc9 141 typedef struct
rgrover1 103:138bdc859cc9 142 {
rgrover1 103:138bdc859cc9 143 uint8_t type; /**< User memory type, see @ref BLE_USER_MEM_TYPES. */
rgrover1 103:138bdc859cc9 144 ble_user_mem_block_t mem_block; /**< User memory block */
rgrover1 103:138bdc859cc9 145 } ble_evt_user_mem_release_t;
rgrover1 103:138bdc859cc9 146
rgrover1 103:138bdc859cc9 147
rgrover1 103:138bdc859cc9 148 /**@brief Event structure for events not associated with a specific function module. */
rgrover1 103:138bdc859cc9 149 typedef struct
rgrover1 103:138bdc859cc9 150 {
rgrover1 112:737b08b3b995 151 uint16_t conn_handle; /**< Connection Handle on which this event occurred. */
rgrover1 103:138bdc859cc9 152 union
rgrover1 103:138bdc859cc9 153 {
rgrover1 103:138bdc859cc9 154 ble_evt_tx_complete_t tx_complete; /**< Transmission Complete. */
rgrover1 103:138bdc859cc9 155 ble_evt_user_mem_request_t user_mem_request; /**< User Memory Request Event Parameters. */
rgrover1 103:138bdc859cc9 156 ble_evt_user_mem_release_t user_mem_release; /**< User Memory Release Event Parameters. */
rgrover1 103:138bdc859cc9 157 } params;
rgrover1 103:138bdc859cc9 158 } ble_common_evt_t;
rgrover1 103:138bdc859cc9 159
rgrover1 103:138bdc859cc9 160 /**@brief BLE Event header. */
rgrover1 103:138bdc859cc9 161 typedef struct
rgrover1 103:138bdc859cc9 162 {
rgrover1 103:138bdc859cc9 163 uint16_t evt_id; /**< Value from a BLE_<module>_EVT series. */
rgrover1 103:138bdc859cc9 164 uint16_t evt_len; /**< Length in octets excluding this header. */
rgrover1 103:138bdc859cc9 165 } ble_evt_hdr_t;
rgrover1 103:138bdc859cc9 166
rgrover1 103:138bdc859cc9 167 /**@brief Common BLE Event type, wrapping the module specific event reports. */
rgrover1 103:138bdc859cc9 168 typedef struct
rgrover1 103:138bdc859cc9 169 {
rgrover1 103:138bdc859cc9 170 ble_evt_hdr_t header; /**< Event header. */
rgrover1 103:138bdc859cc9 171 union
rgrover1 103:138bdc859cc9 172 {
rgrover1 103:138bdc859cc9 173 ble_common_evt_t common_evt; /**< Common Event, evt_id in BLE_EVT_* series. */
rgrover1 103:138bdc859cc9 174 ble_gap_evt_t gap_evt; /**< GAP originated event, evt_id in BLE_GAP_EVT_* series. */
rgrover1 103:138bdc859cc9 175 ble_l2cap_evt_t l2cap_evt; /**< L2CAP originated event, evt_id in BLE_L2CAP_EVT* series. */
rgrover1 103:138bdc859cc9 176 ble_gattc_evt_t gattc_evt; /**< GATT client originated event, evt_id in BLE_GATTC_EVT* series. */
rgrover1 103:138bdc859cc9 177 ble_gatts_evt_t gatts_evt; /**< GATT server originated event, evt_id in BLE_GATTS_EVT* series. */
rgrover1 103:138bdc859cc9 178 } evt;
rgrover1 103:138bdc859cc9 179 } ble_evt_t;
rgrover1 103:138bdc859cc9 180
rgrover1 103:138bdc859cc9 181
rgrover1 103:138bdc859cc9 182 /**
rgrover1 103:138bdc859cc9 183 * @brief Version Information.
rgrover1 103:138bdc859cc9 184 */
rgrover1 103:138bdc859cc9 185 typedef struct
rgrover1 103:138bdc859cc9 186 {
rgrover1 103:138bdc859cc9 187 uint8_t version_number; /**< Link Layer Version number for BT 4.1 spec is 7 (https://www.bluetooth.org/en-us/specification/assigned-numbers/link-layer). */
rgrover1 103:138bdc859cc9 188 uint16_t company_id; /**< Company ID, Nordic Semiconductor's company ID is 89 (0x0059) (https://www.bluetooth.org/apps/content/Default.aspx?doc_id=49708). */
rgrover1 103:138bdc859cc9 189 uint16_t subversion_number; /**< Link Layer Sub Version number, corresponds to the SoftDevice Config ID or Firmware ID (FWID). */
rgrover1 103:138bdc859cc9 190 } ble_version_t;
rgrover1 103:138bdc859cc9 191
rgrover1 103:138bdc859cc9 192 /**@brief Mutual exclusion of radio activity and CPU execution.
rgrover1 103:138bdc859cc9 193 *
rgrover1 103:138bdc859cc9 194 * This option configures the application's access to the CPU when the radio is active. The
rgrover1 112:737b08b3b995 195 * application can configure itself to be blocked from using the CPU while the radio is
rgrover1 112:737b08b3b995 196 * active. By default, the application will be able to share CPU time with the SoftDevice
rgrover1 103:138bdc859cc9 197 * during radio activity. This parameter structure is used together with @ref sd_ble_opt_set
rgrover1 103:138bdc859cc9 198 * to configure the @ref BLE_COMMON_OPT_RADIO_CPU_MUTEX option.
rgrover1 103:138bdc859cc9 199 *
rgrover1 112:737b08b3b995 200 * @note Note that the application should use this option to configure the SoftDevice to block the
rgrover1 112:737b08b3b995 201 * CPU during radio activity (i.e enable mutual exclusion) when running the SoftDevice on
rgrover1 112:737b08b3b995 202 * hardware affected by PAN #44 "CCM may exceed real time requirements"and PAN #45 "AAR may
rgrover1 112:737b08b3b995 203 * exceed real time requirements".
rgrover1 112:737b08b3b995 204 *
rgrover1 112:737b08b3b995 205 * @note Note that when acting as a scanner, the mutex is only enabled for radio TX activity.
rgrover1 103:138bdc859cc9 206 *
rgrover1 103:138bdc859cc9 207 * @note @ref sd_ble_opt_get is not supported for this option.
rgrover1 103:138bdc859cc9 208 *
rgrover1 103:138bdc859cc9 209 */
rgrover1 103:138bdc859cc9 210 typedef struct
rgrover1 103:138bdc859cc9 211 {
rgrover1 103:138bdc859cc9 212 uint8_t enable : 1; /**< Enable mutual exclusion of radio activity and the CPU execution. */
rgrover1 103:138bdc859cc9 213 } ble_common_opt_radio_cpu_mutex_t;
rgrover1 103:138bdc859cc9 214
rgrover1 103:138bdc859cc9 215 /**@brief Option structure for common options. */
rgrover1 103:138bdc859cc9 216 typedef union
rgrover1 103:138bdc859cc9 217 {
rgrover1 103:138bdc859cc9 218 ble_common_opt_radio_cpu_mutex_t radio_cpu_mutex; /**< Parameters for the option for the mutual exclusion of radio activity and CPU execution. */
rgrover1 103:138bdc859cc9 219 } ble_common_opt_t;
rgrover1 103:138bdc859cc9 220
rgrover1 103:138bdc859cc9 221 /**@brief Common BLE Option type, wrapping the module specific options. */
rgrover1 103:138bdc859cc9 222 typedef union
rgrover1 103:138bdc859cc9 223 {
rgrover1 103:138bdc859cc9 224 ble_common_opt_t common_opt; /**< Common option, opt_id in BLE_COMMON_OPT_* series. */
rgrover1 103:138bdc859cc9 225 ble_gap_opt_t gap_opt; /**< GAP option, opt_id in BLE_GAP_OPT_* series. */
rgrover1 103:138bdc859cc9 226 } ble_opt_t;
rgrover1 103:138bdc859cc9 227
rgrover1 103:138bdc859cc9 228 /**
rgrover1 103:138bdc859cc9 229 * @brief BLE GATTS init options
rgrover1 103:138bdc859cc9 230 */
rgrover1 103:138bdc859cc9 231 typedef struct
rgrover1 103:138bdc859cc9 232 {
rgrover1 112:737b08b3b995 233 ble_gatts_enable_params_t gatts_enable_params; /**< GATTS init options @ref ble_gatts_enable_params_t. */
rgrover1 103:138bdc859cc9 234 } ble_enable_params_t;
rgrover1 103:138bdc859cc9 235
rgrover1 103:138bdc859cc9 236 /** @} */
rgrover1 103:138bdc859cc9 237
rgrover1 103:138bdc859cc9 238 /** @addtogroup BLE_COMMON_FUNCTIONS Functions
rgrover1 103:138bdc859cc9 239 * @{ */
rgrover1 103:138bdc859cc9 240
rgrover1 112:737b08b3b995 241 /**@brief Enable the BLE stack
rgrover1 103:138bdc859cc9 242 *
rgrover1 103:138bdc859cc9 243 * @param[in] p_ble_enable_params Pointer to ble_enable_params_t
rgrover1 103:138bdc859cc9 244 *
rgrover1 112:737b08b3b995 245 * @details This call initializes the BLE stack, no other BLE related function can be called before this one.
rgrover1 103:138bdc859cc9 246 *
rgrover1 112:737b08b3b995 247 * @return @ref NRF_SUCCESS BLE the BLE stack has been initialized successfully
rgrover1 112:737b08b3b995 248 * @retval @ref NRF_ERROR_INVALID_STATE the BLE stack had already been initialized and cannot be reinitialized.
rgrover1 103:138bdc859cc9 249 * @return @ref NRF_ERROR_INVALID_ADDR Invalid or not sufficiently aligned pointer supplied.
rgrover1 112:737b08b3b995 250 * @return @ref NRF_ERROR_INVALID_LENGTH The specified Attribute Table size is either too small or not a multiple of 4.
rgrover1 112:737b08b3b995 251 * The minimum acceptable size is defined by @ref BLE_GATTS_ATTR_TAB_SIZE_MIN.
rgrover1 112:737b08b3b995 252 * @return @ref NRF_ERROR_NO_MEM The Attribute Table size is too large. Decrease size in @ref ble_gatts_enable_params_t.
rgrover1 103:138bdc859cc9 253 */
rgrover1 103:138bdc859cc9 254 SVCALL(SD_BLE_ENABLE, uint32_t, sd_ble_enable(ble_enable_params_t * p_ble_enable_params));
rgrover1 103:138bdc859cc9 255
rgrover1 103:138bdc859cc9 256 /**@brief Get an event from the pending events queue.
rgrover1 103:138bdc859cc9 257 *
rgrover1 112:737b08b3b995 258 * @param[out] p_dest Pointer to buffer to be filled in with an event, or NULL to retrieve the event length. This buffer <b>must be 4-byte aligned in memory</b>.
rgrover1 103:138bdc859cc9 259 * @param[in, out] p_len Pointer the length of the buffer, on return it is filled with the event length.
rgrover1 103:138bdc859cc9 260 *
rgrover1 103:138bdc859cc9 261 * @details This call allows the application to pull a BLE event from the BLE stack. The application is signalled that an event is
rgrover1 112:737b08b3b995 262 * available from the BLE stack by the triggering of the SD_EVT_IRQn interrupt.
rgrover1 103:138bdc859cc9 263 * The application is free to choose whether to call this function from thread mode (main context) or directly from the Interrupt Service Routine
rgrover1 103:138bdc859cc9 264 * that maps to SD_EVT_IRQn. In any case however, and because the BLE stack runs at a higher priority than the application, this function should be called
rgrover1 112:737b08b3b995 265 * in a loop (until @ref NRF_ERROR_NOT_FOUND is returned) every time SD_EVT_IRQn is raised to ensure that all available events are pulled from the BLE stack.
rgrover1 103:138bdc859cc9 266 * Failure to do so could potentially leave events in the internal queue without the application being aware of this fact.
rgrover1 103:138bdc859cc9 267 * Sizing the p_dest buffer is equally important, since the application needs to provide all the memory necessary for the event to be copied into
rgrover1 103:138bdc859cc9 268 * application memory. If the buffer provided is not large enough to fit the entire contents of the event, @ref NRF_ERROR_DATA_SIZE will be returned
rgrover1 103:138bdc859cc9 269 * and the application can then call again with a larger buffer size.
rgrover1 103:138bdc859cc9 270 * Please note that because of the variable length nature of some events, sizeof(ble_evt_t) will not always be large enough to fit certain events,
rgrover1 112:737b08b3b995 271 * and so it is the application's responsibility to provide an amount of memory large enough so that the relevant event is copied in full.
rgrover1 103:138bdc859cc9 272 * The application may "peek" the event length by providing p_dest as a NULL pointer and inspecting the value of *p_len upon return.
rgrover1 103:138bdc859cc9 273 *
rgrover1 103:138bdc859cc9 274 * @note The pointer supplied must be aligned to the extend defined by @ref BLE_EVTS_PTR_ALIGNMENT
rgrover1 103:138bdc859cc9 275 *
rgrover1 112:737b08b3b995 276 * @retval ::NRF_SUCCESS Event pulled and stored into the supplied buffer.
rgrover1 112:737b08b3b995 277 * @retval ::NRF_ERROR_INVALID_ADDR Invalid or not sufficiently aligned pointer supplied.
rgrover1 112:737b08b3b995 278 * @retval ::NRF_ERROR_NOT_FOUND No events ready to be pulled.
rgrover1 112:737b08b3b995 279 * @retval ::NRF_ERROR_DATA_SIZE Event ready but could not fit into the supplied buffer.
rgrover1 103:138bdc859cc9 280 */
rgrover1 112:737b08b3b995 281 SVCALL(SD_BLE_EVT_GET, uint32_t, sd_ble_evt_get(uint8_t *p_dest, uint16_t *p_len));
rgrover1 103:138bdc859cc9 282
rgrover1 103:138bdc859cc9 283
rgrover1 112:737b08b3b995 284 /**@brief Get the total number of available application transmission buffers per link in the BLE stack.
rgrover1 103:138bdc859cc9 285 *
rgrover1 103:138bdc859cc9 286 * @details This call allows the application to obtain the total number of
rgrover1 112:737b08b3b995 287 * transmission buffers available per link for application data. Please note that
rgrover1 103:138bdc859cc9 288 * this does not give the number of free buffers, but rather the total amount of them.
rgrover1 103:138bdc859cc9 289 * The application has two options to handle its own application transmission buffers:
rgrover1 103:138bdc859cc9 290 * - Use a simple arithmetic calculation: at boot time the application should use this function
rgrover1 103:138bdc859cc9 291 * to find out the total amount of buffers available to it and store it in a variable.
rgrover1 103:138bdc859cc9 292 * Every time a packet that consumes an application buffer is sent using any of the
rgrover1 103:138bdc859cc9 293 * exposed functions in this BLE API, the application should decrement that variable.
rgrover1 103:138bdc859cc9 294 * Conversely, whenever a @ref BLE_EVT_TX_COMPLETE event is received by the application
rgrover1 103:138bdc859cc9 295 * it should retrieve the count field in such event and add that number to the same
rgrover1 103:138bdc859cc9 296 * variable storing the number of available packets.
rgrover1 103:138bdc859cc9 297 * This mechanism allows the application to be aware at any time of the number of
rgrover1 103:138bdc859cc9 298 * application packets available in the BLE stack's internal buffers, and therefore
rgrover1 103:138bdc859cc9 299 * it can know with certainty whether it is possible to send more data or it has to
rgrover1 103:138bdc859cc9 300 * wait for a @ref BLE_EVT_TX_COMPLETE event before it proceeds.
rgrover1 103:138bdc859cc9 301 * - Choose to simply not keep track of available buffers at all, and instead handle the
rgrover1 103:138bdc859cc9 302 * @ref BLE_ERROR_NO_TX_BUFFERS error by queueing the packet to be transmitted and
rgrover1 103:138bdc859cc9 303 * try again as soon as a @ref BLE_EVT_TX_COMPLETE event arrives.
rgrover1 103:138bdc859cc9 304 *
rgrover1 103:138bdc859cc9 305 * The API functions that <b>may</b> consume an application buffer depending on
rgrover1 103:138bdc859cc9 306 * the parameters supplied to them can be found below:
rgrover1 103:138bdc859cc9 307 *
rgrover1 112:737b08b3b995 308 * - @ref sd_ble_gattc_write (write without response only)
rgrover1 103:138bdc859cc9 309 * - @ref sd_ble_gatts_hvx (notifications only)
rgrover1 103:138bdc859cc9 310 * - @ref sd_ble_l2cap_tx (all packets)
rgrover1 103:138bdc859cc9 311 *
rgrover1 103:138bdc859cc9 312 * @param[out] p_count Pointer to a uint8_t which will contain the number of application transmission buffers upon
rgrover1 103:138bdc859cc9 313 * successful return.
rgrover1 103:138bdc859cc9 314 *
rgrover1 112:737b08b3b995 315 * @retval ::NRF_SUCCESS Number of application transmission buffers retrieved successfully.
rgrover1 112:737b08b3b995 316 * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
rgrover1 103:138bdc859cc9 317 */
rgrover1 112:737b08b3b995 318 SVCALL(SD_BLE_TX_BUFFER_COUNT_GET, uint32_t, sd_ble_tx_buffer_count_get(uint8_t *p_count));
rgrover1 103:138bdc859cc9 319
rgrover1 103:138bdc859cc9 320
rgrover1 103:138bdc859cc9 321 /**@brief Add a Vendor Specific UUID.
rgrover1 103:138bdc859cc9 322 *
rgrover1 103:138bdc859cc9 323 * @details This call enables the application to add a vendor specific UUID to the BLE stack's table,
rgrover1 103:138bdc859cc9 324 * for later use all other modules and APIs. This then allows the application to use the shorter,
rgrover1 103:138bdc859cc9 325 * 24-bit @ref ble_uuid_t format when dealing with both 16-bit and 128-bit UUIDs without having to
rgrover1 103:138bdc859cc9 326 * check for lengths and having split code paths. The way that this is accomplished is by extending the
rgrover1 103:138bdc859cc9 327 * grouping mechanism that the Bluetooth SIG standard base UUID uses for all other 128-bit UUIDs. The
rgrover1 103:138bdc859cc9 328 * type field in the @ref ble_uuid_t structure is an index (relative to @ref BLE_UUID_TYPE_VENDOR_BEGIN)
rgrover1 103:138bdc859cc9 329 * to the table populated by multiple calls to this function, and the uuid field in the same structure
rgrover1 103:138bdc859cc9 330 * contains the 2 bytes at indices 12 and 13. The number of possible 128-bit UUIDs available to the
rgrover1 103:138bdc859cc9 331 * application is therefore the number of Vendor Specific UUIDs added with the help of this function times 65536,
rgrover1 103:138bdc859cc9 332 * although restricted to modifying bytes 12 and 13 for each of the entries in the supplied array.
rgrover1 103:138bdc859cc9 333 *
rgrover1 103:138bdc859cc9 334 * @note Bytes 12 and 13 of the provided UUID will not be used internally, since those are always replaced by
rgrover1 103:138bdc859cc9 335 * the 16-bit uuid field in @ref ble_uuid_t.
rgrover1 103:138bdc859cc9 336 *
rgrover1 103:138bdc859cc9 337 *
rgrover1 103:138bdc859cc9 338 * @param[in] p_vs_uuid Pointer to a 16-octet (128-bit) little endian Vendor Specific UUID disregarding
rgrover1 103:138bdc859cc9 339 * bytes 12 and 13.
rgrover1 112:737b08b3b995 340 * @param[out] p_uuid_type Pointer to a uint8_t where the type field in @ref ble_uuid_t corresponding to this UUID will be stored.
rgrover1 103:138bdc859cc9 341 *
rgrover1 112:737b08b3b995 342 * @retval ::NRF_SUCCESS Successfully added the Vendor Specific UUID.
rgrover1 112:737b08b3b995 343 * @retval ::NRF_ERROR_INVALID_ADDR If p_vs_uuid or p_uuid_type is NULL or invalid.
rgrover1 112:737b08b3b995 344 * @retval ::NRF_ERROR_NO_MEM If there are no more free slots for VS UUIDs.
rgrover1 112:737b08b3b995 345 * @retval ::NRF_ERROR_FORBIDDEN If p_vs_uuid has already been added to the VS UUID table.
rgrover1 103:138bdc859cc9 346 */
rgrover1 112:737b08b3b995 347 SVCALL(SD_BLE_UUID_VS_ADD, uint32_t, sd_ble_uuid_vs_add(ble_uuid128_t const *p_vs_uuid, uint8_t *p_uuid_type));
rgrover1 103:138bdc859cc9 348
rgrover1 103:138bdc859cc9 349
rgrover1 103:138bdc859cc9 350 /** @brief Decode little endian raw UUID bytes (16-bit or 128-bit) into a 24 bit @ref ble_uuid_t structure.
rgrover1 103:138bdc859cc9 351 *
rgrover1 103:138bdc859cc9 352 * @details The raw UUID bytes excluding bytes 12 and 13 (i.e. bytes 0-11 and 14-15) of p_uuid_le are compared
rgrover1 112:737b08b3b995 353 * to the corresponding ones in each entry of the table of vendor specific UUIDs populated with @ref sd_ble_uuid_vs_add
rgrover1 103:138bdc859cc9 354 * to look for a match. If there is such a match, bytes 12 and 13 are returned as p_uuid->uuid and the index
rgrover1 103:138bdc859cc9 355 * relative to @ref BLE_UUID_TYPE_VENDOR_BEGIN as p_uuid->type.
rgrover1 103:138bdc859cc9 356 *
rgrover1 103:138bdc859cc9 357 * @note If the UUID length supplied is 2, then the type set by this call will always be @ref BLE_UUID_TYPE_BLE.
rgrover1 103:138bdc859cc9 358 *
rgrover1 103:138bdc859cc9 359 * @param[in] uuid_le_len Length in bytes of the buffer pointed to by p_uuid_le (must be 2 or 16 bytes).
rgrover1 103:138bdc859cc9 360 * @param[in] p_uuid_le Pointer pointing to little endian raw UUID bytes.
rgrover1 112:737b08b3b995 361 * @param[out] p_uuid Pointer to a @ref ble_uuid_t structure to be filled in.
rgrover1 103:138bdc859cc9 362 *
rgrover1 112:737b08b3b995 363 * @retval ::NRF_SUCCESS Successfully decoded into the @ref ble_uuid_t structure.
rgrover1 112:737b08b3b995 364 * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
rgrover1 112:737b08b3b995 365 * @retval ::NRF_ERROR_INVALID_LENGTH Invalid UUID length.
rgrover1 112:737b08b3b995 366 * @retval ::NRF_ERROR_NOT_FOUND For a 128-bit UUID, no match in the populated table of UUIDs.
rgrover1 103:138bdc859cc9 367 */
rgrover1 112:737b08b3b995 368 SVCALL(SD_BLE_UUID_DECODE, uint32_t, sd_ble_uuid_decode(uint8_t uuid_le_len, uint8_t const *p_uuid_le, ble_uuid_t *p_uuid));
rgrover1 103:138bdc859cc9 369
rgrover1 103:138bdc859cc9 370
rgrover1 103:138bdc859cc9 371 /** @brief Encode a @ref ble_uuid_t structure into little endian raw UUID bytes (16-bit or 128-bit).
rgrover1 103:138bdc859cc9 372 *
rgrover1 112:737b08b3b995 373 * @note The pointer to the destination buffer p_uuid_le may be NULL, in which case only the validity and size of p_uuid is computed.
rgrover1 103:138bdc859cc9 374 *
rgrover1 103:138bdc859cc9 375 * @param[in] p_uuid Pointer to a @ref ble_uuid_t structure that will be encoded into bytes.
rgrover1 103:138bdc859cc9 376 * @param[out] p_uuid_le_len Pointer to a uint8_t that will be filled with the encoded length (2 or 16 bytes).
rgrover1 103:138bdc859cc9 377 * @param[out] p_uuid_le Pointer to a buffer where the little endian raw UUID bytes (2 or 16) will be stored.
rgrover1 103:138bdc859cc9 378 *
rgrover1 112:737b08b3b995 379 * @retval ::NRF_SUCCESS Successfully encoded into the buffer.
rgrover1 112:737b08b3b995 380 * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
rgrover1 112:737b08b3b995 381 * @retval ::NRF_ERROR_INVALID_PARAM Invalid UUID type.
rgrover1 103:138bdc859cc9 382 */
rgrover1 112:737b08b3b995 383 SVCALL(SD_BLE_UUID_ENCODE, uint32_t, sd_ble_uuid_encode(ble_uuid_t const *p_uuid, uint8_t *p_uuid_le_len, uint8_t *p_uuid_le));
rgrover1 103:138bdc859cc9 384
rgrover1 103:138bdc859cc9 385
rgrover1 103:138bdc859cc9 386 /**@brief Get Version Information.
rgrover1 103:138bdc859cc9 387 *
rgrover1 103:138bdc859cc9 388 * @details This call allows the application to get the BLE stack version information.
rgrover1 103:138bdc859cc9 389 *
rgrover1 112:737b08b3b995 390 * @param[out] p_version Pointer to a ble_version_t structure to be filled in.
rgrover1 103:138bdc859cc9 391 *
rgrover1 112:737b08b3b995 392 * @retval ::NRF_SUCCESS Version information stored successfully.
rgrover1 112:737b08b3b995 393 * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
rgrover1 112:737b08b3b995 394 * @retval ::NRF_ERROR_BUSY The BLE stack is busy (typically doing a locally-initiated disconnection procedure).
rgrover1 103:138bdc859cc9 395 */
rgrover1 112:737b08b3b995 396 SVCALL(SD_BLE_VERSION_GET, uint32_t, sd_ble_version_get(ble_version_t *p_version));
rgrover1 103:138bdc859cc9 397
rgrover1 103:138bdc859cc9 398
rgrover1 103:138bdc859cc9 399 /**@brief Provide a user memory block.
rgrover1 103:138bdc859cc9 400 *
rgrover1 103:138bdc859cc9 401 * @note This call can only be used as a response to a @ref BLE_EVT_USER_MEM_REQUEST event issued to the application.
rgrover1 103:138bdc859cc9 402 *
rgrover1 112:737b08b3b995 403 * @param[in] conn_handle Connection handle.
rgrover1 112:737b08b3b995 404 * @param[in,out] p_block Pointer to a user memory block structure.
rgrover1 103:138bdc859cc9 405 *
rgrover1 112:737b08b3b995 406 * @retval ::NRF_SUCCESS Successfully queued a response to the peer.
rgrover1 112:737b08b3b995 407 * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid Connection Handle.
rgrover1 112:737b08b3b995 408 * @retval ::NRF_ERROR_INVALID_STATE Invalid Connection state or no execute write request pending.
rgrover1 112:737b08b3b995 409 * @retval ::NRF_ERROR_BUSY The BLE stack is busy. Retry at later time.
rgrover1 103:138bdc859cc9 410 */
rgrover1 112:737b08b3b995 411 SVCALL(SD_BLE_USER_MEM_REPLY, uint32_t, sd_ble_user_mem_reply(uint16_t conn_handle, ble_user_mem_block_t const *p_block));
rgrover1 103:138bdc859cc9 412
rgrover1 103:138bdc859cc9 413 /**@brief Set a BLE option.
rgrover1 103:138bdc859cc9 414 *
rgrover1 103:138bdc859cc9 415 * @details This call allows the application to set the value of an option.
rgrover1 103:138bdc859cc9 416 *
rgrover1 103:138bdc859cc9 417 * @param[in] opt_id Option ID.
rgrover1 103:138bdc859cc9 418 * @param[in] p_opt Pointer to a ble_opt_t structure containing the option value.
rgrover1 103:138bdc859cc9 419 *
rgrover1 103:138bdc859cc9 420 * @retval ::NRF_SUCCESS Option set successfully.
rgrover1 103:138bdc859cc9 421 * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
rgrover1 103:138bdc859cc9 422 * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid Connection Handle.
rgrover1 103:138bdc859cc9 423 * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied, check parameter limits and constraints.
rgrover1 103:138bdc859cc9 424 * @retval ::NRF_ERROR_INVALID_STATE Unable to set the parameter at this time.
rgrover1 112:737b08b3b995 425 * @retval ::NRF_ERROR_BUSY The BLE stack is busy or the previous procedure has not completed.
rgrover1 103:138bdc859cc9 426 */
rgrover1 103:138bdc859cc9 427 SVCALL(SD_BLE_OPT_SET, uint32_t, sd_ble_opt_set(uint32_t opt_id, ble_opt_t const *p_opt));
rgrover1 103:138bdc859cc9 428
rgrover1 103:138bdc859cc9 429
rgrover1 103:138bdc859cc9 430 /**@brief Get a BLE option.
rgrover1 103:138bdc859cc9 431 *
rgrover1 103:138bdc859cc9 432 * @details This call allows the application to retrieve the value of an option.
rgrover1 103:138bdc859cc9 433 *
rgrover1 103:138bdc859cc9 434 * @param[in] opt_id Option ID.
rgrover1 103:138bdc859cc9 435 * @param[out] p_opt Pointer to a ble_opt_t structure to be filled in.
rgrover1 103:138bdc859cc9 436 *
rgrover1 103:138bdc859cc9 437 * @retval ::NRF_SUCCESS Option retrieved successfully.
rgrover1 103:138bdc859cc9 438 * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
rgrover1 103:138bdc859cc9 439 * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid Connection Handle.
rgrover1 103:138bdc859cc9 440 * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied, check parameter limits and constraints.
rgrover1 103:138bdc859cc9 441 * @retval ::NRF_ERROR_INVALID_STATE Unable to retrieve the parameter at this time.
rgrover1 112:737b08b3b995 442 * @retval ::NRF_ERROR_BUSY The BLE stack is busy or the previous procedure has not completed.
rgrover1 103:138bdc859cc9 443 * @retval ::NRF_ERROR_NOT_SUPPORTED This option is not supported.
rgrover1 103:138bdc859cc9 444 *
rgrover1 103:138bdc859cc9 445 */
rgrover1 103:138bdc859cc9 446 SVCALL(SD_BLE_OPT_GET, uint32_t, sd_ble_opt_get(uint32_t opt_id, ble_opt_t *p_opt));
rgrover1 103:138bdc859cc9 447
rgrover1 103:138bdc859cc9 448 /** @} */
rgrover1 103:138bdc859cc9 449
rgrover1 103:138bdc859cc9 450 #endif /* BLE_H__ */
rgrover1 103:138bdc859cc9 451
rgrover1 103:138bdc859cc9 452 /**
rgrover1 103:138bdc859cc9 453 @}
rgrover1 103:138bdc859cc9 454 @}
rgrover1 103:138bdc859cc9 455 */