nrf_ble_qwr.h 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246
  1. /**
  2. * Copyright (c) 2016 - 2020, Nordic Semiconductor ASA
  3. *
  4. * All rights reserved.
  5. *
  6. * Redistribution and use in source and binary forms, with or without modification,
  7. * are permitted provided that the following conditions are met:
  8. *
  9. * 1. Redistributions of source code must retain the above copyright notice, this
  10. * list of conditions and the following disclaimer.
  11. *
  12. * 2. Redistributions in binary form, except as embedded into a Nordic
  13. * Semiconductor ASA integrated circuit in a product or a software update for
  14. * such product, must reproduce the above copyright notice, this list of
  15. * conditions and the following disclaimer in the documentation and/or other
  16. * materials provided with the distribution.
  17. *
  18. * 3. Neither the name of Nordic Semiconductor ASA nor the names of its
  19. * contributors may be used to endorse or promote products derived from this
  20. * software without specific prior written permission.
  21. *
  22. * 4. This software, with or without modification, must only be used with a
  23. * Nordic Semiconductor ASA integrated circuit.
  24. *
  25. * 5. Any software provided in binary form under this license must not be reverse
  26. * engineered, decompiled, modified and/or disassembled.
  27. *
  28. * THIS SOFTWARE IS PROVIDED BY NORDIC SEMICONDUCTOR ASA "AS IS" AND ANY EXPRESS
  29. * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  30. * OF MERCHANTABILITY, NONINFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE ARE
  31. * DISCLAIMED. IN NO EVENT SHALL NORDIC SEMICONDUCTOR ASA OR CONTRIBUTORS BE
  32. * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  33. * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
  34. * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  35. * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  36. * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  37. * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  38. *
  39. */
  40. /** @file
  41. *
  42. * @defgroup nrf_ble_qwr Queued Writes module
  43. * @{
  44. * @ingroup ble_sdk_lib
  45. * @brief Module for handling Queued Write operations.
  46. *
  47. * @details This module handles prepare write, execute write, and cancel write
  48. * commands. It also manages memory requests related to these operations.
  49. *
  50. * @note The application must propagate BLE stack events to this module by calling
  51. * @ref nrf_ble_qwr_on_ble_evt().
  52. */
  53. #ifndef NRF_BLE_QUEUED_WRITES_H__
  54. #define NRF_BLE_QUEUED_WRITES_H__
  55. #ifdef __cplusplus
  56. extern "C" {
  57. #endif
  58. #include <stdint.h>
  59. #include "nordic_common.h"
  60. #include "sdk_common.h"
  61. #include "ble.h"
  62. #include "ble_srv_common.h"
  63. /**@brief Macro for defining a nrf_ble_qwr instance.
  64. *
  65. * @param _name Name of the instance.
  66. * @hideinitializer
  67. */
  68. #define NRF_BLE_QWR_DEF(_name) \
  69. static nrf_ble_qwr_t _name; \
  70. NRF_SDH_BLE_OBSERVER(_name ## _obs, \
  71. NRF_BLE_QWR_BLE_OBSERVER_PRIO, \
  72. nrf_ble_qwr_on_ble_evt, \
  73. &_name)
  74. /**@brief Macro for defining an array of nrf_ble_qwr instance.
  75. *
  76. * @param _name Name of the array.
  77. * @param _cnt Size of the array.
  78. * @hideinitializer
  79. */
  80. #define NRF_BLE_QWRS_DEF(_name, _cnt) \
  81. static nrf_ble_qwr_t _name[_cnt]; \
  82. NRF_SDH_BLE_OBSERVERS(_name ## _obs, \
  83. NRF_BLE_QWR_BLE_OBSERVER_PRIO, \
  84. nrf_ble_qwr_on_ble_evt, \
  85. &_name, \
  86. _cnt)
  87. #define NRF_BLE_QWR_REJ_REQUEST_ERR_CODE BLE_GATT_STATUS_ATTERR_APP_BEGIN + 0 //!< Error code used by the module to reject prepare write requests on non-registered attributes.
  88. /**@brief Queued Writes module event types. */
  89. typedef enum
  90. {
  91. NRF_BLE_QWR_EVT_EXECUTE_WRITE, //!< Event that indicates that an execute write command was received for a registered handle and that the received data was actually written and is now ready.
  92. NRF_BLE_QWR_EVT_AUTH_REQUEST, //!< Event that indicates that an execute write command was received for a registered handle and that the write request must now be accepted or rejected.
  93. } nrf_ble_qwr_evt_type_t;
  94. /**@brief Queued Writes module events. */
  95. typedef struct
  96. {
  97. nrf_ble_qwr_evt_type_t evt_type; //!< Type of the event.
  98. uint16_t attr_handle; //!< Handle of the attribute to which the event relates.
  99. } nrf_ble_qwr_evt_t;
  100. // Forward declaration of the nrf_ble_qwr_t type.
  101. struct nrf_ble_qwr_t;
  102. /**@brief Queued Writes module event handler type.
  103. *
  104. * If the provided event is of type @ref NRF_BLE_QWR_EVT_AUTH_REQUEST,
  105. * this function must accept or reject the execute write request by returning
  106. * one of the @ref BLE_GATT_STATUS_CODES.*/
  107. typedef uint16_t (* nrf_ble_qwr_evt_handler_t) (struct nrf_ble_qwr_t * p_qwr,
  108. nrf_ble_qwr_evt_t * p_evt);
  109. /**@brief Queued Writes structure.
  110. * @details This structure contains status information for the Queued Writes module. */
  111. typedef struct nrf_ble_qwr_t
  112. {
  113. uint8_t initialized; //!< Flag that indicates whether the module has been initialized.
  114. uint16_t conn_handle; //!< Connection handle.
  115. ble_srv_error_handler_t error_handler; //!< Error handler.
  116. bool is_user_mem_reply_pending; //!< Flag that indicates whether a mem_reply is pending (because a previous attempt returned busy).
  117. #if (NRF_BLE_QWR_MAX_ATTR > 0)
  118. uint16_t attr_handles[NRF_BLE_QWR_MAX_ATTR]; //!< List of handles for registered attributes, for which the module accepts and handles prepare write operations.
  119. uint8_t nb_registered_attr; //!< Number of registered attributes.
  120. uint16_t written_attr_handles[NRF_BLE_QWR_MAX_ATTR]; //!< List of attribute handles that have been written to during the current prepare write or execute write operation.
  121. uint8_t nb_written_handles; //!< Number of attributes that have been written to during the current prepare write or execute write operation.
  122. ble_user_mem_block_t mem_buffer; //!< Memory buffer that is provided to the SoftDevice on an ON_USER_MEM_REQUEST event.
  123. nrf_ble_qwr_evt_handler_t callback; //!< Event handler function that is called for events concerning the handles of all registered attributes.
  124. #endif
  125. } nrf_ble_qwr_t;
  126. /**@brief Queued Writes init structure.
  127. * @details This structure contains all information
  128. * that is needed to initialize the Queued Writes module. */
  129. typedef struct
  130. {
  131. ble_srv_error_handler_t error_handler; //!< Error handler.
  132. #if (NRF_BLE_QWR_MAX_ATTR > 0)
  133. ble_user_mem_block_t mem_buffer; //!< Memory buffer that is provided to the SoftDevice on an ON_USER_MEM_REQUEST event.
  134. nrf_ble_qwr_evt_handler_t callback; //!< Event handler function that is called for events concerning the handles of all registered attributes.
  135. #endif
  136. } nrf_ble_qwr_init_t;
  137. /**@brief Function for initializing the Queued Writes module.
  138. *
  139. * @details Call this function in the main entry of your application to
  140. * initialize the Queued Writes module. It must be called only once with a
  141. * given Queued Writes structure.
  142. *
  143. * @param[out] p_qwr Queued Writes structure. This structure must be
  144. * supplied by the application. It is initialized by this function
  145. * and is later used to identify the particular Queued Writes instance.
  146. * @param[in] p_qwr_init Initialization structure.
  147. *
  148. * @retval NRF_SUCCESS If the Queued Writes module was initialized successfully.
  149. * @retval NRF_ERROR_NULL If any of the given pointers is NULL.
  150. * @retval NRF_ERROR_INVALID_STATE If the given context has already been initialized.
  151. */
  152. ret_code_t nrf_ble_qwr_init(nrf_ble_qwr_t * p_qwr,
  153. nrf_ble_qwr_init_t const * p_qwr_init);
  154. /**@brief Function for assigning a connection handle to a given instance of the Queued Writes module.
  155. *
  156. * @details Call this function when a link with a peer has been established to
  157. * associate this link to the instance of the module. This makes it
  158. * possible to handle several links and associate each link to a particular
  159. * instance of this module.
  160. *
  161. * @param[in] p_qwr Queued Writes structure.
  162. * @param[in] conn_handle Connection handle to be associated with the given Queued Writes instance.
  163. *
  164. * @retval NRF_SUCCESS If the assignment was successful.
  165. * @retval NRF_ERROR_NULL If any of the given pointers is NULL.
  166. * @retval NRF_ERROR_INVALID_STATE If the given context has not been initialized.
  167. */
  168. ret_code_t nrf_ble_qwr_conn_handle_assign(nrf_ble_qwr_t * p_qwr,
  169. uint16_t conn_handle);
  170. /**@brief Function for handling BLE stack events.
  171. *
  172. * @details Handles all events from the BLE stack that are of interest to the Queued Writes module.
  173. *
  174. * @param[in] p_ble_evt Event received from the BLE stack.
  175. * @param[in] p_context Queued Writes structure.
  176. */
  177. void nrf_ble_qwr_on_ble_evt(ble_evt_t const * p_ble_evt, void * p_context);
  178. #if (NRF_BLE_QWR_MAX_ATTR > 0)
  179. /**@brief Function for registering an attribute with the Queued Writes module.
  180. *
  181. * @details Call this function for each attribute that you want to enable for
  182. * Queued Writes (thus a series of prepare write and execute write operations).
  183. *
  184. * @param[in] p_qwr Queued Writes structure.
  185. * @param[in] attr_handle Handle of the attribute to register.
  186. *
  187. * @retval NRF_SUCCESS If the registration was successful.
  188. * @retval NRF_ERROR_NO_MEM If no more memory is available to add this registration.
  189. * @retval NRF_ERROR_NULL If any of the given pointers is NULL.
  190. * @retval NRF_ERROR_INVALID_STATE If the given context has not been initialized.
  191. */
  192. ret_code_t nrf_ble_qwr_attr_register(nrf_ble_qwr_t * p_qwr, uint16_t attr_handle);
  193. /**@brief Function for retrieving the received data for a given attribute.
  194. *
  195. * @details Call this function after receiving an @ref NRF_BLE_QWR_EVT_AUTH_REQUEST
  196. * event to retrieve a linear copy of the data that was received for the given attribute.
  197. *
  198. * @param[in] p_qwr Queued Writes structure.
  199. * @param[in] attr_handle Handle of the attribute.
  200. * @param[out] p_mem Pointer to the application buffer where the received data will be copied.
  201. * @param[in,out] p_len Input: length of the input buffer. Output: length of the received data.
  202. *
  203. *
  204. * @retval NRF_SUCCESS If the data was retrieved and stored successfully.
  205. * @retval NRF_ERROR_NO_MEM If the provided buffer was smaller than the received data.
  206. * @retval NRF_ERROR_NULL If any of the given pointers is NULL.
  207. * @retval NRF_ERROR_INVALID_STATE If the given context has not been initialized.
  208. */
  209. ret_code_t nrf_ble_qwr_value_get(nrf_ble_qwr_t * p_qwr,
  210. uint16_t attr_handle,
  211. uint8_t * p_mem,
  212. uint16_t * p_len);
  213. #endif // (NRF_BLE_QWR_MAX_ATTR > 0)
  214. #ifdef __cplusplus
  215. }
  216. #endif
  217. #endif // NRF_BLE_QUEUED_WRITES_H__
  218. /** @} */