/* * Copyright (c) Nordic Semiconductor ASA * All rights reserved. * * Redistribution and use in source and binary forms, with or without modification, * are permitted provided that the following conditions are met: * * 1. Redistributions of source code must retain the above copyright notice, this * list of conditions and the following disclaimer. * * 2. Redistributions in binary form must reproduce the above copyright notice, this * list of conditions and the following disclaimer in the documentation and/or * other materials provided with the distribution. * * 3. Neither the name of Nordic Semiconductor ASA nor the names of other * contributors to this software may be used to endorse or promote products * derived from this software without specific prior written permission. * * 4. This software must only be used in a processor manufactured by Nordic * Semiconductor ASA, or in a processor manufactured by a third party that * is used in combination with a processor manufactured by Nordic Semiconductor. * * * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. * */ /** @addtogroup BLE_GATTS Generic Attribute Profile (GATT) Server @{ @brief Definitions and prototypes for the GATTS interface. */ #ifndef BLE_GATTS_H__ #define BLE_GATTS_H__ #include "ble_types.h" #include "ble_ranges.h" #include "ble_l2cap.h" #include "ble_gap.h" #include "ble_gatt.h" #include "nrf_svc.h" #ifdef __cplusplus extern "C" { #endif /** @addtogroup BLE_GATTS_ENUMERATIONS Enumerations * @{ */ /** * @brief GATTS API SVC numbers. */ enum BLE_GATTS_SVCS { SD_BLE_GATTS_SERVICE_ADD = BLE_GATTS_SVC_BASE, /**< Add a service. */ SD_BLE_GATTS_INCLUDE_ADD, /**< Add an included service. */ SD_BLE_GATTS_CHARACTERISTIC_ADD, /**< Add a characteristic. */ SD_BLE_GATTS_DESCRIPTOR_ADD, /**< Add a generic attribute. */ SD_BLE_GATTS_VALUE_SET, /**< Set an attribute value. */ SD_BLE_GATTS_VALUE_GET, /**< Get an attribute value. */ SD_BLE_GATTS_HVX, /**< Handle Value Notification or Indication. */ SD_BLE_GATTS_SERVICE_CHANGED, /**< Perform a Service Changed Indication to one or more peers. */ SD_BLE_GATTS_RW_AUTHORIZE_REPLY, /**< Reply to an authorization request for a read or write operation on one or more attributes. */ SD_BLE_GATTS_SYS_ATTR_SET, /**< Set the persistent system attributes for a connection. */ SD_BLE_GATTS_SYS_ATTR_GET, /**< Retrieve the persistent system attributes. */ SD_BLE_GATTS_INITIAL_USER_HANDLE_GET, /**< Retrieve the first valid user handle. */ SD_BLE_GATTS_ATTR_GET, /**< Retrieve the UUID and/or metadata of an attribute. */ SD_BLE_GATTS_EXCHANGE_MTU_REPLY /**< Reply to Exchange MTU Request. */ }; /** * @brief GATT Server Event IDs. */ enum BLE_GATTS_EVTS { BLE_GATTS_EVT_WRITE = BLE_GATTS_EVT_BASE, /**< Write operation performed. \n See @ref ble_gatts_evt_write_t. */ BLE_GATTS_EVT_RW_AUTHORIZE_REQUEST, /**< Read/Write Authorization request. \n Reply with @ref sd_ble_gatts_rw_authorize_reply. \n See @ref ble_gatts_evt_rw_authorize_request_t. */ BLE_GATTS_EVT_SYS_ATTR_MISSING, /**< A persistent system attribute access is pending. \n Respond with @ref sd_ble_gatts_sys_attr_set. \n See @ref ble_gatts_evt_sys_attr_missing_t. */ BLE_GATTS_EVT_HVC, /**< Handle Value Confirmation. \n See @ref ble_gatts_evt_hvc_t. */ BLE_GATTS_EVT_SC_CONFIRM, /**< Service Changed Confirmation. \n No additional event structure applies. */ BLE_GATTS_EVT_EXCHANGE_MTU_REQUEST, /**< Exchange MTU Request. \n Reply with @ref sd_ble_gatts_exchange_mtu_reply. \n See @ref ble_gatts_evt_exchange_mtu_request_t. */ BLE_GATTS_EVT_TIMEOUT, /**< Peer failed to respond to an ATT request in time. \n See @ref ble_gatts_evt_timeout_t. */ BLE_GATTS_EVT_HVN_TX_COMPLETE /**< Handle Value Notification transmission complete. \n See @ref ble_gatts_evt_hvn_tx_complete_t. */ }; /**@brief GATTS Configuration IDs. * * IDs that uniquely identify a GATTS configuration. */ enum BLE_GATTS_CFGS { BLE_GATTS_CFG_SERVICE_CHANGED = BLE_GATTS_CFG_BASE, /**< Service changed configuration. */ BLE_GATTS_CFG_ATTR_TAB_SIZE, /**< Attribute table size configuration. */ }; /** @} */ /** @addtogroup BLE_GATTS_DEFINES Defines * @{ */ /** @defgroup BLE_ERRORS_GATTS SVC return values specific to GATTS * @{ */ #define BLE_ERROR_GATTS_INVALID_ATTR_TYPE (NRF_GATTS_ERR_BASE + 0x000) /**< Invalid attribute type. */ #define BLE_ERROR_GATTS_SYS_ATTR_MISSING (NRF_GATTS_ERR_BASE + 0x001) /**< System Attributes missing. */ /** @} */ /** @defgroup BLE_GATTS_ATTR_LENS_MAX Maximum attribute lengths * @{ */ #define BLE_GATTS_FIX_ATTR_LEN_MAX (510) /**< Maximum length for fixed length Attribute Values. */ #define BLE_GATTS_VAR_ATTR_LEN_MAX (512) /**< Maximum length for variable length Attribute Values. */ /** @} */ /** @defgroup BLE_GATTS_SRVC_TYPES GATT Server Service Types * @{ */ #define BLE_GATTS_SRVC_TYPE_INVALID 0x00 /**< Invalid Service Type. */ #define BLE_GATTS_SRVC_TYPE_PRIMARY 0x01 /**< Primary Service. */ #define BLE_GATTS_SRVC_TYPE_SECONDARY 0x02 /**< Secondary Type. */ /** @} */ /** @defgroup BLE_GATTS_ATTR_TYPES GATT Server Attribute Types * @{ */ #define BLE_GATTS_ATTR_TYPE_INVALID 0x00 /**< Invalid Attribute Type. */ #define BLE_GATTS_ATTR_TYPE_PRIM_SRVC_DECL 0x01 /**< Primary Service Declaration. */ #define BLE_GATTS_ATTR_TYPE_SEC_SRVC_DECL 0x02 /**< Secondary Service Declaration. */ #define BLE_GATTS_ATTR_TYPE_INC_DECL 0x03 /**< Include Declaration. */ #define BLE_GATTS_ATTR_TYPE_CHAR_DECL 0x04 /**< Characteristic Declaration. */ #define BLE_GATTS_ATTR_TYPE_CHAR_VAL 0x05 /**< Characteristic Value. */ #define BLE_GATTS_ATTR_TYPE_DESC 0x06 /**< Descriptor. */ #define BLE_GATTS_ATTR_TYPE_OTHER 0x07 /**< Other, non-GATT specific type. */ /** @} */ /** @defgroup BLE_GATTS_OPS GATT Server Operations * @{ */ #define BLE_GATTS_OP_INVALID 0x00 /**< Invalid Operation. */ #define BLE_GATTS_OP_WRITE_REQ 0x01 /**< Write Request. */ #define BLE_GATTS_OP_WRITE_CMD 0x02 /**< Write Command. */ #define BLE_GATTS_OP_SIGN_WRITE_CMD 0x03 /**< Signed Write Command. */ #define BLE_GATTS_OP_PREP_WRITE_REQ 0x04 /**< Prepare Write Request. */ #define BLE_GATTS_OP_EXEC_WRITE_REQ_CANCEL 0x05 /**< Execute Write Request: Cancel all prepared writes. */ #define BLE_GATTS_OP_EXEC_WRITE_REQ_NOW 0x06 /**< Execute Write Request: Immediately execute all prepared writes. */ /** @} */ /** @defgroup BLE_GATTS_VLOCS GATT Value Locations * @{ */ #define BLE_GATTS_VLOC_INVALID 0x00 /**< Invalid Location. */ #define BLE_GATTS_VLOC_STACK 0x01 /**< Attribute Value is located in stack memory, no user memory is required. */ #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 will read and write directly to the memory using the pointer provided in the APIs. There are no alignment requirements for the buffer. */ /** @} */ /** @defgroup BLE_GATTS_AUTHORIZE_TYPES GATT Server Authorization Types * @{ */ #define BLE_GATTS_AUTHORIZE_TYPE_INVALID 0x00 /**< Invalid Type. */ #define BLE_GATTS_AUTHORIZE_TYPE_READ 0x01 /**< Authorize a Read Operation. */ #define BLE_GATTS_AUTHORIZE_TYPE_WRITE 0x02 /**< Authorize a Write Request Operation. */ /** @} */ /** @defgroup BLE_GATTS_SYS_ATTR_FLAGS System Attribute Flags * @{ */ #define BLE_GATTS_SYS_ATTR_FLAG_SYS_SRVCS (1 << 0) /**< Restrict system attributes to system services only. */ #define BLE_GATTS_SYS_ATTR_FLAG_USR_SRVCS (1 << 1) /**< Restrict system attributes to user services only. */ /** @} */ /** @defgroup BLE_GATTS_SERVICE_CHANGED Service Changed Inclusion Values * @{ */ #define BLE_GATTS_SERVICE_CHANGED_DEFAULT (1) /**< Default is to include the Service Changed characteristic in the Attribute Table. */ /** @} */ /** @defgroup BLE_GATTS_ATTR_TAB_SIZE Attribute Table size * @{ */ #define BLE_GATTS_ATTR_TAB_SIZE_MIN (248) /**< Minimum Attribute Table size */ #define BLE_GATTS_ATTR_TAB_SIZE_DEFAULT (1408) /**< Default Attribute Table size. */ /** @} */ /** @defgroup BLE_GATTS_DEFAULTS GATT Server defaults * @{ */ #define BLE_GATTS_HVN_TX_QUEUE_SIZE_DEFAULT 1 /**< Default number of Handle Value Notifications that can be queued for transmission. */ /** @} */ /** @} */ /** @addtogroup BLE_GATTS_STRUCTURES Structures * @{ */ /** * @brief BLE GATTS connection configuration parameters, set with @ref sd_ble_cfg_set. */ typedef struct { uint8_t hvn_tx_queue_size; /**< Minimum guaranteed number of Handle Value Notifications that can be queued for transmission. The default value is @ref BLE_GATTS_HVN_TX_QUEUE_SIZE_DEFAULT */ } ble_gatts_conn_cfg_t; /**@brief Attribute metadata. */ typedef struct { ble_gap_conn_sec_mode_t read_perm; /**< Read permissions. */ ble_gap_conn_sec_mode_t write_perm; /**< Write permissions. */ uint8_t vlen :1; /**< Variable length attribute. */ uint8_t vloc :2; /**< Value location, see @ref BLE_GATTS_VLOCS.*/ uint8_t rd_auth :1; /**< Read authorization and value will be requested from the application on every read operation. */ uint8_t wr_auth :1; /**< Write authorization will be requested from the application on every Write Request operation (but not Write Command). */ } ble_gatts_attr_md_t; /**@brief GATT Attribute. */ typedef struct { ble_uuid_t const *p_uuid; /**< Pointer to the attribute UUID. */ ble_gatts_attr_md_t const *p_attr_md; /**< Pointer to the attribute metadata structure. */ uint16_t init_len; /**< Initial attribute value length in bytes. */ 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. */ uint16_t max_len; /**< Maximum attribute value length in bytes, see @ref BLE_GATTS_ATTR_LENS_MAX for maximum values. */ 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 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. 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.*/ } ble_gatts_attr_t; /**@brief GATT Attribute Value. */ typedef struct { uint16_t len; /**< Length in bytes to be written or read. Length in bytes written or read after successful return.*/ uint16_t offset; /**< Attribute value offset. */ uint8_t *p_value; /**< Pointer to where value is stored or will be stored. If value is stored in user memory, only the attribute length is updated when p_value == NULL. Set to NULL when reading to obtain the complete length of the attribute value */ } ble_gatts_value_t; /**@brief GATT Characteristic Presentation Format. */ typedef struct { uint8_t format; /**< Format of the value, see @ref BLE_GATT_CPF_FORMATS. */ int8_t exponent; /**< Exponent for integer data types. */ uint16_t unit; /**< Unit from Bluetooth Assigned Numbers. */ uint8_t name_space; /**< Namespace from Bluetooth Assigned Numbers, see @ref BLE_GATT_CPF_NAMESPACES. */ uint16_t desc; /**< Namespace description from Bluetooth Assigned Numbers, see @ref BLE_GATT_CPF_NAMESPACES. */ } ble_gatts_char_pf_t; /**@brief GATT Characteristic metadata. */ typedef struct { ble_gatt_char_props_t char_props; /**< Characteristic Properties. */ ble_gatt_char_ext_props_t char_ext_props; /**< Characteristic Extended Properties. */ uint8_t const *p_char_user_desc; /**< Pointer to a UTF-8 encoded string (non-NULL terminated), NULL if the descriptor is not required. */ uint16_t char_user_desc_max_size; /**< The maximum size in bytes of the user description descriptor. */ uint16_t char_user_desc_size; /**< The size of the user description, must be smaller or equal to char_user_desc_max_size. */ ble_gatts_char_pf_t const *p_char_pf; /**< Pointer to a presentation format structure or NULL if the CPF descriptor is not required. */ ble_gatts_attr_md_t const *p_user_desc_md; /**< Attribute metadata for the User Description descriptor, or NULL for default values. */ ble_gatts_attr_md_t const *p_cccd_md; /**< Attribute metadata for the Client Characteristic Configuration Descriptor, or NULL for default values. */ ble_gatts_attr_md_t const *p_sccd_md; /**< Attribute metadata for the Server Characteristic Configuration Descriptor, or NULL for default values. */ } ble_gatts_char_md_t; /**@brief GATT Characteristic Definition Handles. */ typedef struct { uint16_t value_handle; /**< Handle to the characteristic value. */ uint16_t user_desc_handle; /**< Handle to the User Description descriptor, or @ref BLE_GATT_HANDLE_INVALID if not present. */ uint16_t cccd_handle; /**< Handle to the Client Characteristic Configuration Descriptor, or @ref BLE_GATT_HANDLE_INVALID if not present. */ uint16_t sccd_handle; /**< Handle to the Server Characteristic Configuration Descriptor, or @ref BLE_GATT_HANDLE_INVALID if not present. */ } ble_gatts_char_handles_t; /**@brief GATT HVx parameters. */ typedef struct { uint16_t handle; /**< Characteristic Value Handle. */ uint8_t type; /**< Indication or Notification, see @ref BLE_GATT_HVX_TYPES. */ uint16_t offset; /**< Offset within the attribute value. */ uint16_t *p_len; /**< Length in bytes to be written, length in bytes written after successful return. */ uint8_t const *p_data; /**< Actual data content, use NULL to use the current attribute value. */ } ble_gatts_hvx_params_t; /**@brief GATT Authorization parameters. */ typedef struct { uint16_t gatt_status; /**< GATT status code for the operation, see @ref BLE_GATT_STATUS_CODES. */ uint8_t update : 1; /**< If set, data supplied in p_data will be used to update the attribute value. Please note that for @ref BLE_GATTS_AUTHORIZE_TYPE_WRITE operations this bit must always be set, as the data to be written needs to be stored and later provided by the application. */ uint16_t offset; /**< Offset of the attribute value being updated. */ uint16_t len; /**< Length in bytes of the value in p_data pointer, see @ref BLE_GATTS_ATTR_LENS_MAX. */ uint8_t const *p_data; /**< Pointer to new value used to update the attribute value. */ } ble_gatts_authorize_params_t; /**@brief GATT Read or Write Authorize Reply parameters. */ typedef struct { uint8_t type; /**< Type of authorize operation, see @ref BLE_GATTS_AUTHORIZE_TYPES. */ union { ble_gatts_authorize_params_t read; /**< Read authorization parameters. */ ble_gatts_authorize_params_t write; /**< Write authorization parameters. */ } params; /**< Reply Parameters. */ } ble_gatts_rw_authorize_reply_params_t; /**@brief Service Changed Inclusion configuration parameters, set with @ref sd_ble_cfg_set. */ typedef struct { uint8_t service_changed : 1; /**< If 1, include the Service Changed characteristic in the Attribute Table. Default is @ref BLE_GATTS_SERVICE_CHANGED_DEFAULT. */ } ble_gatts_cfg_service_changed_t; /**@brief Attribute table size configuration parameters, set with @ref sd_ble_cfg_set. * * @retval ::NRF_ERROR_INVALID_LENGTH One or more of the following is true: * - The specified Attribute Table size is too small. * The minimum acceptable size is defined by @ref BLE_GATTS_ATTR_TAB_SIZE_MIN. * - The specified Attribute Table size is not a multiple of 4. */ typedef struct { uint32_t attr_tab_size; /**< Attribute table size. Default is @ref BLE_GATTS_ATTR_TAB_SIZE_DEFAULT, minimum is @ref BLE_GATTS_ATTR_TAB_SIZE_MIN. */ } ble_gatts_cfg_attr_tab_size_t; /**@brief Config structure for GATTS configurations. */ typedef union { ble_gatts_cfg_service_changed_t service_changed; /**< Include service changed characteristic, cfg_id is @ref BLE_GATTS_CFG_SERVICE_CHANGED. */ ble_gatts_cfg_attr_tab_size_t attr_tab_size; /**< Attribute table size, cfg_id is @ref BLE_GATTS_CFG_ATTR_TAB_SIZE. */ } ble_gatts_cfg_t; /**@brief Event structure for @ref BLE_GATTS_EVT_WRITE. */ typedef struct { uint16_t handle; /**< Attribute Handle. */ ble_uuid_t uuid; /**< Attribute UUID. */ uint8_t op; /**< Type of write operation, see @ref BLE_GATTS_OPS. */ uint8_t auth_required; /**< Writing operation deferred due to authorization requirement. Application may use @ref sd_ble_gatts_value_set to finalize the writing operation. */ uint16_t offset; /**< Offset for the write operation. */ uint16_t len; /**< Length of the received data. */ uint8_t data[1]; /**< Received data. @note This is a variable length array. The size of 1 indicated is only a placeholder for compilation. See @ref sd_ble_evt_get for more information on how to use event structures with variable length array members. */ } ble_gatts_evt_write_t; /**@brief Event substructure for authorized read requests, see @ref ble_gatts_evt_rw_authorize_request_t. */ typedef struct { uint16_t handle; /**< Attribute Handle. */ ble_uuid_t uuid; /**< Attribute UUID. */ uint16_t offset; /**< Offset for the read operation. */ } ble_gatts_evt_read_t; /**@brief Event structure for @ref BLE_GATTS_EVT_RW_AUTHORIZE_REQUEST. */ typedef struct { uint8_t type; /**< Type of authorize operation, see @ref BLE_GATTS_AUTHORIZE_TYPES. */ union { ble_gatts_evt_read_t read; /**< Attribute Read Parameters. */ ble_gatts_evt_write_t write; /**< Attribute Write Parameters. */ } request; /**< Request Parameters. */ } ble_gatts_evt_rw_authorize_request_t; /**@brief Event structure for @ref BLE_GATTS_EVT_SYS_ATTR_MISSING. */ typedef struct { uint8_t hint; /**< Hint (currently unused). */ } ble_gatts_evt_sys_attr_missing_t; /**@brief Event structure for @ref BLE_GATTS_EVT_HVC. */ typedef struct { uint16_t handle; /**< Attribute Handle. */ } ble_gatts_evt_hvc_t; /**@brief Event structure for @ref BLE_GATTS_EVT_EXCHANGE_MTU_REQUEST. */ typedef struct { uint16_t client_rx_mtu; /**< Client RX MTU size. */ } ble_gatts_evt_exchange_mtu_request_t; /**@brief Event structure for @ref BLE_GATTS_EVT_TIMEOUT. */ typedef struct { uint8_t src; /**< Timeout source, see @ref BLE_GATT_TIMEOUT_SOURCES. */ } ble_gatts_evt_timeout_t; /**@brief Event structure for @ref BLE_GATTS_EVT_HVN_TX_COMPLETE. */ typedef struct { uint8_t count; /**< Number of notification transmissions completed. */ } ble_gatts_evt_hvn_tx_complete_t; /**@brief GATTS event structure. */ typedef struct { uint16_t conn_handle; /**< Connection Handle on which the event occurred. */ union { ble_gatts_evt_write_t write; /**< Write Event Parameters. */ ble_gatts_evt_rw_authorize_request_t authorize_request; /**< Read or Write Authorize Request Parameters. */ ble_gatts_evt_sys_attr_missing_t sys_attr_missing; /**< System attributes missing. */ ble_gatts_evt_hvc_t hvc; /**< Handle Value Confirmation Event Parameters. */ ble_gatts_evt_exchange_mtu_request_t exchange_mtu_request; /**< Exchange MTU Request Event Parameters. */ ble_gatts_evt_timeout_t timeout; /**< Timeout Event. */ ble_gatts_evt_hvn_tx_complete_t hvn_tx_complete; /**< Handle Value Notification transmission complete Event Parameters. */ } params; /**< Event Parameters. */ } ble_gatts_evt_t; /** @} */ /** @addtogroup BLE_GATTS_FUNCTIONS Functions * @{ */ /**@brief Add a service declaration to the Attribute Table. * * @note Secondary Services are only relevant in the context of the entity that references them, it is therefore forbidden to * add a secondary service declaration that is not referenced by another service later in the Attribute Table. * * @mscs * @mmsc{@ref BLE_GATTS_ATT_TABLE_POP_MSC} * @endmscs * * @param[in] type Toggles between primary and secondary services, see @ref BLE_GATTS_SRVC_TYPES. * @param[in] p_uuid Pointer to service UUID. * @param[out] p_handle Pointer to a 16-bit word where the assigned handle will be stored. * * @retval ::NRF_SUCCESS Successfully added a service declaration. * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied. * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied, Vendor Specific UUIDs need to be present in the table. * @retval ::NRF_ERROR_FORBIDDEN Forbidden value supplied, certain UUIDs are reserved for the stack. * @retval ::NRF_ERROR_NO_MEM Not enough memory to complete operation. */ 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)); /**@brief Add an include declaration to the Attribute Table. * * @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). * * @note The included service must already be present in the Attribute Table prior to this call. * * @mscs * @mmsc{@ref BLE_GATTS_ATT_TABLE_POP_MSC} * @endmscs * * @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. * @param[in] inc_srvc_handle Handle of the included service. * @param[out] p_include_handle Pointer to a 16-bit word where the assigned handle will be stored. * * @retval ::NRF_SUCCESS Successfully added an include declaration. * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied. * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied, handle values need to match previously added services. * @retval ::NRF_ERROR_INVALID_STATE Invalid state to perform operation. * @retval ::NRF_ERROR_NOT_SUPPORTED Feature is not supported, service_handle must be that of the last added service. * @retval ::NRF_ERROR_FORBIDDEN Forbidden value supplied, self inclusions are not allowed. * @retval ::NRF_ERROR_NO_MEM Not enough memory to complete operation. * @retval ::NRF_ERROR_NOT_FOUND Attribute not found. */ 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)); /**@brief Add a characteristic declaration, a characteristic value declaration and optional characteristic descriptor declarations to the Attribute Table. * * @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). * * @note Several restrictions apply to the parameters, such as matching permissions between the user description descriptor and the writable auxiliaries bits, * readable (no security) and writable (selectable) CCCDs and SCCDs and valid presentation format values. * * @note If no metadata is provided for the optional descriptors, their permissions will be derived from the characteristic permissions. * * @mscs * @mmsc{@ref BLE_GATTS_ATT_TABLE_POP_MSC} * @endmscs * * @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. * @param[in] p_char_md Characteristic metadata. * @param[in] p_attr_char_value Pointer to the attribute structure corresponding to the characteristic value. * @param[out] p_handles Pointer to the structure where the assigned handles will be stored. * * @retval ::NRF_SUCCESS Successfully added a characteristic. * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied. * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied, service handle, Vendor Specific UUIDs, lengths, and permissions need to adhere to the constraints. * @retval ::NRF_ERROR_INVALID_STATE Invalid state to perform operation, a service context is required. * @retval ::NRF_ERROR_FORBIDDEN Forbidden value supplied, certain UUIDs are reserved for the stack. * @retval ::NRF_ERROR_NO_MEM Not enough memory to complete operation. * @retval ::NRF_ERROR_DATA_SIZE Invalid data size(s) supplied, attribute lengths are restricted by @ref BLE_GATTS_ATTR_LENS_MAX. */ 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)); /**@brief Add a descriptor to the Attribute Table. * * @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). * * @mscs * @mmsc{@ref BLE_GATTS_ATT_TABLE_POP_MSC} * @endmscs * * @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. * @param[in] p_attr Pointer to the attribute structure. * @param[out] p_handle Pointer to a 16-bit word where the assigned handle will be stored. * * @retval ::NRF_SUCCESS Successfully added a descriptor. * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied. * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied, characteristic handle, Vendor Specific UUIDs, lengths, and permissions need to adhere to the constraints. * @retval ::NRF_ERROR_INVALID_STATE Invalid state to perform operation, a characteristic context is required. * @retval ::NRF_ERROR_FORBIDDEN Forbidden value supplied, certain UUIDs are reserved for the stack. * @retval ::NRF_ERROR_NO_MEM Not enough memory to complete operation. * @retval ::NRF_ERROR_DATA_SIZE Invalid data size(s) supplied, attribute lengths are restricted by @ref BLE_GATTS_ATTR_LENS_MAX. */ 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)); /**@brief Set the value of a given attribute. * * @note Values other than system attributes can be set at any time, regardless of whether any active connections exist. * * @mscs * @mmsc{@ref BLE_GATTS_QUEUED_WRITE_QUEUE_FULL_MSC} * @mmsc{@ref BLE_GATTS_QUEUED_WRITE_NOBUF_NOAUTH_MSC} * @endmscs * * @param[in] conn_handle Connection handle. Ignored if the value does not belong to a system attribute. * @param[in] handle Attribute handle. * @param[in,out] p_value Attribute value information. * * @retval ::NRF_SUCCESS Successfully set the value of the attribute. * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied. * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied. * @retval ::NRF_ERROR_NOT_FOUND Attribute not found. * @retval ::NRF_ERROR_FORBIDDEN Forbidden handle supplied, certain attributes are not modifiable by the application. * @retval ::NRF_ERROR_DATA_SIZE Invalid data size(s) supplied, attribute lengths are restricted by @ref BLE_GATTS_ATTR_LENS_MAX. * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid connection handle supplied on a system attribute. */ 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)); /**@brief Get the value of a given attribute. * * @note If the attribute value is longer than the size of the supplied buffer, * p_len will return the total attribute value length (excluding offset), * and not the number of bytes actually returned in p_data. * The application may use this information to allocate a suitable buffer size. * * @note When retrieving system attribute values with this function, the connection handle * may refer to an already disconnected connection. Refer to the documentation of * @ref sd_ble_gatts_sys_attr_get for further information. * * @param[in] conn_handle Connection handle. Ignored if the value does not belong to a system attribute. * @param[in] handle Attribute handle. * @param[in,out] p_value Attribute value information. * * @retval ::NRF_SUCCESS Successfully retrieved the value of the attribute. * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied. * @retval ::NRF_ERROR_NOT_FOUND Attribute not found. * @retval ::NRF_ERROR_INVALID_PARAM Invalid attribute offset supplied. * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid connection handle supplied on a system attribute. * @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. */ 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)); /**@brief Notify or Indicate an attribute value. * * @details This function checks for the relevant Client Characteristic Configuration descriptor value to verify that the relevant operation * (notification or indication) has been enabled by the client. It is also able to update the attribute value before issuing the PDU, so that * the application can atomically perform a value update and a server initiated transaction with a single API call. * * @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. * The Attribute Table has been updated if one of the following error codes is returned: @ref NRF_ERROR_INVALID_STATE, @ref NRF_ERROR_BUSY, * @ref NRF_ERROR_FORBIDDEN, @ref BLE_ERROR_GATTS_SYS_ATTR_MISSING and @ref NRF_ERROR_RESOURCES. * The caller can check whether the value has been updated by looking at the contents of *(p_hvx_params->p_len). * * @note Only one indication procedure can be ongoing per connection at a time. * If the application tries to indicate an attribute value while another indication procedure is ongoing, * the function call will return @ref NRF_ERROR_BUSY. * A @ref BLE_GATTS_EVT_HVC event will be issued as soon as the confirmation arrives from the peer. * * @note The number of Handle Value Notifications that can be queued is configured by @ref ble_gatts_conn_cfg_t::hvn_tx_queue_size * When the queue is full, the function call will return @ref NRF_ERROR_RESOURCES. * A @ref BLE_GATTS_EVT_HVN_TX_COMPLETE event will be issued as soon as the transmission of the notification is complete. * * @note The application can keep track of the available queue element count for notifications by following the procedure below: * - Store initial queue element count in a variable. * - Decrement the variable, which stores the currently available queue element count, by one when a call to this function returns @ref NRF_SUCCESS. * - Increment the variable, which stores the current available queue element count, by the count variable in @ref BLE_GATTS_EVT_HVN_TX_COMPLETE event. * * @events * @event{@ref BLE_GATTS_EVT_HVN_TX_COMPLETE, Notification transmission complete.} * @event{@ref BLE_GATTS_EVT_HVC, Confirmation received from the peer.} * @endevents * * @mscs * @mmsc{@ref BLE_GATTS_HVX_SYS_ATTRS_MISSING_MSC} * @mmsc{@ref BLE_GATTS_HVN_MSC} * @mmsc{@ref BLE_GATTS_HVI_MSC} * @mmsc{@ref BLE_GATTS_HVX_DISABLED_MSC} * @endmscs * * @param[in] conn_handle Connection handle. * @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 * the contents pointed by it before sending the notification or indication. * * @retval ::NRF_SUCCESS Successfully queued a notification or indication for transmission, and optionally updated the attribute value. * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid Connection Handle. * @retval ::NRF_ERROR_INVALID_STATE One or more of the following is true: * - Invalid Connection State * - Notifications and/or indications not enabled in the CCCD * - An ATT_MTU exchange is ongoing * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied. * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied. * @retval ::BLE_ERROR_INVALID_ATTR_HANDLE Invalid attribute handle(s) supplied. Only attributes added directly by the application are available to notify and indicate. * @retval ::BLE_ERROR_GATTS_INVALID_ATTR_TYPE Invalid attribute type(s) supplied, only characteristic values may be notified and indicated. * @retval ::NRF_ERROR_NOT_FOUND Attribute not found. * @retval ::NRF_ERROR_FORBIDDEN The connection's current security level is lower than the one required by the write permissions of the CCCD associated with this characteristic. * @retval ::NRF_ERROR_DATA_SIZE Invalid data size(s) supplied. * @retval ::NRF_ERROR_BUSY For @ref BLE_GATT_HVX_INDICATION Procedure already in progress. Wait for a @ref BLE_GATTS_EVT_HVC event and retry. * @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. * @retval ::NRF_ERROR_RESOURCES Too many notifications queued. * Wait for a @ref BLE_GATTS_EVT_HVN_TX_COMPLETE event and retry. */ SVCALL(SD_BLE_GATTS_HVX, uint32_t, sd_ble_gatts_hvx(uint16_t conn_handle, ble_gatts_hvx_params_t const *p_hvx_params)); /**@brief Indicate the Service Changed attribute value. * * @details This call will send a Handle Value Indication to one or more peers connected to inform them that the Attribute * Table layout has changed. As soon as the peer has confirmed the indication, a @ref BLE_GATTS_EVT_SC_CONFIRM event will * be issued. * * @note Some of the restrictions and limitations that apply to @ref sd_ble_gatts_hvx also apply here. * * @events * @event{@ref BLE_GATTS_EVT_SC_CONFIRM, Confirmation of attribute table change received from peer.} * @endevents * * @mscs * @mmsc{@ref BLE_GATTS_SC_MSC} * @endmscs * * @param[in] conn_handle Connection handle. * @param[in] start_handle Start of affected attribute handle range. * @param[in] end_handle End of affected attribute handle range. * * @retval ::NRF_SUCCESS Successfully queued the Service Changed indication for transmission. * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid Connection Handle. * @retval ::NRF_ERROR_NOT_SUPPORTED Service Changed not enabled at initialization. See @ref * sd_ble_cfg_set and @ref ble_gatts_cfg_service_changed_t. * @retval ::NRF_ERROR_INVALID_STATE One or more of the following is true: * - Invalid Connection State * - Notifications and/or indications not enabled in the CCCD * - An ATT_MTU exchange is ongoing * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied. * @retval ::BLE_ERROR_INVALID_ATTR_HANDLE Invalid attribute handle(s) supplied, handles must be in the range populated by the application. * @retval ::NRF_ERROR_BUSY Procedure already in progress. * @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. */ 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)); /**@brief Respond to a Read/Write authorization request. * * @note This call should only be used as a response to a @ref BLE_GATTS_EVT_RW_AUTHORIZE_REQUEST event issued to the application. * * @mscs * @mmsc{@ref BLE_GATTS_QUEUED_WRITE_NOBUF_AUTH_MSC} * @mmsc{@ref BLE_GATTS_QUEUED_WRITE_BUF_AUTH_MSC} * @mmsc{@ref BLE_GATTS_QUEUED_WRITE_NOBUF_NOAUTH_MSC} * @mmsc{@ref BLE_GATTS_READ_REQ_AUTH_MSC} * @mmsc{@ref BLE_GATTS_WRITE_REQ_AUTH_MSC} * @mmsc{@ref BLE_GATTS_QUEUED_WRITE_QUEUE_FULL_MSC} * @mmsc{@ref BLE_GATTS_QUEUED_WRITE_NOBUF_PEER_CANCEL_MSC} * @endmscs * * @param[in] conn_handle Connection handle. * @param[in] p_rw_authorize_reply_params Pointer to a structure with the attribute provided by the application. * * @note @ref ble_gatts_authorize_params_t::p_data is ignored when this function is used to respond * to a @ref BLE_GATTS_AUTHORIZE_TYPE_READ event if @ref ble_gatts_authorize_params_t::update * is set to 0. * * @retval ::NRF_SUCCESS Successfully queued a response to the peer, and in the case of a write operation, Attribute Table updated. * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid Connection Handle. * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied. * @retval ::NRF_ERROR_INVALID_STATE Invalid Connection State or no authorization request pending. * @retval ::NRF_ERROR_INVALID_PARAM Authorization op invalid, * handle supplied does not match requested handle, * or invalid data to be written provided by the application. */ 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)); /**@brief Update persistent system attribute information. * * @details Supply information about persistent system attributes to the stack, * previously obtained using @ref sd_ble_gatts_sys_attr_get. * This call is only allowed for active connections, and is usually * made immediately after a connection is established with an known bonded device, * often as a response to a @ref BLE_GATTS_EVT_SYS_ATTR_MISSING. * * p_sysattrs may point directly to the application's stored copy of the system attributes * obtained using @ref sd_ble_gatts_sys_attr_get. * If the pointer is NULL, the system attribute info is initialized, assuming that * the application does not have any previously saved system attribute data for this device. * * @note The state of persistent system attributes is reset upon connection establishment and then remembered for its duration. * * @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. * 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 * reset the SoftDevice to return to a known state. * * @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. * @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. * * @mscs * @mmsc{@ref BLE_GATTS_HVX_SYS_ATTRS_MISSING_MSC} * @mmsc{@ref BLE_GATTS_SYS_ATTRS_UNK_PEER_MSC} * @mmsc{@ref BLE_GATTS_SYS_ATTRS_BONDED_PEER_MSC} * @endmscs * * @param[in] conn_handle Connection handle. * @param[in] p_sys_attr_data Pointer to a saved copy of system attributes supplied to the stack, or NULL. * @param[in] len Size of data pointed by p_sys_attr_data, in octets. * @param[in] flags Optional additional flags, see @ref BLE_GATTS_SYS_ATTR_FLAGS * * @retval ::NRF_SUCCESS Successfully set the system attribute information. * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid Connection Handle. * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied. * @retval ::NRF_ERROR_INVALID_STATE Invalid Connection State. * @retval ::NRF_ERROR_INVALID_PARAM Invalid flags supplied. * @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. * @retval ::NRF_ERROR_NO_MEM Not enough memory to complete operation. */ 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)); /**@brief Retrieve persistent system attribute information from the stack. * * @details This call is used to retrieve information about values to be stored persistently by the application * during the lifetime of a connection or after it has been terminated. When a new connection is established with the same bonded device, * the system attribute information retrieved with this function should be restored using using @ref sd_ble_gatts_sys_attr_set. * If retrieved after disconnection, the data should be read before a new connection established. The connection handle for * the previous, now disconnected, connection will remain valid until a new one is created to allow this API call to refer to it. * Connection handles belonging to active connections can be used as well, but care should be taken since the system attributes * may be written to at any time by the peer during a connection's lifetime. * * @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. * @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. * * @mscs * @mmsc{@ref BLE_GATTS_SYS_ATTRS_BONDED_PEER_MSC} * @endmscs * * @param[in] conn_handle Connection handle of the recently terminated connection. * @param[out] p_sys_attr_data Pointer to a buffer where updated information about system attributes will be filled in. The format of the data is described * in @ref BLE_GATTS_SYS_ATTRS_FORMAT. NULL can be provided to obtain the length of the data. * @param[in,out] p_len Size of application buffer if p_sys_attr_data is not NULL. Unconditionally updated to actual length of system attribute data. * @param[in] flags Optional additional flags, see @ref BLE_GATTS_SYS_ATTR_FLAGS * * @retval ::NRF_SUCCESS Successfully retrieved the system attribute information. * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid Connection Handle. * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied. * @retval ::NRF_ERROR_INVALID_PARAM Invalid flags supplied. * @retval ::NRF_ERROR_DATA_SIZE The system attribute information did not fit into the provided buffer. * @retval ::NRF_ERROR_NOT_FOUND No system attributes found. */ 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)); /**@brief Retrieve the first valid user attribute handle. * * @param[out] p_handle Pointer to an integer where the handle will be stored. * * @retval ::NRF_SUCCESS Successfully retrieved the handle. * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied. */ SVCALL(SD_BLE_GATTS_INITIAL_USER_HANDLE_GET, uint32_t, sd_ble_gatts_initial_user_handle_get(uint16_t *p_handle)); /**@brief Retrieve the attribute UUID and/or metadata. * * @param[in] handle Attribute handle * @param[out] p_uuid UUID of the attribute. Use NULL to omit this field. * @param[out] p_md Metadata of the attribute. Use NULL to omit this field. * * @retval ::NRF_SUCCESS Successfully retrieved the attribute metadata, * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied. * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameters supplied. Returned when both @c p_uuid and @c p_md are NULL. * @retval ::NRF_ERROR_NOT_FOUND Attribute was not found. */ SVCALL(SD_BLE_GATTS_ATTR_GET, uint32_t, sd_ble_gatts_attr_get(uint16_t handle, ble_uuid_t * p_uuid, ble_gatts_attr_md_t * p_md)); /**@brief Reply to an ATT_MTU exchange request by sending an Exchange MTU Response to the client. * * @details This function is only used to reply to a @ref BLE_GATTS_EVT_EXCHANGE_MTU_REQUEST event. * * @details The SoftDevice sets ATT_MTU to the minimum of: * - The Client RX MTU value from @ref BLE_GATTS_EVT_EXCHANGE_MTU_REQUEST, and * - The Server RX MTU value. * * However, the SoftDevice never sets ATT_MTU lower than @ref BLE_GATT_ATT_MTU_DEFAULT. * * @mscs * @mmsc{@ref BLE_GATTS_MTU_EXCHANGE} * @endmscs * * @param[in] conn_handle The connection handle identifying the connection to perform this procedure on. * @param[in] server_rx_mtu Server RX MTU size. * - The minimum value is @ref BLE_GATT_ATT_MTU_DEFAULT. * - The maximum value is @ref ble_gatt_conn_cfg_t::att_mtu in the connection configuration used for this connection. * - The value must be equal to Client RX MTU size given in @ref sd_ble_gattc_exchange_mtu_request * if an ATT_MTU exchange has already been performed in the other direction. * * @retval ::NRF_SUCCESS Successfully sent response to the client. * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid Connection Handle. * @retval ::NRF_ERROR_INVALID_STATE Invalid Connection State or no ATT_MTU exchange request pending. * @retval ::NRF_ERROR_INVALID_PARAM Invalid Server RX MTU size supplied. */ SVCALL(SD_BLE_GATTS_EXCHANGE_MTU_REPLY, uint32_t, sd_ble_gatts_exchange_mtu_reply(uint16_t conn_handle, uint16_t server_rx_mtu)); /** @} */ #ifdef __cplusplus } #endif #endif // BLE_GATTS_H__ /** @} */