Marcus Chang / nRF51822

Important changes to repositories hosted on mbed.com

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

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

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

Fork of nRF51822 by Nordic Semiconductor

nordic/nrf-sdk/ble/ble_db_discovery.h@65:98215c4f3a25, 2014-09-08 (annotated)

Committer:
Rohit Grover
Date:
Mon Sep 08 17:21:46 2014 +0100
Revision:
65:98215c4f3a25
Release 0.1.3



Update to v6.1.0 of Nordic's SDK.



Bugfixes

~~~~~~~~



- Handle all valid disconnection reasons.



Compatible with Release 0.1.1 of the BLE_API.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Rohit Grover 65:98215c4f3a25 1 /* Copyright (c) 2013 Nordic Semiconductor. All Rights Reserved.
Rohit Grover 65:98215c4f3a25 2 *
Rohit Grover 65:98215c4f3a25 3 * The information contained herein is property of Nordic Semiconductor ASA.
Rohit Grover 65:98215c4f3a25 4 * Terms and conditions of usage are described in detail in NORDIC
Rohit Grover 65:98215c4f3a25 5 * SEMICONDUCTOR STANDARD SOFTWARE LICENSE AGREEMENT.
Rohit Grover 65:98215c4f3a25 6 *
Rohit Grover 65:98215c4f3a25 7 * Licensees are granted free, non-transferable use of the information. NO
Rohit Grover 65:98215c4f3a25 8 * WARRANTY of ANY KIND is provided. This heading must NOT be removed from
Rohit Grover 65:98215c4f3a25 9 * the file.
Rohit Grover 65:98215c4f3a25 10 */
Rohit Grover 65:98215c4f3a25 11
Rohit Grover 65:98215c4f3a25 12
Rohit Grover 65:98215c4f3a25 13 /**@file
Rohit Grover 65:98215c4f3a25 14 *
Rohit Grover 65:98215c4f3a25 15 * @defgroup ble_sdk_lib_db_discovery Database Discovery
Rohit Grover 65:98215c4f3a25 16 * @{
Rohit Grover 65:98215c4f3a25 17 * @ingroup nrf51_sdk_api
Rohit Grover 65:98215c4f3a25 18 * @brief Database discovery module.
Rohit Grover 65:98215c4f3a25 19 *
Rohit Grover 65:98215c4f3a25 20 * @details This module contains the APIs and types exposed by the DB Discovery module. These APIs
Rohit Grover 65:98215c4f3a25 21 * and types can be used by the application to perform discovery of a service and its
Rohit Grover 65:98215c4f3a25 22 * characteristics at the peer server. This module can also be used to discover the
Rohit Grover 65:98215c4f3a25 23 * desired services in multiple remote devices.
Rohit Grover 65:98215c4f3a25 24 * A typical use of this library is described in the figure below.
Rohit Grover 65:98215c4f3a25 25 * @image html db_discovery.jpg
Rohit Grover 65:98215c4f3a25 26 *
Rohit Grover 65:98215c4f3a25 27 * @warning The maximum number of characteristics per service that can be discovered by this module
Rohit Grover 65:98215c4f3a25 28 * is indicated by the value of @ref BLE_DB_DISCOVERY_MAX_CHAR_PER_SRV. If the peer
Rohit Grover 65:98215c4f3a25 29 * has more than the supported number of characteristics, then the first found will be
Rohit Grover 65:98215c4f3a25 30 * discovered and any further characteristics will be ignored. No descriptors other
Rohit Grover 65:98215c4f3a25 31 * than Client Characteristic Configuration Descriptors will be searched for at the peer.
Rohit Grover 65:98215c4f3a25 32 *
Rohit Grover 65:98215c4f3a25 33 * @note Presently only one instance of a Primary Service can be discovered by this module. If
Rohit Grover 65:98215c4f3a25 34 * there are multiple instances of the service at the peer, only the first instance
Rohit Grover 65:98215c4f3a25 35 * of it at the peer is fetched and returned to the application.
Rohit Grover 65:98215c4f3a25 36 *
Rohit Grover 65:98215c4f3a25 37 * @note The application must propagate BLE stack events to this module by calling
Rohit Grover 65:98215c4f3a25 38 * ble_db_discovery_on_ble_evt().
Rohit Grover 65:98215c4f3a25 39 *
Rohit Grover 65:98215c4f3a25 40 */
Rohit Grover 65:98215c4f3a25 41
Rohit Grover 65:98215c4f3a25 42 #ifndef BLE_DB_DISCOVERY_H__
Rohit Grover 65:98215c4f3a25 43 #define BLE_DB_DISCOVERY_H__
Rohit Grover 65:98215c4f3a25 44
Rohit Grover 65:98215c4f3a25 45 #include <stdint.h>
Rohit Grover 65:98215c4f3a25 46 #include "ble_gattc.h"
Rohit Grover 65:98215c4f3a25 47 #include "ble.h"
Rohit Grover 65:98215c4f3a25 48 #include "nrf_error.h"
Rohit Grover 65:98215c4f3a25 49 #include "ble_srv_common.h"
Rohit Grover 65:98215c4f3a25 50
Rohit Grover 65:98215c4f3a25 51 /**
Rohit Grover 65:98215c4f3a25 52 * @defgroup db_disc_defines Defines
Rohit Grover 65:98215c4f3a25 53 * @{
Rohit Grover 65:98215c4f3a25 54 */
Rohit Grover 65:98215c4f3a25 55
Rohit Grover 65:98215c4f3a25 56 #define BLE_DB_DISCOVERY_MAX_SRV 2 /**< Maximum number of services supported by this module. This also indicates the maximum number of users allowed to be registered to this module. (one user per service). */
Rohit Grover 65:98215c4f3a25 57 #define BLE_DB_DISCOVERY_MAX_CHAR_PER_SRV 3 /**< Maximum number of characteristics per service supported by this module. */
Rohit Grover 65:98215c4f3a25 58
Rohit Grover 65:98215c4f3a25 59 /** @} */
Rohit Grover 65:98215c4f3a25 60
Rohit Grover 65:98215c4f3a25 61 /**
Rohit Grover 65:98215c4f3a25 62 * @defgroup db_disc_enums Enumerations
Rohit Grover 65:98215c4f3a25 63 * @{
Rohit Grover 65:98215c4f3a25 64 */
Rohit Grover 65:98215c4f3a25 65
Rohit Grover 65:98215c4f3a25 66 /**@brief Type of the DB Discovery event.
Rohit Grover 65:98215c4f3a25 67 */
Rohit Grover 65:98215c4f3a25 68 typedef enum
Rohit Grover 65:98215c4f3a25 69 {
Rohit Grover 65:98215c4f3a25 70 BLE_DB_DISCOVERY_COMPLETE, /**< Event indicating that the GATT Database discovery is complete. */
Rohit Grover 65:98215c4f3a25 71 BLE_DB_DISCOVERY_ERROR, /**< Event indicating that an internal error has occurred in the DB Discovery module. This could typically be because of the SoftDevice API returning an error code during the DB discover.*/
Rohit Grover 65:98215c4f3a25 72 BLE_DB_DISCOVERY_SRV_NOT_FOUND /**< Event indicating that the service was not found at the peer.*/
Rohit Grover 65:98215c4f3a25 73 } ble_db_discovery_evt_type_t;
Rohit Grover 65:98215c4f3a25 74
Rohit Grover 65:98215c4f3a25 75 /** @} */
Rohit Grover 65:98215c4f3a25 76
Rohit Grover 65:98215c4f3a25 77 /**
Rohit Grover 65:98215c4f3a25 78 * @defgroup db_disc_structs Structures
Rohit Grover 65:98215c4f3a25 79 * @{
Rohit Grover 65:98215c4f3a25 80 */
Rohit Grover 65:98215c4f3a25 81
Rohit Grover 65:98215c4f3a25 82 /**@brief Structure for holding the characteristic and the handle of its CCCD found during the
Rohit Grover 65:98215c4f3a25 83 * discovery process.
Rohit Grover 65:98215c4f3a25 84 */
Rohit Grover 65:98215c4f3a25 85 typedef struct
Rohit Grover 65:98215c4f3a25 86 {
Rohit Grover 65:98215c4f3a25 87 ble_gattc_char_t characteristic; /**< Structure containing information about the characteristic. */
Rohit Grover 65:98215c4f3a25 88 uint16_t cccd_handle; /**< CCCD Handle value for this characteristic. This will be set to BLE_GATT_HANDLE_INVALID if a CCCD is not present at the server. */
Rohit Grover 65:98215c4f3a25 89 } ble_db_discovery_char_t;
Rohit Grover 65:98215c4f3a25 90
Rohit Grover 65:98215c4f3a25 91 /**@brief Structure for holding information about the service and the characteristics found during
Rohit Grover 65:98215c4f3a25 92 * the discovery process.
Rohit Grover 65:98215c4f3a25 93 */
Rohit Grover 65:98215c4f3a25 94 typedef struct
Rohit Grover 65:98215c4f3a25 95 {
Rohit Grover 65:98215c4f3a25 96 ble_uuid_t srv_uuid; /**< UUID of the service. */
Rohit Grover 65:98215c4f3a25 97 uint8_t char_count; /**< Number of characteristics present in the service. */
Rohit Grover 65:98215c4f3a25 98 ble_db_discovery_char_t charateristics[BLE_DB_DISCOVERY_MAX_CHAR_PER_SRV]; /**< Array of information related to the characteristics present in the service. */
Rohit Grover 65:98215c4f3a25 99 ble_gattc_handle_range_t handle_range; /**< Service Handle Range. */
Rohit Grover 65:98215c4f3a25 100 } ble_db_discovery_srv_t;
Rohit Grover 65:98215c4f3a25 101
Rohit Grover 65:98215c4f3a25 102 /**@brief Structure for holding the information related to the GATT database at the server.
Rohit Grover 65:98215c4f3a25 103 *
Rohit Grover 65:98215c4f3a25 104 * @details This module identifies a remote database. Use one instance of this structure per
Rohit Grover 65:98215c4f3a25 105 * connection.
Rohit Grover 65:98215c4f3a25 106 *
Rohit Grover 65:98215c4f3a25 107 * @warning This structure must be zero-initialized.
Rohit Grover 65:98215c4f3a25 108 */
Rohit Grover 65:98215c4f3a25 109 typedef struct
Rohit Grover 65:98215c4f3a25 110 {
Rohit Grover 65:98215c4f3a25 111 ble_db_discovery_srv_t services[BLE_DB_DISCOVERY_MAX_SRV]; /**< Information related to the current service being discovered. This is intended for internal use during service discovery.*/
Rohit Grover 65:98215c4f3a25 112 uint16_t conn_handle; /**< Connection handle as provided by the SoftDevice. */
Rohit Grover 65:98215c4f3a25 113 uint8_t srv_count; /**< Number of services at the peers GATT database.*/
Rohit Grover 65:98215c4f3a25 114 uint8_t curr_char_ind; /**< Index of the current characteristic being discovered. This is intended for internal use during service discovery.*/
Rohit Grover 65:98215c4f3a25 115 uint8_t curr_srv_ind; /**< Index of the current service being discovered. This is intended for internal use during service discovery.*/
Rohit Grover 65:98215c4f3a25 116 bool discovery_in_progress; /**< Variable to indicate if there is a service discovery in progress. */
Rohit Grover 65:98215c4f3a25 117 } ble_db_discovery_t;
Rohit Grover 65:98215c4f3a25 118
Rohit Grover 65:98215c4f3a25 119
Rohit Grover 65:98215c4f3a25 120 /**@brief Structure containing the event from the DB discovery module to the application.
Rohit Grover 65:98215c4f3a25 121 */
Rohit Grover 65:98215c4f3a25 122 typedef struct
Rohit Grover 65:98215c4f3a25 123 {
Rohit Grover 65:98215c4f3a25 124 ble_db_discovery_evt_type_t evt_type; /**< Type of event. */
Rohit Grover 65:98215c4f3a25 125 uint16_t conn_handle; /**< Handle of the connection for which this event has occurred. */
Rohit Grover 65:98215c4f3a25 126 union
Rohit Grover 65:98215c4f3a25 127 {
Rohit Grover 65:98215c4f3a25 128 ble_db_discovery_srv_t discovered_db; /**< Structure containing the information about the GATT Database at the server. This will be filled when the event type is @ref BLE_DB_DISCOVERY_COMPLETE.*/
Rohit Grover 65:98215c4f3a25 129 uint32_t err_code; /**< nRF Error code indicating the type of error which occurred in the DB Discovery module. This will be filled when the event type is @ref BLE_DB_DISCOVERY_ERROR. */
Rohit Grover 65:98215c4f3a25 130 } params;
Rohit Grover 65:98215c4f3a25 131 } ble_db_discovery_evt_t;
Rohit Grover 65:98215c4f3a25 132
Rohit Grover 65:98215c4f3a25 133 /** @} */
Rohit Grover 65:98215c4f3a25 134
Rohit Grover 65:98215c4f3a25 135 /**
Rohit Grover 65:98215c4f3a25 136 * @defgroup db_disc_types Types
Rohit Grover 65:98215c4f3a25 137 * @{
Rohit Grover 65:98215c4f3a25 138 */
Rohit Grover 65:98215c4f3a25 139
Rohit Grover 65:98215c4f3a25 140 /**@brief DB Discovery event handler type. */
Rohit Grover 65:98215c4f3a25 141 typedef void (* ble_db_discovery_evt_handler_t)(ble_db_discovery_evt_t * p_evt);
Rohit Grover 65:98215c4f3a25 142
Rohit Grover 65:98215c4f3a25 143 /** @} */
Rohit Grover 65:98215c4f3a25 144
Rohit Grover 65:98215c4f3a25 145 /**
Rohit Grover 65:98215c4f3a25 146 * @addtogroup db_disc_structs
Rohit Grover 65:98215c4f3a25 147 * @{
Rohit Grover 65:98215c4f3a25 148 */
Rohit Grover 65:98215c4f3a25 149
Rohit Grover 65:98215c4f3a25 150 /** @} */
Rohit Grover 65:98215c4f3a25 151
Rohit Grover 65:98215c4f3a25 152 /**
Rohit Grover 65:98215c4f3a25 153 * @defgroup db_disc_functions Functions
Rohit Grover 65:98215c4f3a25 154 * @{
Rohit Grover 65:98215c4f3a25 155 */
Rohit Grover 65:98215c4f3a25 156
Rohit Grover 65:98215c4f3a25 157 /**@brief Function for initializing the DB Discovery module.
Rohit Grover 65:98215c4f3a25 158 *
Rohit Grover 65:98215c4f3a25 159 * @retval NRF_SUCCESS on successful initialization.
Rohit Grover 65:98215c4f3a25 160 */
Rohit Grover 65:98215c4f3a25 161 uint32_t ble_db_discovery_init(void);
Rohit Grover 65:98215c4f3a25 162
Rohit Grover 65:98215c4f3a25 163
Rohit Grover 65:98215c4f3a25 164 /**@brief Function for closing the DB Discovery module.
Rohit Grover 65:98215c4f3a25 165 *
Rohit Grover 65:98215c4f3a25 166 * @details This function will clear up any internal variables and states maintained by the
Rohit Grover 65:98215c4f3a25 167 * module. To re-use the module after calling this function, the function @ref
Rohit Grover 65:98215c4f3a25 168 * ble_db_discovery_init must be called again.
Rohit Grover 65:98215c4f3a25 169 *
Rohit Grover 65:98215c4f3a25 170 * @retval NRF_SUCCESS Operation success.
Rohit Grover 65:98215c4f3a25 171 */
Rohit Grover 65:98215c4f3a25 172 uint32_t ble_db_discovery_close(void);
Rohit Grover 65:98215c4f3a25 173
Rohit Grover 65:98215c4f3a25 174
Rohit Grover 65:98215c4f3a25 175 /**@brief Function for registering with the DB Discovery module.
Rohit Grover 65:98215c4f3a25 176 *
Rohit Grover 65:98215c4f3a25 177 * @details The application can use this function to inform which service it is interested in
Rohit Grover 65:98215c4f3a25 178 * discovering at the server.
Rohit Grover 65:98215c4f3a25 179 *
Rohit Grover 65:98215c4f3a25 180 * @param[in] p_uuid Pointer to the UUID of the service to be discovered at the server.
Rohit Grover 65:98215c4f3a25 181 * @param[in] evt_handler Event handler to be called by the DB discovery module when any event
Rohit Grover 65:98215c4f3a25 182 * related to discovery of the registered service occurs.
Rohit Grover 65:98215c4f3a25 183 *
Rohit Grover 65:98215c4f3a25 184 * @note The total number of services that can be discovered by this module is @ref
Rohit Grover 65:98215c4f3a25 185 * BLE_DB_DISCOVERY_MAX_SRV. This effectively means that the maximum number of
Rohit Grover 65:98215c4f3a25 186 * registrations possible is equal to the @ref BLE_DB_DISCOVERY_MAX_SRV.
Rohit Grover 65:98215c4f3a25 187 *
Rohit Grover 65:98215c4f3a25 188 * @retval NRF_SUCCESS Operation success.
Rohit Grover 65:98215c4f3a25 189 * @retval NRF_ERROR_NULL When a NULL pointer is passed as input.
Rohit Grover 65:98215c4f3a25 190 * @retval NRF_ERROR_INVALID_STATE If this function is called without calling the
Rohit Grover 65:98215c4f3a25 191 * @ref ble_db_discovery_init.
Rohit Grover 65:98215c4f3a25 192 * @retval NRF_ERROR_NOT_SUPPORTED The maximum number of registrations allowed by this module
Rohit Grover 65:98215c4f3a25 193 * has been reached.
Rohit Grover 65:98215c4f3a25 194 */
Rohit Grover 65:98215c4f3a25 195 uint32_t ble_db_discovery_evt_register(const ble_uuid_t * const p_uuid,
Rohit Grover 65:98215c4f3a25 196 const ble_db_discovery_evt_handler_t evt_handler);
Rohit Grover 65:98215c4f3a25 197
Rohit Grover 65:98215c4f3a25 198
Rohit Grover 65:98215c4f3a25 199 /**@brief Function for starting the discovery of the GATT database at the server.
Rohit Grover 65:98215c4f3a25 200 *
Rohit Grover 65:98215c4f3a25 201 * @warning p_db_discovery structure must be zero-initialized.
Rohit Grover 65:98215c4f3a25 202 *
Rohit Grover 65:98215c4f3a25 203 * @param[out] p_db_discovery Pointer to the DB Discovery structure.
Rohit Grover 65:98215c4f3a25 204 * @param[in] conn_handle The handle of the connection for which the discovery should be
Rohit Grover 65:98215c4f3a25 205 * started.
Rohit Grover 65:98215c4f3a25 206 *
Rohit Grover 65:98215c4f3a25 207 * @retval NRF_SUCCESS Operation success.
Rohit Grover 65:98215c4f3a25 208 * @retval NRF_ERROR_NULL When a NULL pointer is passed as input.
Rohit Grover 65:98215c4f3a25 209 * @retval NRF_ERROR_INVALID_STATE If this function is called without calling the
Rohit Grover 65:98215c4f3a25 210 * @ref ble_db_discovery_init, or without calling
Rohit Grover 65:98215c4f3a25 211 * @ref ble_db_discovery_evt_register.
Rohit Grover 65:98215c4f3a25 212 * @retval NRF_ERROR_BUSY If a discovery is already in progress for the current
Rohit Grover 65:98215c4f3a25 213 * connection.
Rohit Grover 65:98215c4f3a25 214 *
Rohit Grover 65:98215c4f3a25 215 * @return This API propagates the error code returned by the
Rohit Grover 65:98215c4f3a25 216 * SoftDevice API @ref sd_ble_gattc_primary_services_discover.
Rohit Grover 65:98215c4f3a25 217 */
Rohit Grover 65:98215c4f3a25 218 uint32_t ble_db_discovery_start(ble_db_discovery_t * const p_db_discovery,
Rohit Grover 65:98215c4f3a25 219 uint16_t conn_handle);
Rohit Grover 65:98215c4f3a25 220
Rohit Grover 65:98215c4f3a25 221
Rohit Grover 65:98215c4f3a25 222 /**@brief Function for handling the Application's BLE Stack events.
Rohit Grover 65:98215c4f3a25 223 *
Rohit Grover 65:98215c4f3a25 224 * @param[in,out] p_db_discovery Pointer to the DB Discovery structure.
Rohit Grover 65:98215c4f3a25 225 * @param[in] p_ble_evt Pointer to the BLE event received.
Rohit Grover 65:98215c4f3a25 226 */
Rohit Grover 65:98215c4f3a25 227 void ble_db_discovery_on_ble_evt(ble_db_discovery_t * const p_db_discovery,
Rohit Grover 65:98215c4f3a25 228 const ble_evt_t * const p_ble_evt);
Rohit Grover 65:98215c4f3a25 229
Rohit Grover 65:98215c4f3a25 230 /** @} */
Rohit Grover 65:98215c4f3a25 231
Rohit Grover 65:98215c4f3a25 232 #endif // BLE_DB_DISCOVERY_H__
Rohit Grover 65:98215c4f3a25 233
Rohit Grover 65:98215c4f3a25 234 /** @} */