Microbug / nRF51822_FOTA

Important changes to repositories hosted on mbed.com

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

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

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

Fork of nRF51822 by Nordic Semiconductor

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

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

Author: Rohit Grover

porting to v8.0 of the SDK

Who changed what in which revision?

UserRevisionLine numberNew contents of line
rgrover1 112:737b08b3b995 1 /*
rgrover1 112:737b08b3b995 2 * Copyright (c) Nordic Semiconductor ASA
rgrover1 112:737b08b3b995 3 * All rights reserved.
rgrover1 112:737b08b3b995 4 *
rgrover1 112:737b08b3b995 5 * Redistribution and use in source and binary forms, with or without modification,
rgrover1 112:737b08b3b995 6 * are permitted provided that the following conditions are met:
rgrover1 112:737b08b3b995 7 *
rgrover1 112:737b08b3b995 8 * 1. Redistributions of source code must retain the above copyright notice, this
rgrover1 112:737b08b3b995 9 * list of conditions and the following disclaimer.
rgrover1 112:737b08b3b995 10 *
rgrover1 112:737b08b3b995 11 * 2. Redistributions in binary form must reproduce the above copyright notice, this
rgrover1 112:737b08b3b995 12 * list of conditions and the following disclaimer in the documentation and/or
rgrover1 112:737b08b3b995 13 * other materials provided with the distribution.
rgrover1 112:737b08b3b995 14 *
rgrover1 112:737b08b3b995 15 * 3. Neither the name of Nordic Semiconductor ASA nor the names of other
rgrover1 112:737b08b3b995 16 * contributors to this software may be used to endorse or promote products
rgrover1 112:737b08b3b995 17 * derived from this software without specific prior written permission.
rgrover1 112:737b08b3b995 18 *
rgrover1 112:737b08b3b995 19 * 4. This software must only be used in a processor manufactured by Nordic
rgrover1 112:737b08b3b995 20 * Semiconductor ASA, or in a processor manufactured by a third party that
rgrover1 112:737b08b3b995 21 * is used in combination with a processor manufactured by Nordic Semiconductor.
rgrover1 112:737b08b3b995 22 *
rgrover1 112:737b08b3b995 23 *
rgrover1 112:737b08b3b995 24 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
rgrover1 112:737b08b3b995 25 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
rgrover1 112:737b08b3b995 26 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
rgrover1 112:737b08b3b995 27 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
rgrover1 112:737b08b3b995 28 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
rgrover1 112:737b08b3b995 29 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
rgrover1 112:737b08b3b995 30 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
rgrover1 112:737b08b3b995 31 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
rgrover1 112:737b08b3b995 32 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
rgrover1 112:737b08b3b995 33 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
rgrover1 112:737b08b3b995 34 *
rgrover1 103:138bdc859cc9 35 */
rgrover1 112:737b08b3b995 36
rgrover1 103:138bdc859cc9 37 /**
rgrover1 103:138bdc859cc9 38 @addtogroup BLE_GATTS Generic Attribute Profile (GATT) Server
rgrover1 103:138bdc859cc9 39 @{
rgrover1 103:138bdc859cc9 40 @brief Definitions and prototypes for the GATTS interface.
rgrover1 103:138bdc859cc9 41 */
rgrover1 103:138bdc859cc9 42
rgrover1 103:138bdc859cc9 43 #ifndef BLE_GATTS_H__
rgrover1 103:138bdc859cc9 44 #define BLE_GATTS_H__
rgrover1 103:138bdc859cc9 45
rgrover1 103:138bdc859cc9 46 #include "ble_types.h"
rgrover1 103:138bdc859cc9 47 #include "ble_ranges.h"
rgrover1 103:138bdc859cc9 48 #include "ble_l2cap.h"
rgrover1 103:138bdc859cc9 49 #include "ble_gap.h"
rgrover1 103:138bdc859cc9 50 #include "ble_gatt.h"
rgrover1 103:138bdc859cc9 51 #include "nrf_svc.h"
rgrover1 103:138bdc859cc9 52
rgrover1 103:138bdc859cc9 53 /** @addtogroup BLE_GATTS_ENUMERATIONS Enumerations
rgrover1 103:138bdc859cc9 54 * @{ */
rgrover1 103:138bdc859cc9 55
rgrover1 103:138bdc859cc9 56 /**
rgrover1 103:138bdc859cc9 57 * @brief GATTS API SVC numbers.
rgrover1 103:138bdc859cc9 58 */
rgrover1 103:138bdc859cc9 59 enum BLE_GATTS_SVCS
rgrover1 103:138bdc859cc9 60 {
rgrover1 103:138bdc859cc9 61 SD_BLE_GATTS_SERVICE_ADD = BLE_GATTS_SVC_BASE, /**< Add a service. */
rgrover1 103:138bdc859cc9 62 SD_BLE_GATTS_INCLUDE_ADD, /**< Add an included service. */
rgrover1 103:138bdc859cc9 63 SD_BLE_GATTS_CHARACTERISTIC_ADD, /**< Add a characteristic. */
rgrover1 103:138bdc859cc9 64 SD_BLE_GATTS_DESCRIPTOR_ADD, /**< Add a generic attribute. */
rgrover1 103:138bdc859cc9 65 SD_BLE_GATTS_VALUE_SET, /**< Set an attribute value. */
rgrover1 103:138bdc859cc9 66 SD_BLE_GATTS_VALUE_GET, /**< Get an attribute value. */
rgrover1 103:138bdc859cc9 67 SD_BLE_GATTS_HVX, /**< Handle Value Notification or Indication. */
rgrover1 103:138bdc859cc9 68 SD_BLE_GATTS_SERVICE_CHANGED, /**< Perform a Service Changed Indication to one or more peers. */
rgrover1 103:138bdc859cc9 69 SD_BLE_GATTS_RW_AUTHORIZE_REPLY, /**< Reply to an authorization request for a read or write operation on one or more attributes. */
rgrover1 103:138bdc859cc9 70 SD_BLE_GATTS_SYS_ATTR_SET, /**< Set the persistent system attributes for a connection. */
rgrover1 112:737b08b3b995 71 SD_BLE_GATTS_SYS_ATTR_GET, /**< Retrieve the persistent system attributes. */
rgrover1 103:138bdc859cc9 72 };
rgrover1 103:138bdc859cc9 73
rgrover1 112:737b08b3b995 74 /**
rgrover1 112:737b08b3b995 75 * @brief GATT Server Event IDs.
rgrover1 112:737b08b3b995 76 */
rgrover1 112:737b08b3b995 77 enum BLE_GATTS_EVTS
rgrover1 112:737b08b3b995 78 {
rgrover1 112:737b08b3b995 79 BLE_GATTS_EVT_WRITE = BLE_GATTS_EVT_BASE, /**< Write operation performed. @ref ble_gatts_evt_write_t */
rgrover1 112:737b08b3b995 80 BLE_GATTS_EVT_RW_AUTHORIZE_REQUEST, /**< Read/Write Authorization request.@ref ble_gatts_evt_rw_authorize_request_t */
rgrover1 112:737b08b3b995 81 BLE_GATTS_EVT_SYS_ATTR_MISSING, /**< A persistent system attribute access is pending, awaiting a sd_ble_gatts_sys_attr_set(). @ref ble_gatts_evt_sys_attr_missing_t */
rgrover1 112:737b08b3b995 82 BLE_GATTS_EVT_HVC, /**< Handle Value Confirmation. @ref ble_gatts_evt_hvc_t */
rgrover1 112:737b08b3b995 83 BLE_GATTS_EVT_SC_CONFIRM, /**< Service Changed Confirmation. No additional event structure applies. */
rgrover1 112:737b08b3b995 84 BLE_GATTS_EVT_TIMEOUT /**< Timeout. @ref ble_gatts_evt_timeout_t */
rgrover1 112:737b08b3b995 85 };
rgrover1 103:138bdc859cc9 86 /** @} */
rgrover1 103:138bdc859cc9 87
rgrover1 103:138bdc859cc9 88 /** @addtogroup BLE_GATTS_DEFINES Defines
rgrover1 103:138bdc859cc9 89 * @{ */
rgrover1 103:138bdc859cc9 90
rgrover1 103:138bdc859cc9 91 /** @defgroup BLE_ERRORS_GATTS SVC return values specific to GATTS
rgrover1 103:138bdc859cc9 92 * @{ */
rgrover1 103:138bdc859cc9 93 #define BLE_ERROR_GATTS_INVALID_ATTR_TYPE (NRF_GATTS_ERR_BASE + 0x000) /**< Invalid attribute type. */
rgrover1 103:138bdc859cc9 94 #define BLE_ERROR_GATTS_SYS_ATTR_MISSING (NRF_GATTS_ERR_BASE + 0x001) /**< System Attributes missing. */
rgrover1 103:138bdc859cc9 95 /** @} */
rgrover1 103:138bdc859cc9 96
rgrover1 103:138bdc859cc9 97 /** @defgroup BLE_GATTS_ATTR_LENS_MAX Maximum attribute lengths
rgrover1 103:138bdc859cc9 98 * @{ */
rgrover1 103:138bdc859cc9 99 #define BLE_GATTS_FIX_ATTR_LEN_MAX (510) /**< Maximum length for fixed length Attribute Values. */
rgrover1 103:138bdc859cc9 100 #define BLE_GATTS_VAR_ATTR_LEN_MAX (512) /**< Maximum length for variable length Attribute Values. */
rgrover1 103:138bdc859cc9 101 /** @} */
rgrover1 103:138bdc859cc9 102
rgrover1 103:138bdc859cc9 103 /** @defgroup BLE_GATTS_SRVC_TYPES GATT Server Service Types
rgrover1 103:138bdc859cc9 104 * @{ */
rgrover1 103:138bdc859cc9 105 #define BLE_GATTS_SRVC_TYPE_INVALID 0x00 /**< Invalid Service Type. */
rgrover1 103:138bdc859cc9 106 #define BLE_GATTS_SRVC_TYPE_PRIMARY 0x01 /**< Primary Service. */
rgrover1 103:138bdc859cc9 107 #define BLE_GATTS_SRVC_TYPE_SECONDARY 0x02 /**< Secondary Type. */
rgrover1 103:138bdc859cc9 108 /** @} */
rgrover1 103:138bdc859cc9 109
rgrover1 103:138bdc859cc9 110
rgrover1 103:138bdc859cc9 111 /** @defgroup BLE_GATTS_ATTR_TYPES GATT Server Attribute Types
rgrover1 103:138bdc859cc9 112 * @{ */
rgrover1 103:138bdc859cc9 113 #define BLE_GATTS_ATTR_TYPE_INVALID 0x00 /**< Invalid Attribute Type. */
rgrover1 103:138bdc859cc9 114 #define BLE_GATTS_ATTR_TYPE_PRIM_SRVC_DECL 0x01 /**< Primary Service Declaration. */
rgrover1 103:138bdc859cc9 115 #define BLE_GATTS_ATTR_TYPE_SEC_SRVC_DECL 0x02 /**< Secondary Service Declaration. */
rgrover1 103:138bdc859cc9 116 #define BLE_GATTS_ATTR_TYPE_INC_DECL 0x03 /**< Include Declaration. */
rgrover1 103:138bdc859cc9 117 #define BLE_GATTS_ATTR_TYPE_CHAR_DECL 0x04 /**< Characteristic Declaration. */
rgrover1 103:138bdc859cc9 118 #define BLE_GATTS_ATTR_TYPE_CHAR_VAL 0x05 /**< Characteristic Value. */
rgrover1 103:138bdc859cc9 119 #define BLE_GATTS_ATTR_TYPE_DESC 0x06 /**< Descriptor. */
rgrover1 103:138bdc859cc9 120 #define BLE_GATTS_ATTR_TYPE_OTHER 0x07 /**< Other, non-GATT specific type. */
rgrover1 103:138bdc859cc9 121 /** @} */
rgrover1 103:138bdc859cc9 122
rgrover1 103:138bdc859cc9 123
rgrover1 103:138bdc859cc9 124 /** @defgroup BLE_GATTS_OPS GATT Server Operations
rgrover1 103:138bdc859cc9 125 * @{ */
rgrover1 103:138bdc859cc9 126 #define BLE_GATTS_OP_INVALID 0x00 /**< Invalid Operation. */
rgrover1 103:138bdc859cc9 127 #define BLE_GATTS_OP_WRITE_REQ 0x01 /**< Write Request. */
rgrover1 103:138bdc859cc9 128 #define BLE_GATTS_OP_WRITE_CMD 0x02 /**< Write Command. */
rgrover1 103:138bdc859cc9 129 #define BLE_GATTS_OP_SIGN_WRITE_CMD 0x03 /**< Signed Write Command. */
rgrover1 103:138bdc859cc9 130 #define BLE_GATTS_OP_PREP_WRITE_REQ 0x04 /**< Prepare Write Request. */
rgrover1 103:138bdc859cc9 131 #define BLE_GATTS_OP_EXEC_WRITE_REQ_CANCEL 0x05 /**< Execute Write Request: Cancel all prepared writes. */
rgrover1 103:138bdc859cc9 132 #define BLE_GATTS_OP_EXEC_WRITE_REQ_NOW 0x06 /**< Execute Write Request: Immediately execute all prepared writes. */
rgrover1 103:138bdc859cc9 133 /** @} */
rgrover1 103:138bdc859cc9 134
rgrover1 103:138bdc859cc9 135 /** @defgroup BLE_GATTS_VLOCS GATT Value Locations
rgrover1 103:138bdc859cc9 136 * @{ */
rgrover1 103:138bdc859cc9 137 #define BLE_GATTS_VLOC_INVALID 0x00 /**< Invalid Location. */
rgrover1 103:138bdc859cc9 138 #define BLE_GATTS_VLOC_STACK 0x01 /**< Attribute Value is located in stack memory, no user memory is required. */
rgrover1 103:138bdc859cc9 139 #define BLE_GATTS_VLOC_USER 0x02 /**< Attribute Value is located in user memory. This requires the user to maintain a valid buffer through the lifetime of the attribute, since the stack
rgrover1 103:138bdc859cc9 140 will read and write directly to the memory using the pointer provided in the APIs. There are no alignment requirements for the buffer. */
rgrover1 103:138bdc859cc9 141 /** @} */
rgrover1 103:138bdc859cc9 142
rgrover1 103:138bdc859cc9 143 /** @defgroup BLE_GATTS_AUTHORIZE_TYPES GATT Server Authorization Types
rgrover1 103:138bdc859cc9 144 * @{ */
rgrover1 103:138bdc859cc9 145 #define BLE_GATTS_AUTHORIZE_TYPE_INVALID 0x00 /**< Invalid Type. */
rgrover1 103:138bdc859cc9 146 #define BLE_GATTS_AUTHORIZE_TYPE_READ 0x01 /**< Authorize a Read Operation. */
rgrover1 103:138bdc859cc9 147 #define BLE_GATTS_AUTHORIZE_TYPE_WRITE 0x02 /**< Authorize a Write Request Operation. */
rgrover1 103:138bdc859cc9 148 /** @} */
rgrover1 103:138bdc859cc9 149
rgrover1 112:737b08b3b995 150 /** @defgroup BLE_GATTS_SYS_ATTR_FLAGS System Attribute Flags
rgrover1 112:737b08b3b995 151 * @{ */
rgrover1 112:737b08b3b995 152 #define BLE_GATTS_SYS_ATTR_FLAG_SYS_SRVCS (1 << 0) /**< Restrict system attributes to system services only. */
rgrover1 112:737b08b3b995 153 #define BLE_GATTS_SYS_ATTR_FLAG_USR_SRVCS (1 << 1) /**< Restrict system attributes to user services only. */
rgrover1 112:737b08b3b995 154 /** @} */
rgrover1 112:737b08b3b995 155
rgrover1 112:737b08b3b995 156 /** @defgroup BLE_GATTS_ATTR_TAB_SIZE Attribute Table size
rgrover1 112:737b08b3b995 157 * @{
rgrover1 112:737b08b3b995 158 */
rgrover1 112:737b08b3b995 159 #define BLE_GATTS_ATTR_TAB_SIZE_MIN 216 /**< Minimum Attribute Table size */
rgrover1 112:737b08b3b995 160 #define BLE_GATTS_ATTR_TAB_SIZE_DEFAULT 0x0000 /**< Default Attribute Table size (0x700 bytes for this version of the SoftDevice). */
rgrover1 112:737b08b3b995 161 /** @} */
rgrover1 103:138bdc859cc9 162
rgrover1 103:138bdc859cc9 163 /** @} */
rgrover1 103:138bdc859cc9 164
rgrover1 103:138bdc859cc9 165 /** @addtogroup BLE_GATTS_STRUCTURES Structures
rgrover1 103:138bdc859cc9 166 * @{ */
rgrover1 103:138bdc859cc9 167
rgrover1 103:138bdc859cc9 168 /**
rgrover1 103:138bdc859cc9 169 * @brief BLE GATTS init options
rgrover1 103:138bdc859cc9 170 */
rgrover1 103:138bdc859cc9 171 typedef struct
rgrover1 103:138bdc859cc9 172 {
rgrover1 112:737b08b3b995 173 uint8_t service_changed:1; /**< Include the Service Changed characteristic in the Attribute Table. */
rgrover1 112:737b08b3b995 174 uint32_t attr_tab_size; /**< Attribute Table size in bytes. The size must be a multiple of 4. @ref BLE_GATTS_ATTR_TAB_SIZE_DEFAULT is used to set the default size. */
rgrover1 103:138bdc859cc9 175 } ble_gatts_enable_params_t;
rgrover1 103:138bdc859cc9 176
rgrover1 103:138bdc859cc9 177 /**@brief Attribute metadata. */
rgrover1 103:138bdc859cc9 178 typedef struct
rgrover1 103:138bdc859cc9 179 {
rgrover1 103:138bdc859cc9 180 ble_gap_conn_sec_mode_t read_perm; /**< Read permissions. */
rgrover1 103:138bdc859cc9 181 ble_gap_conn_sec_mode_t write_perm; /**< Write permissions. */
rgrover1 103:138bdc859cc9 182 uint8_t vlen :1; /**< Variable length attribute. */
rgrover1 103:138bdc859cc9 183 uint8_t vloc :2; /**< Value location, see @ref BLE_GATTS_VLOCS.*/
rgrover1 112:737b08b3b995 184 uint8_t rd_auth :1; /**< Read authorization and value will be requested from the application on every read operation. */
rgrover1 112:737b08b3b995 185 uint8_t wr_auth :1; /**< Write authorization will be requested from the application on every Write Request operation (but not Write Command). */
rgrover1 103:138bdc859cc9 186 } ble_gatts_attr_md_t;
rgrover1 103:138bdc859cc9 187
rgrover1 103:138bdc859cc9 188
rgrover1 103:138bdc859cc9 189 /**@brief GATT Attribute. */
rgrover1 103:138bdc859cc9 190 typedef struct
rgrover1 103:138bdc859cc9 191 {
rgrover1 112:737b08b3b995 192 ble_uuid_t *p_uuid; /**< Pointer to the attribute UUID. */
rgrover1 112:737b08b3b995 193 ble_gatts_attr_md_t *p_attr_md; /**< Pointer to the attribute metadata structure. */
rgrover1 103:138bdc859cc9 194 uint16_t init_len; /**< Initial attribute value length in bytes. */
rgrover1 103:138bdc859cc9 195 uint16_t init_offs; /**< Initial attribute value offset in bytes. If different from zero, the first init_offs bytes of the attribute value will be left uninitialized. */
rgrover1 103:138bdc859cc9 196 uint16_t max_len; /**< Maximum attribute value length in bytes, see @ref BLE_GATTS_ATTR_LENS_MAX for maximum values. */
rgrover1 103:138bdc859cc9 197 uint8_t* p_value; /**< Pointer to the attribute data. Please note that if the @ref BLE_GATTS_VLOC_USER value location is selected in the attribute metadata, this will have to point to a buffer
rgrover1 103:138bdc859cc9 198 that remains valid through the lifetime of the attribute. This excludes usage of automatic variables that may go out of scope or any other temporary location.
rgrover1 112:737b08b3b995 199 The stack may access that memory directly without the application's knowledge. For writable characteristics, this value must not be a location in flash memory.*/
rgrover1 103:138bdc859cc9 200 } ble_gatts_attr_t;
rgrover1 103:138bdc859cc9 201
rgrover1 112:737b08b3b995 202 /**@brief GATT Attribute Value. */
rgrover1 112:737b08b3b995 203 typedef struct
rgrover1 112:737b08b3b995 204 {
rgrover1 112:737b08b3b995 205 uint16_t len; /**< Length in bytes to be written or read. Length in bytes written or read after successful return.*/
rgrover1 112:737b08b3b995 206 uint16_t offset; /**< Attribute value offset. */
rgrover1 112:737b08b3b995 207 uint8_t *p_value; /**< Pointer to where value is stored or will be stored.
rgrover1 112:737b08b3b995 208 If value is stored in user memory, only the attribute length is updated when p_value == NULL.
rgrover1 112:737b08b3b995 209 Set to NULL when reading to obtain the complete length of the attribute value */
rgrover1 112:737b08b3b995 210 } ble_gatts_value_t;
rgrover1 112:737b08b3b995 211
rgrover1 103:138bdc859cc9 212
rgrover1 103:138bdc859cc9 213 /**@brief GATT Attribute Context. */
rgrover1 103:138bdc859cc9 214 typedef struct
rgrover1 103:138bdc859cc9 215 {
rgrover1 103:138bdc859cc9 216 ble_uuid_t srvc_uuid; /**< Service UUID. */
rgrover1 112:737b08b3b995 217 ble_uuid_t char_uuid; /**< Characteristic UUID if applicable (BLE_UUID_TYPE_UNKNOWN otherwise). */
rgrover1 112:737b08b3b995 218 ble_uuid_t desc_uuid; /**< Descriptor UUID if applicable (BLE_UUID_TYPE_UNKNOWN otherwise). */
rgrover1 103:138bdc859cc9 219 uint16_t srvc_handle; /**< Service Handle. */
rgrover1 112:737b08b3b995 220 uint16_t value_handle; /**< Characteristic Value Handle if applicable (BLE_GATT_HANDLE_INVALID otherwise). */
rgrover1 103:138bdc859cc9 221 uint8_t type; /**< Attribute Type, see @ref BLE_GATTS_ATTR_TYPES. */
rgrover1 103:138bdc859cc9 222 } ble_gatts_attr_context_t;
rgrover1 103:138bdc859cc9 223
rgrover1 103:138bdc859cc9 224
rgrover1 103:138bdc859cc9 225 /**@brief GATT Characteristic Presentation Format. */
rgrover1 103:138bdc859cc9 226 typedef struct
rgrover1 103:138bdc859cc9 227 {
rgrover1 103:138bdc859cc9 228 uint8_t format; /**< Format of the value, see @ref BLE_GATT_CPF_FORMATS. */
rgrover1 103:138bdc859cc9 229 int8_t exponent; /**< Exponent for integer data types. */
rgrover1 112:737b08b3b995 230 uint16_t unit; /**< Unit from Bluetooth Assigned Numbers. */
rgrover1 103:138bdc859cc9 231 uint8_t name_space; /**< Namespace from Bluetooth Assigned Numbers, see @ref BLE_GATT_CPF_NAMESPACES. */
rgrover1 103:138bdc859cc9 232 uint16_t desc; /**< Namespace description from Bluetooth Assigned Numbers, see @ref BLE_GATT_CPF_NAMESPACES. */
rgrover1 103:138bdc859cc9 233 } ble_gatts_char_pf_t;
rgrover1 103:138bdc859cc9 234
rgrover1 103:138bdc859cc9 235
rgrover1 103:138bdc859cc9 236 /**@brief GATT Characteristic metadata. */
rgrover1 103:138bdc859cc9 237 typedef struct
rgrover1 103:138bdc859cc9 238 {
rgrover1 103:138bdc859cc9 239 ble_gatt_char_props_t char_props; /**< Characteristic Properties. */
rgrover1 103:138bdc859cc9 240 ble_gatt_char_ext_props_t char_ext_props; /**< Characteristic Extended Properties. */
rgrover1 112:737b08b3b995 241 uint8_t *p_char_user_desc; /**< Pointer to a UTF-8 encoded string (non-NULL terminated), NULL if the descriptor is not required. */
rgrover1 103:138bdc859cc9 242 uint16_t char_user_desc_max_size; /**< The maximum size in bytes of the user description descriptor. */
rgrover1 103:138bdc859cc9 243 uint16_t char_user_desc_size; /**< The size of the user description, must be smaller or equal to char_user_desc_max_size. */
rgrover1 112:737b08b3b995 244 ble_gatts_char_pf_t* p_char_pf; /**< Pointer to a presentation format structure or NULL if the CPF descriptor is not required. */
rgrover1 103:138bdc859cc9 245 ble_gatts_attr_md_t* p_user_desc_md; /**< Attribute metadata for the User Description descriptor, or NULL for default values. */
rgrover1 103:138bdc859cc9 246 ble_gatts_attr_md_t* p_cccd_md; /**< Attribute metadata for the Client Characteristic Configuration Descriptor, or NULL for default values. */
rgrover1 103:138bdc859cc9 247 ble_gatts_attr_md_t* p_sccd_md; /**< Attribute metadata for the Server Characteristic Configuration Descriptor, or NULL for default values. */
rgrover1 103:138bdc859cc9 248 } ble_gatts_char_md_t;
rgrover1 103:138bdc859cc9 249
rgrover1 103:138bdc859cc9 250
rgrover1 103:138bdc859cc9 251 /**@brief GATT Characteristic Definition Handles. */
rgrover1 103:138bdc859cc9 252 typedef struct
rgrover1 103:138bdc859cc9 253 {
rgrover1 103:138bdc859cc9 254 uint16_t value_handle; /**< Handle to the characteristic value. */
rgrover1 112:737b08b3b995 255 uint16_t user_desc_handle; /**< Handle to the User Description descriptor, or @ref BLE_GATT_HANDLE_INVALID if not present. */
rgrover1 112:737b08b3b995 256 uint16_t cccd_handle; /**< Handle to the Client Characteristic Configuration Descriptor, or @ref BLE_GATT_HANDLE_INVALID if not present. */
rgrover1 112:737b08b3b995 257 uint16_t sccd_handle; /**< Handle to the Server Characteristic Configuration Descriptor, or @ref BLE_GATT_HANDLE_INVALID if not present. */
rgrover1 103:138bdc859cc9 258 } ble_gatts_char_handles_t;
rgrover1 103:138bdc859cc9 259
rgrover1 103:138bdc859cc9 260
rgrover1 103:138bdc859cc9 261 /**@brief GATT HVx parameters. */
rgrover1 103:138bdc859cc9 262 typedef struct
rgrover1 103:138bdc859cc9 263 {
rgrover1 103:138bdc859cc9 264 uint16_t handle; /**< Characteristic Value Handle. */
rgrover1 103:138bdc859cc9 265 uint8_t type; /**< Indication or Notification, see @ref BLE_GATT_HVX_TYPES. */
rgrover1 103:138bdc859cc9 266 uint16_t offset; /**< Offset within the attribute value. */
rgrover1 112:737b08b3b995 267 uint16_t *p_len; /**< Length in bytes to be written, length in bytes written after successful return. */
rgrover1 112:737b08b3b995 268 uint8_t *p_data; /**< Actual data content, use NULL to use the current attribute value. */
rgrover1 103:138bdc859cc9 269 } ble_gatts_hvx_params_t;
rgrover1 103:138bdc859cc9 270
rgrover1 103:138bdc859cc9 271 /**@brief GATT Read Authorization parameters. */
rgrover1 103:138bdc859cc9 272 typedef struct
rgrover1 103:138bdc859cc9 273 {
rgrover1 103:138bdc859cc9 274 uint16_t gatt_status; /**< GATT status code for the operation, see @ref BLE_GATT_STATUS_CODES. */
rgrover1 103:138bdc859cc9 275 uint8_t update : 1; /**< If set, data supplied in p_data will be used in the ATT response. */
rgrover1 103:138bdc859cc9 276 uint16_t offset; /**< Offset of the attribute value being updated. */
rgrover1 103:138bdc859cc9 277 uint16_t len; /**< Length in bytes of the value in p_data pointer, see @ref BLE_GATTS_ATTR_LENS_MAX. */
rgrover1 112:737b08b3b995 278 uint8_t *p_data; /**< Pointer to new value used to update the attribute value. */
rgrover1 103:138bdc859cc9 279 } ble_gatts_read_authorize_params_t;
rgrover1 103:138bdc859cc9 280
rgrover1 112:737b08b3b995 281 /**@brief GATT Write Authorization parameters. */
rgrover1 103:138bdc859cc9 282 typedef struct
rgrover1 103:138bdc859cc9 283 {
rgrover1 103:138bdc859cc9 284 uint16_t gatt_status; /**< GATT status code for the operation, see @ref BLE_GATT_STATUS_CODES. */
rgrover1 103:138bdc859cc9 285 } ble_gatts_write_authorize_params_t;
rgrover1 103:138bdc859cc9 286
rgrover1 103:138bdc859cc9 287 /**@brief GATT Read or Write Authorize Reply parameters. */
rgrover1 103:138bdc859cc9 288 typedef struct
rgrover1 103:138bdc859cc9 289 {
rgrover1 103:138bdc859cc9 290 uint8_t type; /**< Type of authorize operation, see @ref BLE_GATTS_AUTHORIZE_TYPES. */
rgrover1 103:138bdc859cc9 291 union {
rgrover1 103:138bdc859cc9 292 ble_gatts_read_authorize_params_t read; /**< Read authorization parameters. */
rgrover1 103:138bdc859cc9 293 ble_gatts_write_authorize_params_t write; /**< Write authorization parameters. */
rgrover1 112:737b08b3b995 294 } params; /**< Reply Parameters. */
rgrover1 103:138bdc859cc9 295 } ble_gatts_rw_authorize_reply_params_t;
rgrover1 103:138bdc859cc9 296
rgrover1 103:138bdc859cc9 297
rgrover1 103:138bdc859cc9 298
rgrover1 112:737b08b3b995 299 /**@brief Event structure for @ref BLE_GATTS_EVT_WRITE. */
rgrover1 103:138bdc859cc9 300 typedef struct
rgrover1 103:138bdc859cc9 301 {
rgrover1 103:138bdc859cc9 302 uint16_t handle; /**< Attribute Handle. */
rgrover1 103:138bdc859cc9 303 uint8_t op; /**< Type of write operation, see @ref BLE_GATTS_OPS. */
rgrover1 103:138bdc859cc9 304 ble_gatts_attr_context_t context; /**< Attribute Context. */
rgrover1 103:138bdc859cc9 305 uint16_t offset; /**< Offset for the write operation. */
rgrover1 112:737b08b3b995 306 uint16_t len; /**< Length of the received data. */
rgrover1 112:737b08b3b995 307 uint8_t data[1]; /**< Received data, variable length. */
rgrover1 103:138bdc859cc9 308 } ble_gatts_evt_write_t;
rgrover1 103:138bdc859cc9 309
rgrover1 112:737b08b3b995 310 /**@brief Event substructure for authorized read requests, see @ref ble_gatts_evt_rw_authorize_request_t. */
rgrover1 103:138bdc859cc9 311 typedef struct
rgrover1 103:138bdc859cc9 312 {
rgrover1 103:138bdc859cc9 313 uint16_t handle; /**< Attribute Handle. */
rgrover1 103:138bdc859cc9 314 ble_gatts_attr_context_t context; /**< Attribute Context. */
rgrover1 103:138bdc859cc9 315 uint16_t offset; /**< Offset for the read operation. */
rgrover1 103:138bdc859cc9 316 } ble_gatts_evt_read_t;
rgrover1 103:138bdc859cc9 317
rgrover1 112:737b08b3b995 318 /**@brief Event structure for @ref BLE_GATTS_EVT_RW_AUTHORIZE_REQUEST. */
rgrover1 103:138bdc859cc9 319 typedef struct
rgrover1 103:138bdc859cc9 320 {
rgrover1 103:138bdc859cc9 321 uint8_t type; /**< Type of authorize operation, see @ref BLE_GATTS_AUTHORIZE_TYPES. */
rgrover1 103:138bdc859cc9 322 union {
rgrover1 103:138bdc859cc9 323 ble_gatts_evt_read_t read; /**< Attribute Read Parameters. */
rgrover1 103:138bdc859cc9 324 ble_gatts_evt_write_t write; /**< Attribute Write Parameters. */
rgrover1 112:737b08b3b995 325 } request; /**< Request Parameters. */
rgrover1 103:138bdc859cc9 326 } ble_gatts_evt_rw_authorize_request_t;
rgrover1 103:138bdc859cc9 327
rgrover1 112:737b08b3b995 328 /**@brief Event structure for @ref BLE_GATTS_EVT_SYS_ATTR_MISSING. */
rgrover1 103:138bdc859cc9 329 typedef struct
rgrover1 103:138bdc859cc9 330 {
rgrover1 112:737b08b3b995 331 uint8_t hint; /**< Hint (currently unused). */
rgrover1 103:138bdc859cc9 332 } ble_gatts_evt_sys_attr_missing_t;
rgrover1 103:138bdc859cc9 333
rgrover1 103:138bdc859cc9 334
rgrover1 112:737b08b3b995 335 /**@brief Event structure for @ref BLE_GATTS_EVT_HVC. */
rgrover1 103:138bdc859cc9 336 typedef struct
rgrover1 103:138bdc859cc9 337 {
rgrover1 103:138bdc859cc9 338 uint16_t handle; /**< Attribute Handle. */
rgrover1 103:138bdc859cc9 339 } ble_gatts_evt_hvc_t;
rgrover1 103:138bdc859cc9 340
rgrover1 112:737b08b3b995 341 /**@brief Event structure for @ref BLE_GATTS_EVT_TIMEOUT. */
rgrover1 103:138bdc859cc9 342 typedef struct
rgrover1 103:138bdc859cc9 343 {
rgrover1 103:138bdc859cc9 344 uint8_t src; /**< Timeout source, see @ref BLE_GATT_TIMEOUT_SOURCES. */
rgrover1 103:138bdc859cc9 345 } ble_gatts_evt_timeout_t;
rgrover1 103:138bdc859cc9 346
rgrover1 103:138bdc859cc9 347
rgrover1 103:138bdc859cc9 348 /**@brief GATT Server event callback event structure. */
rgrover1 103:138bdc859cc9 349 typedef struct
rgrover1 103:138bdc859cc9 350 {
rgrover1 112:737b08b3b995 351 uint16_t conn_handle; /**< Connection Handle on which the event occurred. */
rgrover1 103:138bdc859cc9 352 union
rgrover1 103:138bdc859cc9 353 {
rgrover1 103:138bdc859cc9 354 ble_gatts_evt_write_t write; /**< Write Event Parameters. */
rgrover1 103:138bdc859cc9 355 ble_gatts_evt_rw_authorize_request_t authorize_request; /**< Read or Write Authorize Request Parameters. */
rgrover1 103:138bdc859cc9 356 ble_gatts_evt_sys_attr_missing_t sys_attr_missing; /**< System attributes missing. */
rgrover1 103:138bdc859cc9 357 ble_gatts_evt_hvc_t hvc; /**< Handle Value Confirmation Event Parameters. */
rgrover1 103:138bdc859cc9 358 ble_gatts_evt_timeout_t timeout; /**< Timeout Event. */
rgrover1 112:737b08b3b995 359 } params; /**< Event Parameters. */
rgrover1 103:138bdc859cc9 360 } ble_gatts_evt_t;
rgrover1 103:138bdc859cc9 361
rgrover1 103:138bdc859cc9 362 /** @} */
rgrover1 103:138bdc859cc9 363
rgrover1 103:138bdc859cc9 364 /** @addtogroup BLE_GATTS_FUNCTIONS Functions
rgrover1 103:138bdc859cc9 365 * @{ */
rgrover1 103:138bdc859cc9 366
rgrover1 112:737b08b3b995 367 /**@brief Add a service declaration to the Attribute Table.
rgrover1 103:138bdc859cc9 368 *
rgrover1 103:138bdc859cc9 369 * @param[in] type Toggles between primary and secondary services, see @ref BLE_GATTS_SRVC_TYPES.
rgrover1 103:138bdc859cc9 370 * @param[in] p_uuid Pointer to service UUID.
rgrover1 103:138bdc859cc9 371 * @param[out] p_handle Pointer to a 16-bit word where the assigned handle will be stored.
rgrover1 103:138bdc859cc9 372 *
rgrover1 103:138bdc859cc9 373 * @note Secondary Services are only relevant in the context of the entity that references them, it is therefore forbidden to
rgrover1 112:737b08b3b995 374 * add a secondary service declaration that is not referenced by another service later in the Attribute Table.
rgrover1 103:138bdc859cc9 375 *
rgrover1 112:737b08b3b995 376 * @retval ::NRF_SUCCESS Successfully added a service declaration.
rgrover1 112:737b08b3b995 377 * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
rgrover1 112:737b08b3b995 378 * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied, Vendor Specific UUIDs need to be present in the table.
rgrover1 112:737b08b3b995 379 * @retval ::NRF_ERROR_FORBIDDEN Forbidden value supplied, certain UUIDs are reserved for the stack.
rgrover1 112:737b08b3b995 380 * @retval ::NRF_ERROR_NO_MEM Not enough memory to complete operation.
rgrover1 103:138bdc859cc9 381 */
rgrover1 112:737b08b3b995 382 SVCALL(SD_BLE_GATTS_SERVICE_ADD, uint32_t, sd_ble_gatts_service_add(uint8_t type, ble_uuid_t const *p_uuid, uint16_t *p_handle));
rgrover1 103:138bdc859cc9 383
rgrover1 103:138bdc859cc9 384
rgrover1 112:737b08b3b995 385 /**@brief Add an include declaration to the Attribute Table.
rgrover1 103:138bdc859cc9 386 *
rgrover1 112:737b08b3b995 387 * @note It is currently only possible to add an include declaration to the last added service (i.e. only sequential population is supported at this time).
rgrover1 103:138bdc859cc9 388 *
rgrover1 112:737b08b3b995 389 * @note The included service must already be present in the Attribute Table prior to this call.
rgrover1 103:138bdc859cc9 390 *
rgrover1 112:737b08b3b995 391 * @param[in] service_handle Handle of the service where the included service is to be placed, if @ref BLE_GATT_HANDLE_INVALID is used, it will be placed sequentially.
rgrover1 103:138bdc859cc9 392 * @param[in] inc_srvc_handle Handle of the included service.
rgrover1 103:138bdc859cc9 393 * @param[out] p_include_handle Pointer to a 16-bit word where the assigned handle will be stored.
rgrover1 103:138bdc859cc9 394 *
rgrover1 112:737b08b3b995 395 * @retval ::NRF_SUCCESS Successfully added an include declaration.
rgrover1 112:737b08b3b995 396 * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
rgrover1 112:737b08b3b995 397 * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied, handle values need to match previously added services.
rgrover1 112:737b08b3b995 398 * @retval ::NRF_ERROR_INVALID_STATE Invalid state to perform operation.
rgrover1 112:737b08b3b995 399 * @retval ::NRF_ERROR_FORBIDDEN Forbidden value supplied, self inclusions are not allowed.
rgrover1 112:737b08b3b995 400 * @retval ::NRF_ERROR_NO_MEM Not enough memory to complete operation.
rgrover1 112:737b08b3b995 401 * @retval ::NRF_ERROR_NOT_FOUND Attribute not found.
rgrover1 103:138bdc859cc9 402 */
rgrover1 112:737b08b3b995 403 SVCALL(SD_BLE_GATTS_INCLUDE_ADD, uint32_t, sd_ble_gatts_include_add(uint16_t service_handle, uint16_t inc_srvc_handle, uint16_t *p_include_handle));
rgrover1 103:138bdc859cc9 404
rgrover1 103:138bdc859cc9 405
rgrover1 112:737b08b3b995 406 /**@brief Add a characteristic declaration, a characteristic value declaration and optional characteristic descriptor declarations to the Attribute Table.
rgrover1 103:138bdc859cc9 407 *
rgrover1 112:737b08b3b995 408 * @note It is currently only possible to add a characteristic to the last added service (i.e. only sequential population is supported at this time).
rgrover1 103:138bdc859cc9 409 *
rgrover1 103:138bdc859cc9 410 * @note Several restrictions apply to the parameters, such as matching permissions between the user description descriptor and the writeable auxiliaries bits,
rgrover1 103:138bdc859cc9 411 * readable (no security) and writeable (selectable) CCCDs and SCCDs and valid presentation format values.
rgrover1 103:138bdc859cc9 412 *
rgrover1 103:138bdc859cc9 413 * @note If no metadata is provided for the optional descriptors, their permissions will be derived from the characteristic permissions.
rgrover1 103:138bdc859cc9 414 *
rgrover1 112:737b08b3b995 415 * @param[in] service_handle Handle of the service where the characteristic is to be placed, if @ref BLE_GATT_HANDLE_INVALID is used, it will be placed sequentially.
rgrover1 103:138bdc859cc9 416 * @param[in] p_char_md Characteristic metadata.
rgrover1 103:138bdc859cc9 417 * @param[in] p_attr_char_value Pointer to the attribute structure corresponding to the characteristic value.
rgrover1 103:138bdc859cc9 418 * @param[out] p_handles Pointer to the structure where the assigned handles will be stored.
rgrover1 103:138bdc859cc9 419 *
rgrover1 112:737b08b3b995 420 * @retval ::NRF_SUCCESS Successfully added a characteristic.
rgrover1 112:737b08b3b995 421 * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
rgrover1 112:737b08b3b995 422 * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied, service handle, Vendor Specific UUIDs, lengths, and permissions need to adhere to the constraints.
rgrover1 112:737b08b3b995 423 * @retval ::NRF_ERROR_INVALID_STATE Invalid state to perform operation, a service context is required.
rgrover1 112:737b08b3b995 424 * @retval ::NRF_ERROR_FORBIDDEN Forbidden value supplied, certain UUIDs are reserved for the stack.
rgrover1 112:737b08b3b995 425 * @retval ::NRF_ERROR_NO_MEM Not enough memory to complete operation.
rgrover1 112:737b08b3b995 426 * @retval ::NRF_ERROR_DATA_SIZE Invalid data size(s) supplied, attribute lengths are restricted by @ref BLE_GATTS_ATTR_LENS_MAX.
rgrover1 103:138bdc859cc9 427 */
rgrover1 112:737b08b3b995 428 SVCALL(SD_BLE_GATTS_CHARACTERISTIC_ADD, uint32_t, sd_ble_gatts_characteristic_add(uint16_t service_handle, ble_gatts_char_md_t const *p_char_md, ble_gatts_attr_t const *p_attr_char_value, ble_gatts_char_handles_t *p_handles));
rgrover1 103:138bdc859cc9 429
rgrover1 103:138bdc859cc9 430
rgrover1 112:737b08b3b995 431 /**@brief Add a descriptor to the Attribute Table.
rgrover1 103:138bdc859cc9 432 *
rgrover1 112:737b08b3b995 433 * @note It is currently only possible to add a descriptor to the last added characteristic (i.e. only sequential population is supported at this time).
rgrover1 103:138bdc859cc9 434 *
rgrover1 112:737b08b3b995 435 * @param[in] char_handle Handle of the characteristic where the descriptor is to be placed, if @ref BLE_GATT_HANDLE_INVALID is used, it will be placed sequentially.
rgrover1 103:138bdc859cc9 436 * @param[in] p_attr Pointer to the attribute structure.
rgrover1 103:138bdc859cc9 437 * @param[out] p_handle Pointer to a 16-bit word where the assigned handle will be stored.
rgrover1 103:138bdc859cc9 438 *
rgrover1 112:737b08b3b995 439 * @retval ::NRF_SUCCESS Successfully added a descriptor.
rgrover1 112:737b08b3b995 440 * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
rgrover1 112:737b08b3b995 441 * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied, characteristic handle, Vendor Specific UUIDs, lengths, and permissions need to adhere to the constraints.
rgrover1 112:737b08b3b995 442 * @retval ::NRF_ERROR_INVALID_STATE Invalid state to perform operation, a characteristic context is required.
rgrover1 112:737b08b3b995 443 * @retval ::NRF_ERROR_FORBIDDEN Forbidden value supplied, certain UUIDs are reserved for the stack.
rgrover1 112:737b08b3b995 444 * @retval ::NRF_ERROR_NO_MEM Not enough memory to complete operation.
rgrover1 112:737b08b3b995 445 * @retval ::NRF_ERROR_DATA_SIZE Invalid data size(s) supplied, attribute lengths are restricted by @ref BLE_GATTS_ATTR_LENS_MAX.
rgrover1 103:138bdc859cc9 446 */
rgrover1 112:737b08b3b995 447 SVCALL(SD_BLE_GATTS_DESCRIPTOR_ADD, uint32_t, sd_ble_gatts_descriptor_add(uint16_t char_handle, ble_gatts_attr_t const *p_attr, uint16_t *p_handle));
rgrover1 103:138bdc859cc9 448
rgrover1 103:138bdc859cc9 449 /**@brief Set the value of a given attribute.
rgrover1 103:138bdc859cc9 450 *
rgrover1 112:737b08b3b995 451 * @param[in] conn_handle Connection handle. If the value does not belong to a system attribute then @ref BLE_CONN_HANDLE_INVALID can be used.
rgrover1 112:737b08b3b995 452 * @param[in] handle Attribute handle.
rgrover1 112:737b08b3b995 453 * @param[in,out] p_value Attribute value information.
rgrover1 112:737b08b3b995 454 *
rgrover1 112:737b08b3b995 455 * @note Values other than system attributes can be set at any time, regardless of wheter any active connections exist.
rgrover1 103:138bdc859cc9 456 *
rgrover1 112:737b08b3b995 457 * @retval ::NRF_SUCCESS Successfully set the value of the attribute.
rgrover1 112:737b08b3b995 458 * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
rgrover1 112:737b08b3b995 459 * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied.
rgrover1 112:737b08b3b995 460 * @retval ::NRF_ERROR_NOT_FOUND Attribute not found.
rgrover1 112:737b08b3b995 461 * @retval ::NRF_ERROR_FORBIDDEN Forbidden handle supplied, certain attributes are not modifiable by the application.
rgrover1 112:737b08b3b995 462 * @retval ::NRF_ERROR_DATA_SIZE Invalid data size(s) supplied, attribute lengths are restricted by @ref BLE_GATTS_ATTR_LENS_MAX.
rgrover1 112:737b08b3b995 463 * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid connection handle supplied.
rgrover1 112:737b08b3b995 464 * @retval ::BLE_ERROR_GATTS_INVALID_ATTR_TYPE @ref BLE_CONN_HANDLE_INVALID supplied on a system attribute.
rgrover1 103:138bdc859cc9 465 */
rgrover1 112:737b08b3b995 466 SVCALL(SD_BLE_GATTS_VALUE_SET, uint32_t, sd_ble_gatts_value_set(uint16_t conn_handle, uint16_t handle, ble_gatts_value_t *p_value));
rgrover1 103:138bdc859cc9 467
rgrover1 103:138bdc859cc9 468 /**@brief Get the value of a given attribute.
rgrover1 103:138bdc859cc9 469 *
rgrover1 112:737b08b3b995 470 * @param[in] conn_handle Connection handle. If the value does not belong to a system attribute then @ref BLE_CONN_HANDLE_INVALID can be used.
rgrover1 112:737b08b3b995 471 * @param[in] handle Attribute handle.
rgrover1 112:737b08b3b995 472 * @param[in,out] p_value Attribute value information.
rgrover1 103:138bdc859cc9 473 *
rgrover1 103:138bdc859cc9 474 * @note If the attribute value is longer than the size of the supplied buffer,
rgrover1 103:138bdc859cc9 475 * p_len will return the total attribute value length (excluding offset),
rgrover1 103:138bdc859cc9 476 * and not the number of bytes actually returned in p_data.
rgrover1 103:138bdc859cc9 477 * The application may use this information to allocate a suitable buffer size.
rgrover1 103:138bdc859cc9 478 *
rgrover1 112:737b08b3b995 479 * @note When retrieving system attribute values with this function, the connection handle
rgrover1 112:737b08b3b995 480 * may refer to an already disconnected connection. Refer to the documentation of
rgrover1 112:737b08b3b995 481 * @ref sd_ble_gatts_sys_attr_get for further information.
rgrover1 112:737b08b3b995 482 *
rgrover1 112:737b08b3b995 483 * @retval ::NRF_SUCCESS Successfully retrieved the value of the attribute.
rgrover1 112:737b08b3b995 484 * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
rgrover1 112:737b08b3b995 485 * @retval ::NRF_ERROR_NOT_FOUND Attribute not found.
rgrover1 112:737b08b3b995 486 * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid connection handle supplied.
rgrover1 112:737b08b3b995 487 * @retval ::BLE_ERROR_GATTS_INVALID_ATTR_TYPE @ref BLE_CONN_HANDLE_INVALID supplied on a system attribute.
rgrover1 103:138bdc859cc9 488 */
rgrover1 112:737b08b3b995 489 SVCALL(SD_BLE_GATTS_VALUE_GET, uint32_t, sd_ble_gatts_value_get(uint16_t conn_handle, uint16_t handle, ble_gatts_value_t *p_value));
rgrover1 103:138bdc859cc9 490
rgrover1 103:138bdc859cc9 491 /**@brief Notify or Indicate an attribute value.
rgrover1 103:138bdc859cc9 492 *
rgrover1 103:138bdc859cc9 493 * @details This function checks for the relevant Client Characteristic Configuration descriptor value to verify that the relevant operation
rgrover1 103:138bdc859cc9 494 * (notification or indication) has been enabled by the client. It is also able to update the attribute value before issuing the PDU, so that
rgrover1 103:138bdc859cc9 495 * the application can atomically perform a value update and a server initiated transaction with a single API call.
rgrover1 112:737b08b3b995 496 * If the application chooses to indicate an attribute value, a @ref BLE_GATTS_EVT_HVC event will be issued as soon as the confirmation arrives from
rgrover1 103:138bdc859cc9 497 * the peer.
rgrover1 103:138bdc859cc9 498 *
rgrover1 103:138bdc859cc9 499 * @note The local attribute value may be updated even if an outgoing packet is not sent to the peer due to an error during execution.
rgrover1 103:138bdc859cc9 500 * When receiveing the error codes @ref NRF_ERROR_INVALID_STATE, @ref NRF_ERROR_BUSY, @ref BLE_ERROR_GATTS_SYS_ATTR_MISSING and
rgrover1 112:737b08b3b995 501 * @ref BLE_ERROR_NO_TX_BUFFERS the Attribute Table has been updated.
rgrover1 103:138bdc859cc9 502 * The caller can check whether the value has been updated by looking at the contents of *(p_hvx_params->p_len).
rgrover1 103:138bdc859cc9 503 *
rgrover1 103:138bdc859cc9 504 * @note It is important to note that a notification will <b>consume an application buffer</b>, and will therefore
rgrover1 103:138bdc859cc9 505 * generate a @ref BLE_EVT_TX_COMPLETE event when the packet has been transmitted. An indication on the other hand will use the
rgrover1 103:138bdc859cc9 506 * standard server internal buffer and thus will only generate a @ref BLE_GATTS_EVT_HVC event as soon as the confirmation
rgrover1 103:138bdc859cc9 507 * has been received from the peer. Please see the documentation of @ref sd_ble_tx_buffer_count_get for more details.
rgrover1 103:138bdc859cc9 508 *
rgrover1 103:138bdc859cc9 509 * @param[in] conn_handle Connection handle.
rgrover1 103:138bdc859cc9 510 * @param[in] p_hvx_params Pointer to an HVx parameters structure. If the p_data member contains a non-NULL pointer the attribute value will be updated with
rgrover1 103:138bdc859cc9 511 * the contents pointed by it before sending the notification or indication.
rgrover1 103:138bdc859cc9 512 *
rgrover1 112:737b08b3b995 513 * @retval ::NRF_SUCCESS Successfully queued a notification or indication for transmission, and optionally updated the attribute value.
rgrover1 112:737b08b3b995 514 * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid Connection Handle.
rgrover1 112:737b08b3b995 515 * @retval ::NRF_ERROR_INVALID_STATE Invalid Connection State or notifications and/or indications not enabled in the CCCD.
rgrover1 112:737b08b3b995 516 * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
rgrover1 112:737b08b3b995 517 * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied.
rgrover1 112:737b08b3b995 518 * @retval ::BLE_ERROR_INVALID_ATTR_HANDLE Invalid attribute handle(s) supplied. Only attributes added directly by the application are available to notify and indicate.
rgrover1 112:737b08b3b995 519 * @retval ::BLE_ERROR_GATTS_INVALID_ATTR_TYPE Invalid attribute type(s) supplied, only characteristic values may be notified and indicated.
rgrover1 112:737b08b3b995 520 * @retval ::NRF_ERROR_NOT_FOUND Attribute not found.
rgrover1 112:737b08b3b995 521 * @retval ::NRF_ERROR_DATA_SIZE Invalid data size(s) supplied.
rgrover1 112:737b08b3b995 522 * @retval ::NRF_ERROR_BUSY Procedure already in progress.
rgrover1 112:737b08b3b995 523 * @retval ::BLE_ERROR_GATTS_SYS_ATTR_MISSING System attributes missing, use @ref sd_ble_gatts_sys_attr_set to set them to a known value.
rgrover1 112:737b08b3b995 524 * @retval ::BLE_ERROR_NO_TX_BUFFERS There are no available buffers to send the data, applies only to notifications.
rgrover1 103:138bdc859cc9 525 */
rgrover1 112:737b08b3b995 526 SVCALL(SD_BLE_GATTS_HVX, uint32_t, sd_ble_gatts_hvx(uint16_t conn_handle, ble_gatts_hvx_params_t const *p_hvx_params));
rgrover1 103:138bdc859cc9 527
rgrover1 103:138bdc859cc9 528 /**@brief Indicate the Service Changed attribute value.
rgrover1 103:138bdc859cc9 529 *
rgrover1 112:737b08b3b995 530 * @details This call will send a Handle Value Indication to one or more peers connected to inform them that the Attribute
rgrover1 112:737b08b3b995 531 * Table layout has changed. As soon as the peer has confirmed the indication, a @ref BLE_GATTS_EVT_SC_CONFIRM event will
rgrover1 103:138bdc859cc9 532 * be issued.
rgrover1 103:138bdc859cc9 533 *
rgrover1 103:138bdc859cc9 534 * @note Some of the restrictions and limitations that apply to @ref sd_ble_gatts_hvx also apply here.
rgrover1 103:138bdc859cc9 535 *
rgrover1 103:138bdc859cc9 536 * @param[in] conn_handle Connection handle.
rgrover1 103:138bdc859cc9 537 * @param[in] start_handle Start of affected attribute handle range.
rgrover1 103:138bdc859cc9 538 * @param[in] end_handle End of affected attribute handle range.
rgrover1 103:138bdc859cc9 539 *
rgrover1 112:737b08b3b995 540 * @retval ::NRF_SUCCESS Successfully queued the Service Changed indication for transmission.
rgrover1 112:737b08b3b995 541 * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid Connection Handle.
rgrover1 112:737b08b3b995 542 * @retval ::NRF_ERROR_INVALID_STATE Invalid Connection State or notifications and/or indications not enabled in the CCCD.
rgrover1 112:737b08b3b995 543 * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied.
rgrover1 112:737b08b3b995 544 * @retval ::BLE_ERROR_INVALID_ATTR_HANDLE Invalid attribute handle(s) supplied, handles must be in the range populated by the application.
rgrover1 112:737b08b3b995 545 * @retval ::NRF_ERROR_INVALID_STATE Invalid state to perform operation, notifications or indications must be enabled in the CCCD.
rgrover1 112:737b08b3b995 546 * @retval ::NRF_ERROR_BUSY Procedure already in progress.
rgrover1 112:737b08b3b995 547 * @retval ::BLE_ERROR_GATTS_SYS_ATTR_MISSING System attributes missing, use @ref sd_ble_gatts_sys_attr_set to set them to a known value.
rgrover1 103:138bdc859cc9 548 */
rgrover1 103:138bdc859cc9 549 SVCALL(SD_BLE_GATTS_SERVICE_CHANGED, uint32_t, sd_ble_gatts_service_changed(uint16_t conn_handle, uint16_t start_handle, uint16_t end_handle));
rgrover1 103:138bdc859cc9 550
rgrover1 103:138bdc859cc9 551 /**@brief Respond to a Read/Write authorization request.
rgrover1 103:138bdc859cc9 552 *
rgrover1 103:138bdc859cc9 553 * @note This call should only be used as a response to a @ref BLE_GATTS_EVT_RW_AUTHORIZE_REQUEST event issued to the application.
rgrover1 103:138bdc859cc9 554 *
rgrover1 103:138bdc859cc9 555 * @param[in] conn_handle Connection handle.
rgrover1 103:138bdc859cc9 556 * @param[in] p_rw_authorize_reply_params Pointer to a structure with the attribute provided by the application.
rgrover1 103:138bdc859cc9 557 *
rgrover1 112:737b08b3b995 558 * @retval ::NRF_SUCCESS Successfully queued a response to the peer, and in the case of a write operation, Attribute Table updated.
rgrover1 112:737b08b3b995 559 * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid Connection Handle.
rgrover1 112:737b08b3b995 560 * @retval ::NRF_ERROR_INVALID_STATE Invalid Connection State or no authorization request pending.
rgrover1 112:737b08b3b995 561 * @retval ::NRF_ERROR_INVALID_PARAM Authorization op invalid,
rgrover1 103:138bdc859cc9 562 * or for Read Authorization reply: requested handles not replied with,
rgrover1 103:138bdc859cc9 563 * or for Write Authorization reply: handle supplied does not match requested handle.
rgrover1 112:737b08b3b995 564 * @retval ::NRF_ERROR_BUSY The stack is busy. Retry at later time.
rgrover1 103:138bdc859cc9 565 */
rgrover1 112:737b08b3b995 566 SVCALL(SD_BLE_GATTS_RW_AUTHORIZE_REPLY, uint32_t, sd_ble_gatts_rw_authorize_reply(uint16_t conn_handle, ble_gatts_rw_authorize_reply_params_t const *p_rw_authorize_reply_params));
rgrover1 103:138bdc859cc9 567
rgrover1 103:138bdc859cc9 568
rgrover1 103:138bdc859cc9 569 /**@brief Update persistent system attribute information.
rgrover1 103:138bdc859cc9 570 *
rgrover1 112:737b08b3b995 571 * @details Supply information about persistent system attributes to the stack,
rgrover1 112:737b08b3b995 572 * previously obtained using @ref sd_ble_gatts_sys_attr_get.
rgrover1 112:737b08b3b995 573 * This call is only allowed for active connections, and is usually
rgrover1 112:737b08b3b995 574 * made immediately after a connection is established with an known bonded device,
rgrover1 112:737b08b3b995 575 * often as a response to a @ref BLE_GATTS_EVT_SYS_ATTR_MISSING.
rgrover1 103:138bdc859cc9 576 *
rgrover1 112:737b08b3b995 577 * p_sysattrs may point directly to the application's stored copy of the system attributes
rgrover1 112:737b08b3b995 578 * obtained using @ref sd_ble_gatts_sys_attr_get.
rgrover1 103:138bdc859cc9 579 * If the pointer is NULL, the system attribute info is initialized, assuming that
rgrover1 112:737b08b3b995 580 * the application does not have any previously saved system attribute data for this device.
rgrover1 103:138bdc859cc9 581 *
rgrover1 112:737b08b3b995 582 * @note The state of persistent system attributes is reset upon connection establishment and then remembered for its duration.
rgrover1 103:138bdc859cc9 583 *
rgrover1 103:138bdc859cc9 584 * @note If this call returns with an error code different from @ref NRF_SUCCESS, the storage of persistent system attributes may have been completed only partially.
rgrover1 103:138bdc859cc9 585 * This means that the state of the attribute table is undefined, and the application should either provide a new set of attributes using this same call or
rgrover1 103:138bdc859cc9 586 * reset the SoftDevice to return to a known state.
rgrover1 103:138bdc859cc9 587 *
rgrover1 112:737b08b3b995 588 * @note When the @ref BLE_GATTS_SYS_ATTR_FLAG_SYS_SRVCS is used with this function, only the system attributes included in system services will be modified.
rgrover1 112:737b08b3b995 589 * @note When the @ref BLE_GATTS_SYS_ATTR_FLAG_USR_SRVCS is used with this function, only the system attributes included in user services will be modified.
rgrover1 112:737b08b3b995 590 *
rgrover1 103:138bdc859cc9 591 * @param[in] conn_handle Connection handle.
rgrover1 103:138bdc859cc9 592 * @param[in] p_sys_attr_data Pointer to a saved copy of system attributes supplied to the stack, or NULL.
rgrover1 103:138bdc859cc9 593 * @param[in] len Size of data pointed by p_sys_attr_data, in octets.
rgrover1 112:737b08b3b995 594 * @param[in] flags Optional additional flags, see @ref BLE_GATTS_SYS_ATTR_FLAGS
rgrover1 103:138bdc859cc9 595 *
rgrover1 112:737b08b3b995 596 * @retval ::NRF_SUCCESS Successfully set the system attribute information.
rgrover1 112:737b08b3b995 597 * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid Connection Handle.
rgrover1 112:737b08b3b995 598 * @retval ::NRF_ERROR_INVALID_STATE Invalid Connection State.
rgrover1 112:737b08b3b995 599 * @retval ::NRF_ERROR_INVALID_DATA Invalid data supplied, the data should be exactly the same as retrieved with @ref sd_ble_gatts_sys_attr_get.
rgrover1 112:737b08b3b995 600 * @retval ::NRF_ERROR_NO_MEM Not enough memory to complete operation.
rgrover1 112:737b08b3b995 601 * @retval ::NRF_ERROR_BUSY The stack is busy. Retry at later time.
rgrover1 103:138bdc859cc9 602 */
rgrover1 112:737b08b3b995 603 SVCALL(SD_BLE_GATTS_SYS_ATTR_SET, uint32_t, sd_ble_gatts_sys_attr_set(uint16_t conn_handle, uint8_t const *p_sys_attr_data, uint16_t len, uint32_t flags));
rgrover1 103:138bdc859cc9 604
rgrover1 103:138bdc859cc9 605
rgrover1 103:138bdc859cc9 606 /**@brief Retrieve persistent system attribute information from the stack.
rgrover1 103:138bdc859cc9 607 *
rgrover1 103:138bdc859cc9 608 * @details This call is used to retrieve information about values to be stored perisistently by the application
rgrover1 112:737b08b3b995 609 * during the lifetime of a connection or after it has been terminated. When a new connection is established with the same bonded device,
rgrover1 112:737b08b3b995 610 * the system attribute information retrieved with this function should be restored using using @ref sd_ble_gatts_sys_attr_set.
rgrover1 112:737b08b3b995 611 * If retrieved after disconnection, the data should be read before a new connection established. The connection handle for
rgrover1 112:737b08b3b995 612 * the previous, now disconnected, connection will remain valid until a new one is created to allow this API call to refer to it.
rgrover1 112:737b08b3b995 613 * Connection handles belonging to active connections can be used as well, but care should be taken since the system attributes
rgrover1 112:737b08b3b995 614 * may be written to at any time by the peer during a connection's lifetime.
rgrover1 112:737b08b3b995 615 *
rgrover1 112:737b08b3b995 616 * @note When the @ref BLE_GATTS_SYS_ATTR_FLAG_SYS_SRVCS is used with this function, only the system attributes included in system services will be returned.
rgrover1 112:737b08b3b995 617 * @note When the @ref BLE_GATTS_SYS_ATTR_FLAG_USR_SRVCS is used with this function, only the system attributes included in user services will be returned.
rgrover1 103:138bdc859cc9 618 *
rgrover1 103:138bdc859cc9 619 * @param[in] conn_handle Connection handle of the recently terminated connection.
rgrover1 112:737b08b3b995 620 * @param[out] p_sys_attr_data Pointer to a buffer where updated information about system attributes will be filled in. NULL can be provided to
rgrover1 103:138bdc859cc9 621 * obtain the length of the data
rgrover1 103:138bdc859cc9 622 * @param[in,out] p_len Size of application buffer if p_sys_attr_data is not NULL. Unconditially updated to actual length of system attribute data.
rgrover1 112:737b08b3b995 623 * @param[in] flags Optional additional flags, see @ref BLE_GATTS_SYS_ATTR_FLAGS
rgrover1 103:138bdc859cc9 624 *
rgrover1 112:737b08b3b995 625 * @retval ::NRF_SUCCESS Successfully retrieved the system attribute information.
rgrover1 112:737b08b3b995 626 * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid Connection Handle.
rgrover1 112:737b08b3b995 627 * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
rgrover1 112:737b08b3b995 628 * @retval ::NRF_ERROR_DATA_SIZE The system attribute information did not fit into the provided buffer.
rgrover1 112:737b08b3b995 629 * @retval ::NRF_ERROR_NOT_FOUND No system attributes found.
rgrover1 103:138bdc859cc9 630 */
rgrover1 112:737b08b3b995 631 SVCALL(SD_BLE_GATTS_SYS_ATTR_GET, uint32_t, sd_ble_gatts_sys_attr_get(uint16_t conn_handle, uint8_t *p_sys_attr_data, uint16_t *p_len, uint32_t flags));
rgrover1 103:138bdc859cc9 632
rgrover1 103:138bdc859cc9 633 /** @} */
rgrover1 103:138bdc859cc9 634
rgrover1 103:138bdc859cc9 635 #endif // BLE_GATTS_H__
rgrover1 103:138bdc859cc9 636
rgrover1 103:138bdc859cc9 637 /**
rgrover1 103:138bdc859cc9 638 @}
rgrover1 103:138bdc859cc9 639 */