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@345:dfde56236c36, 2015-06-19 (annotated)

Committer:
rgrover1
Date:
Fri Jun 19 15:55:35 2015 +0100
Revision:
345:dfde56236c36
Parent:
343:6675661fa600
Child:
346:14b090482fd2
Synchronized with git rev fbfc6d16

Author: Andrew Fernandes

Fix various GCC compilation issues.

Who changed what in which revision?

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