Cefn Hoile / 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.

Dependencies:   nrf51-sdk

Dependents:   microbit-dal

Fork of nRF51822 by Lancaster University

nordic-sdk/components/softdevice/s130/include/ble.h@370:295f76db798e, 2015-07-06 (annotated)

Committer:
rgrover1
Date:
Mon Jul 06 10:13:26 2015 +0100
Revision:
370:295f76db798e
Parent:
362:6fa0d4d555f6
Child:
371:8f7d2137727a
Synchronized with git rev 9f72c4ba

Author: Rohit Grover

Release 0.3.7

=============



This is a minor set of enhancements mostly around reduce our global static

memory footprint.



Enhancements

~~~~~~~~~~~~



* Reduce the maximum number of CHARACTERISTICS and DESCRIPTORS that can be

  handled. This has memory implications for static global memory. It should

  be possible to re-architect our solution for add_characteristic() to not

  require these limits; hopefully we'll get there soon.



* Move nRF51GattServer::getInstance() into a .cpp file; same for nRF51Gap::getInstance().



* Reduce max bonds to managed by device-manager to 4; this has memory implications for static global memory.



* Reduce pStorage command queue size to 2; this has memory implications for static global memory.



* Replace uses of deprecated Gap::addr_type_t with Gap::AddressType_t.



* Some UUID-related types have moved into UUID class. Minor changes were needed to work around build errors.



Bugfixes

~~~~~~~~



* None.

Who changed what in which revision?

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