Rob Kluin / nRF51822

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/s130/include/ble.h@343:6675661fa600, 2015-06-19 (annotated)

Committer:
rgrover1
Date:
Fri Jun 19 15:55:34 2015 +0100
Revision:
343:6675661fa600
Parent:
163:65f11741e3d4
Child:
345:dfde56236c36
Synchronized with git rev 6d1bf116

Author: Rohit Grover

fix #1: update license headers for all sources obtained from nordic-SDK using a new template obtained from Nordic.

Who changed what in which revision?

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