Nordic stack and drivers for the mbed BLE API
Fork of nRF51822 by
nordic/nrf-sdk/ble/device_manager/device_manager.h@61:214f61f4d5f8, 2014-09-05 (annotated)
- Committer:
- todotani
- Date:
- Fri Sep 05 14:20:55 2014 +0000
- Revision:
- 61:214f61f4d5f8
- Parent:
- 37:c29c330d942c
BLE_Health_Thermometer for mbed HRM1017 with BLE library 0.1.0
Who changed what in which revision?
User | Revision | Line number | New contents of line |
---|---|---|---|
Rohit Grover |
37:c29c330d942c | 1 | /* Copyright (C) 2013 Nordic Semiconductor. All Rights Reserved. |
Rohit Grover |
37:c29c330d942c | 2 | * |
Rohit Grover |
37:c29c330d942c | 3 | * The information contained herein is property of Nordic Semiconductor ASA. |
Rohit Grover |
37:c29c330d942c | 4 | * SEMICONDUCTOR STANDARD SOFTWARE LICENSE AGREEMENT. |
Rohit Grover |
37:c29c330d942c | 5 | * |
Rohit Grover |
37:c29c330d942c | 6 | * Licensees are granted free, non-transferable use of the information. NO |
Rohit Grover |
37:c29c330d942c | 7 | * WARRANTY of ANY KIND is provided. This heading must NOT be removed from |
Rohit Grover |
37:c29c330d942c | 8 | * the file. |
Rohit Grover |
37:c29c330d942c | 9 | * |
Rohit Grover |
37:c29c330d942c | 10 | */ |
Rohit Grover |
37:c29c330d942c | 11 | |
Rohit Grover |
37:c29c330d942c | 12 | /** |
Rohit Grover |
37:c29c330d942c | 13 | * @file device_manager.h |
Rohit Grover |
37:c29c330d942c | 14 | * |
Rohit Grover |
37:c29c330d942c | 15 | * @defgroup device_manager Device Manager |
Rohit Grover |
37:c29c330d942c | 16 | * @ingroup ble_sdk_lib |
Rohit Grover |
37:c29c330d942c | 17 | * @{ |
Rohit Grover |
37:c29c330d942c | 18 | * @brief Device Manager Application Interface Abstraction. |
Rohit Grover |
37:c29c330d942c | 19 | * |
Rohit Grover |
37:c29c330d942c | 20 | * @details The Device Manager module manages Active and Bonded Peers. Management of peer includes |
Rohit Grover |
37:c29c330d942c | 21 | * book keeping of contextual information like the Security Keys, GATT |
Rohit Grover |
37:c29c330d942c | 22 | * configuration and any application specific information. |
Rohit Grover |
37:c29c330d942c | 23 | * |
Rohit Grover |
37:c29c330d942c | 24 | * Active Peers are devices which are connected, and may or may not be bonded. |
Rohit Grover |
37:c29c330d942c | 25 | * Bonded Peers are devices which are bonded, and may or may not be Active (Connected). |
Rohit Grover |
37:c29c330d942c | 26 | * Active Bonded Peer refers to a device which is connected and bonded. |
Rohit Grover |
37:c29c330d942c | 27 | * |
Rohit Grover |
37:c29c330d942c | 28 | * Paired Devices refers to peer devices that are connected and have necessary context |
Rohit Grover |
37:c29c330d942c | 29 | * establishment/exchange for the current connection session. On disconnect, |
Rohit Grover |
37:c29c330d942c | 30 | * all contextual information is flushed. For example, SMP Information Exchanged during |
Rohit Grover |
37:c29c330d942c | 31 | * pairing and GATT Configuration is not retained on disconnection. |
Rohit Grover |
37:c29c330d942c | 32 | * |
Rohit Grover |
37:c29c330d942c | 33 | * Note that this module allows management of contextual information but |
Rohit Grover |
37:c29c330d942c | 34 | * does not provide an interface for connection management. Therefore, entering connectible |
Rohit Grover |
37:c29c330d942c | 35 | * mode, connection establishment, or disconnection of a link with peer is not in scope |
Rohit Grover |
37:c29c330d942c | 36 | * of this module. |
Rohit Grover |
37:c29c330d942c | 37 | * |
Rohit Grover |
37:c29c330d942c | 38 | * For bonded peers, the contextual information is required to be retained on disconnection |
Rohit Grover |
37:c29c330d942c | 39 | * and power cycling. Persistent storage of contextual information is handled by the |
Rohit Grover |
37:c29c330d942c | 40 | * module. This module categorizes the contextual information into 3 categories: |
Rohit Grover |
37:c29c330d942c | 41 | * - <b>Bonding Information</b> |
Rohit Grover |
37:c29c330d942c | 42 | * Bond information is the information exchanged between local and peer device to |
Rohit Grover |
37:c29c330d942c | 43 | * establish a bond. It also includes peer identification information, |
Rohit Grover |
37:c29c330d942c | 44 | * like the peer address or the IRK or both. From here on this category of information |
Rohit Grover |
37:c29c330d942c | 45 | * is referred to as Device Context. |
Rohit Grover |
37:c29c330d942c | 46 | * - <b>Service/Protocol Information</b> |
Rohit Grover |
37:c29c330d942c | 47 | * Service/Protocol information is the information retained for the peer to save on one-time |
Rohit Grover |
37:c29c330d942c | 48 | * procedures like the GATT Service Discovery procedures and Service Configurations. |
Rohit Grover |
37:c29c330d942c | 49 | * It allows devices to resume data exchange on subsequent reconnection without having |
Rohit Grover |
37:c29c330d942c | 50 | * to perform initial set-up procedures each time. From here on this category is |
Rohit Grover |
37:c29c330d942c | 51 | * referred to as Service Context. |
Rohit Grover |
37:c29c330d942c | 52 | * - <b>Application Information</b> |
Rohit Grover |
37:c29c330d942c | 53 | * Application information is the context that the application would like to associate with |
Rohit Grover |
37:c29c330d942c | 54 | * each of the bonded device. For example, if the application chooses to rank its peers |
Rohit Grover |
37:c29c330d942c | 55 | * in order to manage them better, the rank information could be treated as |
Rohit Grover |
37:c29c330d942c | 56 | * Application Information. This storage space is provided to save the application from |
Rohit Grover |
37:c29c330d942c | 57 | * maintaining a mapping table with each Device Instance and Application Information. |
Rohit Grover |
37:c29c330d942c | 58 | * However, if the application have no use for this, it is possible to not |
Rohit Grover |
37:c29c330d942c | 59 | * use or employ this at compile time. From here on this category of information is |
Rohit Grover |
37:c29c330d942c | 60 | * referred to as Application Context. |
Rohit Grover |
37:c29c330d942c | 61 | */ |
Rohit Grover |
37:c29c330d942c | 62 | |
Rohit Grover |
37:c29c330d942c | 63 | |
Rohit Grover |
37:c29c330d942c | 64 | #ifndef DEVICE_MANAGER_H__ |
Rohit Grover |
37:c29c330d942c | 65 | #define DEVICE_MANAGER_H__ |
Rohit Grover |
37:c29c330d942c | 66 | |
Rohit Grover |
37:c29c330d942c | 67 | #include <stdint.h> |
Rohit Grover |
37:c29c330d942c | 68 | #include <stdbool.h> |
Rohit Grover |
37:c29c330d942c | 69 | #include "sdk_common.h" |
Rohit Grover |
37:c29c330d942c | 70 | #include "ble.h" |
Rohit Grover |
37:c29c330d942c | 71 | #include "ble_gap.h" |
Rohit Grover |
37:c29c330d942c | 72 | #include "device_manager_cnfg.h" |
Rohit Grover |
37:c29c330d942c | 73 | |
Rohit Grover |
37:c29c330d942c | 74 | /** |
Rohit Grover |
37:c29c330d942c | 75 | * @defgroup dm_service_cntext_types Service/Protocol Types |
Rohit Grover |
37:c29c330d942c | 76 | * |
Rohit Grover |
37:c29c330d942c | 77 | * @brief Describes the possible types of Service/Protocol Contexts for a bonded/peer device. |
Rohit Grover |
37:c29c330d942c | 78 | * |
Rohit Grover |
37:c29c330d942c | 79 | * @details Possible Service/Protocol context per peer device. The Device Manager provides the |
Rohit Grover |
37:c29c330d942c | 80 | * functionality of persistently storing the Service/Protocol context and can automatically |
Rohit Grover |
37:c29c330d942c | 81 | * load them when needed. |
Rohit Grover |
37:c29c330d942c | 82 | * For example system attributes for a GATT Server. Based on the nature of the application, |
Rohit Grover |
37:c29c330d942c | 83 | * not all service types may be needed. The application can specify |
Rohit Grover |
37:c29c330d942c | 84 | * only the service/protocol context it wants to use at the time of registration. |
Rohit Grover |
37:c29c330d942c | 85 | * @{ |
Rohit Grover |
37:c29c330d942c | 86 | */ |
Rohit Grover |
37:c29c330d942c | 87 | #define DM_PROTOCOL_CNTXT_NONE 0x00 /**< No Service Context, this implies the application does not want to associate any service/protocol context with the peer device */ |
Rohit Grover |
37:c29c330d942c | 88 | #define DM_PROTOCOL_CNTXT_GATT_SRVR_ID 0x01 /**< GATT Server Service Context, this implies the application does associate GATT Server with the peer device and this information will be loaded when needed for a bonded device */ |
Rohit Grover |
37:c29c330d942c | 89 | #define DM_PROTOCOL_CNTXT_GATT_CLI_ID 0x02 /**< GATT Client Service Context, this implies the application does associate GATT Client with the peer device and this information will be loaded when needed for a bonded device */ |
Rohit Grover |
37:c29c330d942c | 90 | #define DM_PROTOCOL_CNTXT_ALL \ |
Rohit Grover |
37:c29c330d942c | 91 | (DM_PROTOCOL_CNTXT_GATT_SRVR_ID | DM_PROTOCOL_CNTXT_GATT_CLI_ID) /**< All Service/Protocol Context, this implies that the application wants to associate all Service/Protocol Information with the bonded device. This is configurable based on system requirements. If the application has only one type of service, this define could be altered to reflect the same. */ |
Rohit Grover |
37:c29c330d942c | 92 | /** @} */ |
Rohit Grover |
37:c29c330d942c | 93 | |
Rohit Grover |
37:c29c330d942c | 94 | |
Rohit Grover |
37:c29c330d942c | 95 | /** |
Rohit Grover |
37:c29c330d942c | 96 | * @defgroup dm_events Device Manager Events |
Rohit Grover |
37:c29c330d942c | 97 | * |
Rohit Grover |
37:c29c330d942c | 98 | * @brief This section describes the device manager events that are notified to the application. |
Rohit Grover |
37:c29c330d942c | 99 | * |
Rohit Grover |
37:c29c330d942c | 100 | * @details The Device Manager notifies the application of various asynchronous events using the |
Rohit Grover |
37:c29c330d942c | 101 | * asynchronous event notification callback. All events has been categorized into: |
Rohit Grover |
37:c29c330d942c | 102 | * a. General. |
Rohit Grover |
37:c29c330d942c | 103 | * b. Link Status. |
Rohit Grover |
37:c29c330d942c | 104 | * c. Context Management. |
Rohit Grover |
37:c29c330d942c | 105 | * |
Rohit Grover |
37:c29c330d942c | 106 | * In the callback, these events are notified along with handle that uniquely identifies: |
Rohit Grover |
37:c29c330d942c | 107 | * application instance, active instance (if applicable), device instance |
Rohit Grover |
37:c29c330d942c | 108 | * bonding instance, (if applicable) and service instance. |
Rohit Grover |
37:c29c330d942c | 109 | * Not all events are pertaining to an active connection, for example a context deletion event could occur even if the peer |
Rohit Grover |
37:c29c330d942c | 110 | * is not connected. Also, general category of events may not be pertaining to any specific peer. |
Rohit Grover |
37:c29c330d942c | 111 | * See also \ref dm_event_cb_t and \ref dm_register. |
Rohit Grover |
37:c29c330d942c | 112 | * @{ |
Rohit Grover |
37:c29c330d942c | 113 | */ |
Rohit Grover |
37:c29c330d942c | 114 | /** |
Rohit Grover |
37:c29c330d942c | 115 | * @defgroup general_events General Events |
Rohit Grover |
37:c29c330d942c | 116 | * |
Rohit Grover |
37:c29c330d942c | 117 | * @brief General or miscellaneous events. |
Rohit Grover |
37:c29c330d942c | 118 | * |
Rohit Grover |
37:c29c330d942c | 119 | * @details This category of events are general events not pertaining to a peer or context. |
Rohit Grover |
37:c29c330d942c | 120 | * |
Rohit Grover |
37:c29c330d942c | 121 | * @{ |
Rohit Grover |
37:c29c330d942c | 122 | */ |
Rohit Grover |
37:c29c330d942c | 123 | #define DM_EVT_RFU 0x00 /**< Reserved for future use, is never notified. */ |
Rohit Grover |
37:c29c330d942c | 124 | #define DM_EVT_ERROR 0x01 /**< Device Manager Event Error. */ |
Rohit Grover |
37:c29c330d942c | 125 | /** @} */ |
Rohit Grover |
37:c29c330d942c | 126 | |
Rohit Grover |
37:c29c330d942c | 127 | /** |
Rohit Grover |
37:c29c330d942c | 128 | * @defgroup link_status_events Link Status Events |
Rohit Grover |
37:c29c330d942c | 129 | * |
Rohit Grover |
37:c29c330d942c | 130 | * @brief Link Status Events. |
Rohit Grover |
37:c29c330d942c | 131 | * |
Rohit Grover |
37:c29c330d942c | 132 | * @details This category of events notify the application of the link status. Event result associated |
Rohit Grover |
37:c29c330d942c | 133 | * with the event is provided along with the event in the callback to provide more details of |
Rohit Grover |
37:c29c330d942c | 134 | * whether a procedure succeeded or failed and assist the application in decision making of |
Rohit Grover |
37:c29c330d942c | 135 | * how to proceed. For example if a DM_DEVICE_CONNECT_IND is indicated with NRF_SUCCESS |
Rohit Grover |
37:c29c330d942c | 136 | * result, the application may want to proceed with discovering and association with |
Rohit Grover |
37:c29c330d942c | 137 | * service of the peer. However, if indicated with a failure result, the application may |
Rohit Grover |
37:c29c330d942c | 138 | * want to take an alternate action such as reattempting to connect or go into a |
Rohit Grover |
37:c29c330d942c | 139 | * sleep mode. |
Rohit Grover |
37:c29c330d942c | 140 | * |
Rohit Grover |
37:c29c330d942c | 141 | * @{ |
Rohit Grover |
37:c29c330d942c | 142 | */ |
Rohit Grover |
37:c29c330d942c | 143 | #define DM_EVT_CONNECTION 0x11 /**< Indicates that link with the peer is established. */ |
Rohit Grover |
37:c29c330d942c | 144 | #define DM_EVT_DISCONNECTION 0x12 /**< Indicates that link with peer is torn down. */ |
Rohit Grover |
37:c29c330d942c | 145 | #define DM_EVT_SECURITY_SETUP 0x13 /**< Security procedure for link started indication */ |
Rohit Grover |
37:c29c330d942c | 146 | #define DM_EVT_SECURITY_SETUP_COMPLETE 0x14 /**< Security procedure for link completion indication. */ |
Rohit Grover |
37:c29c330d942c | 147 | #define DM_EVT_LINK_SECURED 0x15 /**< Indicates that link with the peer is secured. For bonded devices, subsequent reconnections with bonded peer will result only in this event when the link is secured and setup procedures will not occur unless the bonding information is either lost or deleted on either or both sides. */ |
Rohit Grover |
37:c29c330d942c | 148 | #define DM_EVT_SECURITY_SETUP_REFRESH 0x16 /**< Indicates that the security on the link was re-established. */ |
Rohit Grover |
37:c29c330d942c | 149 | /** @} */ |
Rohit Grover |
37:c29c330d942c | 150 | |
Rohit Grover |
37:c29c330d942c | 151 | /** |
Rohit Grover |
37:c29c330d942c | 152 | * @defgroup context_mgmt_events Context Management Events |
Rohit Grover |
37:c29c330d942c | 153 | * |
Rohit Grover |
37:c29c330d942c | 154 | * @brief Context Management Events. |
Rohit Grover |
37:c29c330d942c | 155 | * |
Rohit Grover |
37:c29c330d942c | 156 | * @details These events notify the application of the status of context loading and storing. |
Rohit Grover |
37:c29c330d942c | 157 | * |
Rohit Grover |
37:c29c330d942c | 158 | * @{ |
Rohit Grover |
37:c29c330d942c | 159 | */ |
Rohit Grover |
37:c29c330d942c | 160 | #define DM_EVT_DEVICE_CONTEXT_LOADED 0x21 /**< Indicates that device context for a peer is loaded. */ |
Rohit Grover |
37:c29c330d942c | 161 | #define DM_EVT_DEVICE_CONTEXT_STORED 0x22 /**< Indicates that device context is stored persistently. */ |
Rohit Grover |
37:c29c330d942c | 162 | #define DM_EVT_DEVICE_CONTEXT_DELETED 0x23 /**< Indicates that device context is deleted. */ |
Rohit Grover |
37:c29c330d942c | 163 | #define DM_EVT_SERVICE_CONTEXT_LOADED 0x31 /**< Indicates that service context for a peer is loaded. */ |
Rohit Grover |
37:c29c330d942c | 164 | #define DM_EVT_SERVICE_CONTEXT_STORED 0x32 /**< Indicates that service context is stored persistently. */ |
Rohit Grover |
37:c29c330d942c | 165 | #define DM_EVT_SERVICE_CONTEXT_DELETED 0x33 /**< Indicates that service context is deleted. */ |
Rohit Grover |
37:c29c330d942c | 166 | #define DM_EVT_APPL_CONTEXT_LOADED 0x41 /**< Indicates that application context for a peer is loaded. */ |
Rohit Grover |
37:c29c330d942c | 167 | #define DM_EVT_APPL_CONTEXT_STORED 0x42 /**< Indicates that application context is stored persistently. */ |
Rohit Grover |
37:c29c330d942c | 168 | #define DM_EVT_APPL_CONTEXT_DELETED 0x43 /**< Indicates that application context is deleted. */ |
Rohit Grover |
37:c29c330d942c | 169 | /** @} */ |
Rohit Grover |
37:c29c330d942c | 170 | /** @} */ |
Rohit Grover |
37:c29c330d942c | 171 | |
Rohit Grover |
37:c29c330d942c | 172 | #define DM_INVALID_ID 0xFF /**< Invalid instance idenitifer. */ |
Rohit Grover |
37:c29c330d942c | 173 | |
Rohit Grover |
37:c29c330d942c | 174 | /** |
Rohit Grover |
37:c29c330d942c | 175 | * @defgroup dm_data_structure Device Manager Data Types |
Rohit Grover |
37:c29c330d942c | 176 | * |
Rohit Grover |
37:c29c330d942c | 177 | * @brief This section describes all the data types exposed by the module to the application. |
Rohit Grover |
37:c29c330d942c | 178 | * @{ |
Rohit Grover |
37:c29c330d942c | 179 | */ |
Rohit Grover |
37:c29c330d942c | 180 | |
Rohit Grover |
37:c29c330d942c | 181 | /** |
Rohit Grover |
37:c29c330d942c | 182 | * @brief Application Instance. |
Rohit Grover |
37:c29c330d942c | 183 | * |
Rohit Grover |
37:c29c330d942c | 184 | * @details Application instance uniquely identifies an application. The identifier is allocated by |
Rohit Grover |
37:c29c330d942c | 185 | * the device manager when application registers with the module. The application is |
Rohit Grover |
37:c29c330d942c | 186 | * expected to identify itself with this instance identifier when initiating subsequent |
Rohit Grover |
37:c29c330d942c | 187 | * requests. Application should use the utility API \ref dm_application_instance_set in |
Rohit Grover |
37:c29c330d942c | 188 | * order to set its application instance in dm_handle_t needed for all subsequent APIs. |
Rohit Grover |
37:c29c330d942c | 189 | * See also \ref dm_register. |
Rohit Grover |
37:c29c330d942c | 190 | */ |
Rohit Grover |
37:c29c330d942c | 191 | typedef uint8_t dm_application_instance_t; |
Rohit Grover |
37:c29c330d942c | 192 | |
Rohit Grover |
37:c29c330d942c | 193 | /** |
Rohit Grover |
37:c29c330d942c | 194 | * @brief Connection Instance. |
Rohit Grover |
37:c29c330d942c | 195 | * |
Rohit Grover |
37:c29c330d942c | 196 | * @details Identifies connection instance for an active device. This instance is allocated by the |
Rohit Grover |
37:c29c330d942c | 197 | * device manager when a connection is established and is notified with DM_EVT_CONNECTION |
Rohit Grover |
37:c29c330d942c | 198 | * with the event result NRF_SUCCESS. |
Rohit Grover |
37:c29c330d942c | 199 | */ |
Rohit Grover |
37:c29c330d942c | 200 | typedef uint8_t dm_connection_instance_t; |
Rohit Grover |
37:c29c330d942c | 201 | |
Rohit Grover |
37:c29c330d942c | 202 | /** |
Rohit Grover |
37:c29c330d942c | 203 | * @brief Device Instance. |
Rohit Grover |
37:c29c330d942c | 204 | * |
Rohit Grover |
37:c29c330d942c | 205 | * @details Uniquely identifies a bonded peer device. The peer device may or may not be connected. |
Rohit Grover |
37:c29c330d942c | 206 | * In case of the central: The bonded device instance to identify the peer is allocated when bonding procedure is initiated by the central using dm_security_setup_req. |
Rohit Grover |
37:c29c330d942c | 207 | * In case of the peripheral: When the bonding procedure is successful, the DM_EVT_SECURITY_SETUP_COMPLETE event with success event result, is received. |
Rohit Grover |
37:c29c330d942c | 208 | * In case the module cannot add more bonded devices, no instance is allocated, this is indicated by an appropriate error code for the API/event as the case may be. Application can choose to disconnect the link. |
Rohit Grover |
37:c29c330d942c | 209 | */ |
Rohit Grover |
37:c29c330d942c | 210 | typedef uint8_t dm_device_instance_t; |
Rohit Grover |
37:c29c330d942c | 211 | |
Rohit Grover |
37:c29c330d942c | 212 | /** |
Rohit Grover |
37:c29c330d942c | 213 | * @brief Service Instance. |
Rohit Grover |
37:c29c330d942c | 214 | * |
Rohit Grover |
37:c29c330d942c | 215 | * @details Uniquely identifies a peer device. The peer device may or may not be connected. This |
Rohit Grover |
37:c29c330d942c | 216 | * instance is allocated by the device manager when a device is bonded and is notified |
Rohit Grover |
37:c29c330d942c | 217 | * when security procedures have been initiated. |
Rohit Grover |
37:c29c330d942c | 218 | * Security Procedures initiation is notified with DM_SECURITY_SETUP_IND with |
Rohit Grover |
37:c29c330d942c | 219 | * success event result. In case the event result indicates that the module cannot add more |
Rohit Grover |
37:c29c330d942c | 220 | * bonded devices, no instance is allocated. Application can chose to disconnect the link. |
Rohit Grover |
37:c29c330d942c | 221 | */ |
Rohit Grover |
37:c29c330d942c | 222 | typedef uint8_t dm_service_instance_t; |
Rohit Grover |
37:c29c330d942c | 223 | |
Rohit Grover |
37:c29c330d942c | 224 | /** |
Rohit Grover |
37:c29c330d942c | 225 | * @brief Service/Protocol Type Identifier. |
Rohit Grover |
37:c29c330d942c | 226 | * |
Rohit Grover |
37:c29c330d942c | 227 | * @details Uniquely identifies a service or a protocol type. Service/Protocol Type identification |
Rohit Grover |
37:c29c330d942c | 228 | * is needed as each service/protocol can have its own contextual data. |
Rohit Grover |
37:c29c330d942c | 229 | * This allows the peer to access more than one service at a time. \ref dm_service_cntext_types describes the |
Rohit Grover |
37:c29c330d942c | 230 | * list of services/protocols supported. |
Rohit Grover |
37:c29c330d942c | 231 | */ |
Rohit Grover |
37:c29c330d942c | 232 | typedef uint8_t service_type_t; |
Rohit Grover |
37:c29c330d942c | 233 | |
Rohit Grover |
37:c29c330d942c | 234 | /** |
Rohit Grover |
37:c29c330d942c | 235 | * @brief Device Handle used for unique identification of each peer. |
Rohit Grover |
37:c29c330d942c | 236 | * |
Rohit Grover |
37:c29c330d942c | 237 | * @details This data type is used to uniquely identify each peer device. A peer device could be |
Rohit Grover |
37:c29c330d942c | 238 | * active and/or bonded. Therefore an instance for active and bonded is provided. |
Rohit Grover |
37:c29c330d942c | 239 | * However, the application is expected to treat this is an opaque structure and use this for |
Rohit Grover |
37:c29c330d942c | 240 | * all API interactions once stored on appropriate events. |
Rohit Grover |
37:c29c330d942c | 241 | * See \ref dm_events. |
Rohit Grover |
37:c29c330d942c | 242 | */ |
Rohit Grover |
37:c29c330d942c | 243 | typedef struct device_handle |
Rohit Grover |
37:c29c330d942c | 244 | { |
Rohit Grover |
37:c29c330d942c | 245 | dm_application_instance_t appl_id; /**< Identifies the application instances for the device that is being managed. */ |
Rohit Grover |
37:c29c330d942c | 246 | dm_connection_instance_t connection_id; /**< Identifies the active connection instance. */ |
Rohit Grover |
37:c29c330d942c | 247 | dm_device_instance_t device_id; /**< Identifies peer instance in the data base. */ |
Rohit Grover |
37:c29c330d942c | 248 | dm_service_instance_t service_id; /**< Service instance identifier. */ |
Rohit Grover |
37:c29c330d942c | 249 | } dm_handle_t; |
Rohit Grover |
37:c29c330d942c | 250 | |
Rohit Grover |
37:c29c330d942c | 251 | /** |
Rohit Grover |
37:c29c330d942c | 252 | * @brief Definition of Data Context. |
Rohit Grover |
37:c29c330d942c | 253 | * |
Rohit Grover |
37:c29c330d942c | 254 | * @details Defines contextual data format, it consists of context data length and pointer to data. |
Rohit Grover |
37:c29c330d942c | 255 | */ |
Rohit Grover |
37:c29c330d942c | 256 | typedef struct |
Rohit Grover |
37:c29c330d942c | 257 | { |
Rohit Grover |
37:c29c330d942c | 258 | uint32_t len; /**< Length of data . */ |
Rohit Grover |
37:c29c330d942c | 259 | uint8_t * p_data; /**< Pointer to contextual data, a copy is made of the data. */ |
Rohit Grover |
37:c29c330d942c | 260 | } dm_context_t; |
Rohit Grover |
37:c29c330d942c | 261 | |
Rohit Grover |
37:c29c330d942c | 262 | |
Rohit Grover |
37:c29c330d942c | 263 | /** |
Rohit Grover |
37:c29c330d942c | 264 | * @brief Device Context. |
Rohit Grover |
37:c29c330d942c | 265 | * |
Rohit Grover |
37:c29c330d942c | 266 | * @details Defines "device context" type for a device managed by device manager. |
Rohit Grover |
37:c29c330d942c | 267 | */ |
Rohit Grover |
37:c29c330d942c | 268 | typedef dm_context_t dm_device_context_t; |
Rohit Grover |
37:c29c330d942c | 269 | |
Rohit Grover |
37:c29c330d942c | 270 | /** |
Rohit Grover |
37:c29c330d942c | 271 | * @brief Service Context. |
Rohit Grover |
37:c29c330d942c | 272 | * |
Rohit Grover |
37:c29c330d942c | 273 | * @details Service context data for a service identified by the 'service_type' field. |
Rohit Grover |
37:c29c330d942c | 274 | */ |
Rohit Grover |
37:c29c330d942c | 275 | typedef struct |
Rohit Grover |
37:c29c330d942c | 276 | { |
Rohit Grover |
37:c29c330d942c | 277 | service_type_t service_type; /**< Identifies the service/protocol to which the context data is related. */ |
Rohit Grover |
37:c29c330d942c | 278 | dm_context_t context_data; /**< Contains length and pointer to context data */ |
Rohit Grover |
37:c29c330d942c | 279 | } dm_service_context_t; |
Rohit Grover |
37:c29c330d942c | 280 | |
Rohit Grover |
37:c29c330d942c | 281 | /** |
Rohit Grover |
37:c29c330d942c | 282 | * @brief Application context. |
Rohit Grover |
37:c29c330d942c | 283 | * |
Rohit Grover |
37:c29c330d942c | 284 | * @details The application context can be used by the application to map any application level |
Rohit Grover |
37:c29c330d942c | 285 | * information that is to be mapped with a particular peer. |
Rohit Grover |
37:c29c330d942c | 286 | * For bonded peers, this information will be stored by the bond manager persistently. |
Rohit Grover |
37:c29c330d942c | 287 | * Note that the device manager treats this information as an |
Rohit Grover |
37:c29c330d942c | 288 | * opaque block of bytes. |
Rohit Grover |
37:c29c330d942c | 289 | * Necessary APIs to get and set this context for a peer have been provided. |
Rohit Grover |
37:c29c330d942c | 290 | */ |
Rohit Grover |
37:c29c330d942c | 291 | typedef dm_context_t dm_application_context_t; |
Rohit Grover |
37:c29c330d942c | 292 | |
Rohit Grover |
37:c29c330d942c | 293 | /** |
Rohit Grover |
37:c29c330d942c | 294 | * @brief Event parameters. |
Rohit Grover |
37:c29c330d942c | 295 | * |
Rohit Grover |
37:c29c330d942c | 296 | * @details Defines event parameters for each of the events notified by the module. |
Rohit Grover |
37:c29c330d942c | 297 | */ |
Rohit Grover |
37:c29c330d942c | 298 | typedef union |
Rohit Grover |
37:c29c330d942c | 299 | { |
Rohit Grover |
37:c29c330d942c | 300 | ble_gap_evt_t * p_gap_param; /**< All events that are triggered in device manager as a result of GAP events, like connection, disconnection and security procedures are accompanied with GAP parameters. */ |
Rohit Grover |
37:c29c330d942c | 301 | dm_application_context_t * p_app_context; /**< All events that are associated with application context procedures of store, load, and deletion have this as event parameter. */ |
Rohit Grover |
37:c29c330d942c | 302 | dm_service_context_t * p_service_context; /**< All events that are associated with service context procedures of store, load and deletion have this as event parameter. */ |
Rohit Grover |
37:c29c330d942c | 303 | dm_device_context_t * p_device_context; /**< All events that are associated with device context procedures of store, load and deletion have this as event parameter. */ |
Rohit Grover |
37:c29c330d942c | 304 | } dm_event_param_t; |
Rohit Grover |
37:c29c330d942c | 305 | |
Rohit Grover |
37:c29c330d942c | 306 | /** |
Rohit Grover |
37:c29c330d942c | 307 | * @brief Asynchronous events details notified to the application by the module. |
Rohit Grover |
37:c29c330d942c | 308 | * |
Rohit Grover |
37:c29c330d942c | 309 | * @details Defines event type along with event parameters notified to the application by the |
Rohit Grover |
37:c29c330d942c | 310 | * module. |
Rohit Grover |
37:c29c330d942c | 311 | */ |
Rohit Grover |
37:c29c330d942c | 312 | typedef struct |
Rohit Grover |
37:c29c330d942c | 313 | { |
Rohit Grover |
37:c29c330d942c | 314 | uint8_t event_id; /**< Identifies the event. See \ref dm_events for details on event types and their significance. */ |
Rohit Grover |
37:c29c330d942c | 315 | dm_event_param_t event_param; /**< Event parameters. Can be NULL if the event does not have any parameters. */ |
Rohit Grover |
37:c29c330d942c | 316 | uint16_t event_paramlen; /**< Length of the event parameters, is zero if the event does not have any parameters. */ |
Rohit Grover |
37:c29c330d942c | 317 | } dm_event_t; |
Rohit Grover |
37:c29c330d942c | 318 | |
Rohit Grover |
37:c29c330d942c | 319 | /** |
Rohit Grover |
37:c29c330d942c | 320 | * @brief Event notification callback registered by application with the module. |
Rohit Grover |
37:c29c330d942c | 321 | * |
Rohit Grover |
37:c29c330d942c | 322 | * @details Event notification callback registered by application with the module when registering |
Rohit Grover |
37:c29c330d942c | 323 | * the module using \ref dm_register API. |
Rohit Grover |
37:c29c330d942c | 324 | * |
Rohit Grover |
37:c29c330d942c | 325 | * @param[in] p_handle Identifies the peer for which the event is being notified. |
Rohit Grover |
37:c29c330d942c | 326 | * @param[in] p_event Identifies the event, any associated parameters and parameter length. |
Rohit Grover |
37:c29c330d942c | 327 | * See \ref dm_events for details on event types and their significance. |
Rohit Grover |
37:c29c330d942c | 328 | * @param[in,out] event_result Provide additional information on the event. |
Rohit Grover |
37:c29c330d942c | 329 | * In addition to SDK error codes there is also a return value |
Rohit Grover |
37:c29c330d942c | 330 | * indicating if maximum number of connections has been reached when connecting or bonding. |
Rohit Grover |
37:c29c330d942c | 331 | * |
Rohit Grover |
37:c29c330d942c | 332 | * @retval NRF_SUCCESS on success, or a failure to indicate if it could handle the event |
Rohit Grover |
37:c29c330d942c | 333 | * successfully. There is no action taken in case application returns a failure. |
Rohit Grover |
37:c29c330d942c | 334 | */ |
Rohit Grover |
37:c29c330d942c | 335 | typedef api_result_t (*dm_event_cb_t)(dm_handle_t const * p_handle, |
Rohit Grover |
37:c29c330d942c | 336 | dm_event_t const * p_event, |
Rohit Grover |
37:c29c330d942c | 337 | api_result_t event_result); |
Rohit Grover |
37:c29c330d942c | 338 | |
Rohit Grover |
37:c29c330d942c | 339 | /** |
Rohit Grover |
37:c29c330d942c | 340 | * @brief Initialization Parameters. |
Rohit Grover |
37:c29c330d942c | 341 | * |
Rohit Grover |
37:c29c330d942c | 342 | * @details Indicates the application parameters. Currently this only encompasses clearing |
Rohit Grover |
37:c29c330d942c | 343 | * all persistent data. |
Rohit Grover |
37:c29c330d942c | 344 | */ |
Rohit Grover |
37:c29c330d942c | 345 | typedef struct |
Rohit Grover |
37:c29c330d942c | 346 | { |
Rohit Grover |
37:c29c330d942c | 347 | bool clear_persistent_data; /**< Set to true in case the module should clear all persistent data. */ |
Rohit Grover |
37:c29c330d942c | 348 | } dm_init_param_t; |
Rohit Grover |
37:c29c330d942c | 349 | |
Rohit Grover |
37:c29c330d942c | 350 | /** |
Rohit Grover |
37:c29c330d942c | 351 | * @brief Application Registration Parameters. |
Rohit Grover |
37:c29c330d942c | 352 | * |
Rohit Grover |
37:c29c330d942c | 353 | * @details Parameters needed by the module when registering with it. |
Rohit Grover |
37:c29c330d942c | 354 | */ |
Rohit Grover |
37:c29c330d942c | 355 | typedef struct |
Rohit Grover |
37:c29c330d942c | 356 | { |
Rohit Grover |
37:c29c330d942c | 357 | dm_event_cb_t evt_handler; /**< Event Handler to be registered. It will receive asynchronous notification from the module, see \ref dm_events for asynchronous events. */ |
Rohit Grover |
37:c29c330d942c | 358 | uint8_t service_type; /**< Bit mask identifying services that the application intends to support for all peers. */ |
Rohit Grover |
37:c29c330d942c | 359 | ble_gap_sec_params_t sec_param; /**< Security parameters to be used for the application. */ |
Rohit Grover |
37:c29c330d942c | 360 | } dm_application_param_t; |
Rohit Grover |
37:c29c330d942c | 361 | |
Rohit Grover |
37:c29c330d942c | 362 | /** |
Rohit Grover |
37:c29c330d942c | 363 | * @brief Defines possible security status/states. |
Rohit Grover |
37:c29c330d942c | 364 | * |
Rohit Grover |
37:c29c330d942c | 365 | * @details Defines possible security status/states of a link when requested by application using |
Rohit Grover |
37:c29c330d942c | 366 | * the \ref dm_security_status_req. |
Rohit Grover |
37:c29c330d942c | 367 | */ |
Rohit Grover |
37:c29c330d942c | 368 | typedef enum |
Rohit Grover |
37:c29c330d942c | 369 | { |
Rohit Grover |
37:c29c330d942c | 370 | NOT_ENCRYPTED, /**< The link does not security. */ |
Rohit Grover |
37:c29c330d942c | 371 | ENCRYPTION_IN_PROGRESS, /**< Security is in progress of being established.*/ |
Rohit Grover |
37:c29c330d942c | 372 | ENCRYPTED /**< The link is secure.*/ |
Rohit Grover |
37:c29c330d942c | 373 | } dm_security_status_t; |
Rohit Grover |
37:c29c330d942c | 374 | /** @} */ |
Rohit Grover |
37:c29c330d942c | 375 | |
Rohit Grover |
37:c29c330d942c | 376 | /** |
Rohit Grover |
37:c29c330d942c | 377 | * @defgroup dm_api Device Module APIs |
Rohit Grover |
37:c29c330d942c | 378 | * |
Rohit Grover |
37:c29c330d942c | 379 | * @brief This section describes APIs exposed by the module. |
Rohit Grover |
37:c29c330d942c | 380 | * |
Rohit Grover |
37:c29c330d942c | 381 | * @details This section describes APIs exposed by the module. The APIs have been categorized to provide |
Rohit Grover |
37:c29c330d942c | 382 | * better and specific look up for developers. Categories are: |
Rohit Grover |
37:c29c330d942c | 383 | * a. Set up APIs. |
Rohit Grover |
37:c29c330d942c | 384 | * b. Context Management APIs. |
Rohit Grover |
37:c29c330d942c | 385 | * c. Utility APIs. |
Rohit Grover |
37:c29c330d942c | 386 | * |
Rohit Grover |
37:c29c330d942c | 387 | * MSCs describe usage of these APIs. See @mscfile dm_api.dox |
Rohit Grover |
37:c29c330d942c | 388 | * @{ |
Rohit Grover |
37:c29c330d942c | 389 | */ |
Rohit Grover |
37:c29c330d942c | 390 | /** |
Rohit Grover |
37:c29c330d942c | 391 | * @defgroup dm_setup_api Device Module Set-up APIs |
Rohit Grover |
37:c29c330d942c | 392 | * |
Rohit Grover |
37:c29c330d942c | 393 | * @brief Initialization & registration APIs that are pre-requisite for all other module procedures. |
Rohit Grover |
37:c29c330d942c | 394 | * @details This section describes the Module Initialization and Registration APIs needed to be set up by |
Rohit Grover |
37:c29c330d942c | 395 | * the application before device manager can start managing devices and device contexts |
Rohit Grover |
37:c29c330d942c | 396 | * for the application. |
Rohit Grover |
37:c29c330d942c | 397 | * |
Rohit Grover |
37:c29c330d942c | 398 | * @{ |
Rohit Grover |
37:c29c330d942c | 399 | */ |
Rohit Grover |
37:c29c330d942c | 400 | |
Rohit Grover |
37:c29c330d942c | 401 | /** |
Rohit Grover |
37:c29c330d942c | 402 | * @brief Module Initialization Routine. |
Rohit Grover |
37:c29c330d942c | 403 | * |
Rohit Grover |
37:c29c330d942c | 404 | * @details Function for initializing the module. Must called before any other APIs of the module are used. |
Rohit Grover |
37:c29c330d942c | 405 | * |
Rohit Grover |
37:c29c330d942c | 406 | * @param[in] p_init_param Initialization parameters. |
Rohit Grover |
37:c29c330d942c | 407 | * |
Rohit Grover |
37:c29c330d942c | 408 | * @retval NRF_SUCCESS On success, else an error code indicating reason for failure. |
Rohit Grover |
37:c29c330d942c | 409 | * |
Rohit Grover |
37:c29c330d942c | 410 | * @note It is mandatory that pstorage is initialized before initializing this module. |
Rohit Grover |
37:c29c330d942c | 411 | */ |
Rohit Grover |
37:c29c330d942c | 412 | api_result_t dm_init(dm_init_param_t const * p_init_param); |
Rohit Grover |
37:c29c330d942c | 413 | |
Rohit Grover |
37:c29c330d942c | 414 | /** |
Rohit Grover |
37:c29c330d942c | 415 | * @brief Function for registering the application. |
Rohit Grover |
37:c29c330d942c | 416 | * |
Rohit Grover |
37:c29c330d942c | 417 | * @details This routine is used by the application to register for asynchronous events with the |
Rohit Grover |
37:c29c330d942c | 418 | * device manager. During registration the application also indicates the services that it |
Rohit Grover |
37:c29c330d942c | 419 | * intends to support on this instance. It is possible to register multiple times with the |
Rohit Grover |
37:c29c330d942c | 420 | * device manager. At least one instance shall be registered with the device manager after |
Rohit Grover |
37:c29c330d942c | 421 | * the module has been initialized. |
Rohit Grover |
37:c29c330d942c | 422 | * Maximum number of application instances device manager can support is determined |
Rohit Grover |
37:c29c330d942c | 423 | * by DM_MAX_APPLICATIONS. |
Rohit Grover |
37:c29c330d942c | 424 | * |
Rohit Grover |
37:c29c330d942c | 425 | * All applications must be registered before initiating or accepting connections from the peer. |
Rohit Grover |
37:c29c330d942c | 426 | * |
Rohit Grover |
37:c29c330d942c | 427 | * @param[in] p_appl_param Application parameters. |
Rohit Grover |
37:c29c330d942c | 428 | * @param[out] p_appl_instance Application Instance Identifier in case registration is successful. |
Rohit Grover |
37:c29c330d942c | 429 | * |
Rohit Grover |
37:c29c330d942c | 430 | * @retval NRF_SUCCESS On success, else an error code indicating reason for failure. |
Rohit Grover |
37:c29c330d942c | 431 | * @retval NRF_ERROR_INVALID_STATE If the API is called without module initialization. |
Rohit Grover |
37:c29c330d942c | 432 | * @retval NRF_ERROR_NO_MEM If module cannot support more applications. |
Rohit Grover |
37:c29c330d942c | 433 | * |
Rohit Grover |
37:c29c330d942c | 434 | * @note Currently only one application instance is supported by the module. |
Rohit Grover |
37:c29c330d942c | 435 | */ |
Rohit Grover |
37:c29c330d942c | 436 | api_result_t dm_register(dm_application_instance_t * p_appl_instance, |
Rohit Grover |
37:c29c330d942c | 437 | dm_application_param_t const * p_appl_param); |
Rohit Grover |
37:c29c330d942c | 438 | |
Rohit Grover |
37:c29c330d942c | 439 | /** |
Rohit Grover |
37:c29c330d942c | 440 | * @brief Function for handling BLE events. |
Rohit Grover |
37:c29c330d942c | 441 | * |
Rohit Grover |
37:c29c330d942c | 442 | * @details BLE Event Handler for the module. This routine should be called from BLE stack event |
Rohit Grover |
37:c29c330d942c | 443 | * dispatcher for the module to work as expected. |
Rohit Grover |
37:c29c330d942c | 444 | * |
Rohit Grover |
37:c29c330d942c | 445 | * @param[in] p_ble_evt BLE stack event being dispatched to the function. |
Rohit Grover |
37:c29c330d942c | 446 | * |
Rohit Grover |
37:c29c330d942c | 447 | */ |
Rohit Grover |
37:c29c330d942c | 448 | void dm_ble_evt_handler(ble_evt_t * p_ble_evt); |
Rohit Grover |
37:c29c330d942c | 449 | |
Rohit Grover |
37:c29c330d942c | 450 | /** @} */ |
Rohit Grover |
37:c29c330d942c | 451 | |
Rohit Grover |
37:c29c330d942c | 452 | |
Rohit Grover |
37:c29c330d942c | 453 | /** |
Rohit Grover |
37:c29c330d942c | 454 | * @defgroup dm_security_api APIs to set up or read status of security on a link. |
Rohit Grover |
37:c29c330d942c | 455 | * |
Rohit Grover |
37:c29c330d942c | 456 | * @brief This section describes APIs to set up Security. These APIs require that the peer is |
Rohit Grover |
37:c29c330d942c | 457 | * connected before the procedures can be requested. |
Rohit Grover |
37:c29c330d942c | 458 | * |
Rohit Grover |
37:c29c330d942c | 459 | * @details This group allows application to request security procedures |
Rohit Grover |
37:c29c330d942c | 460 | * or get the status of the security on a link. |
Rohit Grover |
37:c29c330d942c | 461 | * @{ |
Rohit Grover |
37:c29c330d942c | 462 | */ |
Rohit Grover |
37:c29c330d942c | 463 | /** |
Rohit Grover |
37:c29c330d942c | 464 | * @brief Function for requesting setting up security on a link. |
Rohit Grover |
37:c29c330d942c | 465 | * |
Rohit Grover |
37:c29c330d942c | 466 | * @details This API initiates security procedures with a peer device. |
Rohit Grover |
37:c29c330d942c | 467 | * @note For the GAP Central role, in case peer is not bonded, request to bond/pair is |
Rohit Grover |
37:c29c330d942c | 468 | * initiated. If it is bonded, the link is re-encrypted using the existing bond information. |
Rohit Grover |
37:c29c330d942c | 469 | * For the GAP peripheral role, a Slave security request is sent. |
Rohit Grover |
37:c29c330d942c | 470 | * @details If a pairing procedure is initiated successfully, application is notified of |
Rohit Grover |
37:c29c330d942c | 471 | * @ref DM_EVT_SECURITY_SETUP_COMPLETE. A result indicating success or failure is notified along with the event. |
Rohit Grover |
37:c29c330d942c | 472 | * In case the link is re-encrypted using existing bond information, @ref DM_EVT_LINK_SECURED is |
Rohit Grover |
37:c29c330d942c | 473 | * notified to the application. |
Rohit Grover |
37:c29c330d942c | 474 | * |
Rohit Grover |
37:c29c330d942c | 475 | * @param[in] p_handle Identifies the link on which security is desired. |
Rohit Grover |
37:c29c330d942c | 476 | * |
Rohit Grover |
37:c29c330d942c | 477 | * @retval NRF_SUCCESS On success, else an error code indicating reason for failure. |
Rohit Grover |
37:c29c330d942c | 478 | * @retval NRF_ERROR_INVALID_STATE If the API is called without module initialization and/or |
Rohit Grover |
37:c29c330d942c | 479 | * application registration. |
Rohit Grover |
37:c29c330d942c | 480 | * @retval NRF_ERROR_NULL If p_handle is NULL. |
Rohit Grover |
37:c29c330d942c | 481 | * @retval NRF_ERROR_INVALID_ADDR If the peer is not identified by the handle provided by the application |
Rohit Grover |
37:c29c330d942c | 482 | * or if the peer is not connected when this procedure is requested. |
Rohit Grover |
37:c29c330d942c | 483 | */ |
Rohit Grover |
37:c29c330d942c | 484 | api_result_t dm_security_setup_req(dm_handle_t * p_handle); |
Rohit Grover |
37:c29c330d942c | 485 | |
Rohit Grover |
37:c29c330d942c | 486 | /** |
Rohit Grover |
37:c29c330d942c | 487 | * @brief Function for reading the status of the security on a link. |
Rohit Grover |
37:c29c330d942c | 488 | * |
Rohit Grover |
37:c29c330d942c | 489 | * @details This API allows application to query status of security on a link. |
Rohit Grover |
37:c29c330d942c | 490 | * |
Rohit Grover |
37:c29c330d942c | 491 | * @param[in] p_handle Identifies the link on which security is desired. |
Rohit Grover |
37:c29c330d942c | 492 | * @param[out] p_status Pointer where security status is provided to the application. |
Rohit Grover |
37:c29c330d942c | 493 | * See \ref dm_security_status_t for possible statuses that can be expected. |
Rohit Grover |
37:c29c330d942c | 494 | * |
Rohit Grover |
37:c29c330d942c | 495 | * @retval NRF_SUCCESS Or appropriate error code indicating reason for failure. |
Rohit Grover |
37:c29c330d942c | 496 | * @retval NRF_ERROR_INVALID_STATE If the API is called without module initialization and/or |
Rohit Grover |
37:c29c330d942c | 497 | * application registration. |
Rohit Grover |
37:c29c330d942c | 498 | * @retval NRF_ERROR_NULL If p_handle or p_status is NULL. |
Rohit Grover |
37:c29c330d942c | 499 | * @retval NRF_ERROR_INVALID_ADDR If peer is not identified by the handle provided by the application |
Rohit Grover |
37:c29c330d942c | 500 | * or if peer is not connected when this procedure is requested. |
Rohit Grover |
37:c29c330d942c | 501 | */ |
Rohit Grover |
37:c29c330d942c | 502 | api_result_t dm_security_status_req(dm_handle_t const * p_handle, dm_security_status_t * p_status); |
Rohit Grover |
37:c29c330d942c | 503 | |
Rohit Grover |
37:c29c330d942c | 504 | /** |
Rohit Grover |
37:c29c330d942c | 505 | * @brief Function for creating the whitelist. |
Rohit Grover |
37:c29c330d942c | 506 | * |
Rohit Grover |
37:c29c330d942c | 507 | * @details This API allows application to create whitelist based on bonded peer devices in module |
Rohit Grover |
37:c29c330d942c | 508 | * data base. |
Rohit Grover |
37:c29c330d942c | 509 | * |
Rohit Grover |
37:c29c330d942c | 510 | * @param[in] p_handle Identifies the application requesting whitelist creation. |
Rohit Grover |
37:c29c330d942c | 511 | * @param[in,out] p_whitelist Pointer where created whitelist is provided to the application. |
Rohit Grover |
37:c29c330d942c | 512 | * |
Rohit Grover |
37:c29c330d942c | 513 | * @note 'addr_count' and 'irk_count' fields of the structure should be populated with the maximum |
Rohit Grover |
37:c29c330d942c | 514 | * number of devices that the application wishes to request in the whitelist. |
Rohit Grover |
37:c29c330d942c | 515 | * If the number of bonded devices is less than requested, the fields are updated with that number of devices. |
Rohit Grover |
37:c29c330d942c | 516 | * If the number of devices are more than requested, the module will populate the list |
Rohit Grover |
37:c29c330d942c | 517 | * with devices in the order the bond was established with the peer devices. Also, if this routine is |
Rohit Grover |
37:c29c330d942c | 518 | * called when a connection exists with one or more peer devices, |
Rohit Grover |
37:c29c330d942c | 519 | * those connected devices are not added to the whitelist. |
Rohit Grover |
37:c29c330d942c | 520 | * |
Rohit Grover |
37:c29c330d942c | 521 | * @retval NRF_SUCCESS On success, else an error code indicating reason for failure. |
Rohit Grover |
37:c29c330d942c | 522 | * @retval NRF_ERROR_INVALID_STATE If the API is called without module initialization and/or |
Rohit Grover |
37:c29c330d942c | 523 | * application registration. |
Rohit Grover |
37:c29c330d942c | 524 | * @retval NRF_ERROR_NULL If p_handle or p_whitelist is NULL. |
Rohit Grover |
37:c29c330d942c | 525 | */ |
Rohit Grover |
37:c29c330d942c | 526 | api_result_t dm_whitelist_create(dm_application_instance_t const * p_handle, |
Rohit Grover |
37:c29c330d942c | 527 | ble_gap_whitelist_t * p_whitelist); |
Rohit Grover |
37:c29c330d942c | 528 | |
Rohit Grover |
37:c29c330d942c | 529 | /** @} */ |
Rohit Grover |
37:c29c330d942c | 530 | |
Rohit Grover |
37:c29c330d942c | 531 | |
Rohit Grover |
37:c29c330d942c | 532 | /** |
Rohit Grover |
37:c29c330d942c | 533 | * @defgroup dm_cntxt_mgmt_api Context Management APIs |
Rohit Grover |
37:c29c330d942c | 534 | * |
Rohit Grover |
37:c29c330d942c | 535 | * @brief Utility APIs offered by the device manager to get information about the peer if and |
Rohit Grover |
37:c29c330d942c | 536 | * when needed. |
Rohit Grover |
37:c29c330d942c | 537 | * |
Rohit Grover |
37:c29c330d942c | 538 | * @details This group of API allow the application to access information that is not required to be |
Rohit Grover |
37:c29c330d942c | 539 | * maintained by the application but may be needed. Hence it is possible to get the |
Rohit Grover |
37:c29c330d942c | 540 | * information from the module instead of mapping all the information with a device |
Rohit Grover |
37:c29c330d942c | 541 | * context. |
Rohit Grover |
37:c29c330d942c | 542 | * @{ |
Rohit Grover |
37:c29c330d942c | 543 | */ |
Rohit Grover |
37:c29c330d942c | 544 | |
Rohit Grover |
37:c29c330d942c | 545 | api_result_t dm_device_add(dm_handle_t * p_handle, |
Rohit Grover |
37:c29c330d942c | 546 | dm_device_context_t const * p_context); |
Rohit Grover |
37:c29c330d942c | 547 | |
Rohit Grover |
37:c29c330d942c | 548 | /** |
Rohit Grover |
37:c29c330d942c | 549 | * @brief Function for deleting a peer device context and all related information from the database. |
Rohit Grover |
37:c29c330d942c | 550 | * |
Rohit Grover |
37:c29c330d942c | 551 | * @details Delete peer device context and all related information from database. If |
Rohit Grover |
37:c29c330d942c | 552 | * this API returns NRF_SUCCESS, DM_EVT_DEVICE_CONTEXT_DELETED event is notified to the |
Rohit Grover |
37:c29c330d942c | 553 | * application. Event result notified along with the event indicates success or failure |
Rohit Grover |
37:c29c330d942c | 554 | * of this procedure. |
Rohit Grover |
37:c29c330d942c | 555 | * |
Rohit Grover |
37:c29c330d942c | 556 | * @param[in] p_handle Identifies the peer device to be deleted. |
Rohit Grover |
37:c29c330d942c | 557 | * |
Rohit Grover |
37:c29c330d942c | 558 | * @retval NRF_SUCCESS on success, else an error code indicating reason for failure. |
Rohit Grover |
37:c29c330d942c | 559 | * @retval NRF_ERROR_INVALID_STATE In the API is called without module initialization and/or |
Rohit Grover |
37:c29c330d942c | 560 | * application registration. |
Rohit Grover |
37:c29c330d942c | 561 | * @retval NRF_ERROR_NULL If p_handle is NULL. |
Rohit Grover |
37:c29c330d942c | 562 | * @retval NRF_ERROR_INVALID_ADDR If peer is not identified the handle provided by the application. |
Rohit Grover |
37:c29c330d942c | 563 | * |
Rohit Grover |
37:c29c330d942c | 564 | * @note Deleting device context results in deleting service and application context for the |
Rohit Grover |
37:c29c330d942c | 565 | * bonded device. The respective events DM_EVT_SERVICE_CONTEXT_DELETED and |
Rohit Grover |
37:c29c330d942c | 566 | * DM_EVT_APPL_CONTEXT_DELETED are not notified to the application. |
Rohit Grover |
37:c29c330d942c | 567 | */ |
Rohit Grover |
37:c29c330d942c | 568 | api_result_t dm_device_delete(dm_handle_t const * p_handle); |
Rohit Grover |
37:c29c330d942c | 569 | |
Rohit Grover |
37:c29c330d942c | 570 | /** |
Rohit Grover |
37:c29c330d942c | 571 | * @brief Function for deleting all peer device context and all related information from the database. |
Rohit Grover |
37:c29c330d942c | 572 | * |
Rohit Grover |
37:c29c330d942c | 573 | * @details Delete peer device context and all related information from database. If |
Rohit Grover |
37:c29c330d942c | 574 | * this API returns NRF_SUCCESS, DM_EVT_DEVICE_CONTEXT_DELETED event is notified to the |
Rohit Grover |
37:c29c330d942c | 575 | * application for each device that is deleted from the data base. Event result |
Rohit Grover |
37:c29c330d942c | 576 | * notified along with the event indicates success or failure of this procedure. |
Rohit Grover |
37:c29c330d942c | 577 | * |
Rohit Grover |
37:c29c330d942c | 578 | * @param[in] p_handle Identifies application instance that is requesting |
Rohit Grover |
37:c29c330d942c | 579 | * the deletion of all bonded devices. |
Rohit Grover |
37:c29c330d942c | 580 | * |
Rohit Grover |
37:c29c330d942c | 581 | * @retval NRF_SUCCESS On success, else an error code indicating reason for failure. |
Rohit Grover |
37:c29c330d942c | 582 | * @retval NRF_ERROR_INVALID_STATE If the API is called without module initialization and/or |
Rohit Grover |
37:c29c330d942c | 583 | * application registration. |
Rohit Grover |
37:c29c330d942c | 584 | * @retval NRF_ERROR_NULL If p_handle is NULL. |
Rohit Grover |
37:c29c330d942c | 585 | * @retval NRF_ERROR_INVALID_ADDR If peer is not identified the handle provided by the application. |
Rohit Grover |
37:c29c330d942c | 586 | * |
Rohit Grover |
37:c29c330d942c | 587 | * @note Deleting device context results in deleting both service and application context for the |
Rohit Grover |
37:c29c330d942c | 588 | * bonded device. The respective events DM_EVT_SERVICE_CONTEXT_DELETED and |
Rohit Grover |
37:c29c330d942c | 589 | * DM_EVT_APPL_CONTEXT_DELETED are not notified to the application. |
Rohit Grover |
37:c29c330d942c | 590 | */ |
Rohit Grover |
37:c29c330d942c | 591 | api_result_t dm_device_delete_all(dm_application_instance_t const * p_handle); |
Rohit Grover |
37:c29c330d942c | 592 | |
Rohit Grover |
37:c29c330d942c | 593 | /** |
Rohit Grover |
37:c29c330d942c | 594 | * @brief Function for setting Service Context for a peer device identified by 'p_handle' parameter. |
Rohit Grover |
37:c29c330d942c | 595 | * |
Rohit Grover |
37:c29c330d942c | 596 | * @details This API allows application to Set Service Context for a peer device identified by the |
Rohit Grover |
37:c29c330d942c | 597 | * 'p_handle' parameter. This API is useful when the Service Context cannot be requested |
Rohit Grover |
37:c29c330d942c | 598 | * from the SoftDevice, but needs to be assembled by the application or an another module. |
Rohit Grover |
37:c29c330d942c | 599 | * (or when service context is exchanged in an out of band way.) |
Rohit Grover |
37:c29c330d942c | 600 | * This API could also be used to trigger a storing of service context into persistent |
Rohit Grover |
37:c29c330d942c | 601 | * memory. If this is desired, a NULL pointer could be passed to the p_context. |
Rohit Grover |
37:c29c330d942c | 602 | * |
Rohit Grover |
37:c29c330d942c | 603 | * @param[in] p_handle Identifies peer device for which the procedure is requested. |
Rohit Grover |
37:c29c330d942c | 604 | * @param[in] p_context Service context being set. The context information includes length of |
Rohit Grover |
37:c29c330d942c | 605 | * data and pointer to the contextual data being set. The memory pointed to by |
Rohit Grover |
37:c29c330d942c | 606 | * the pointer to data is assumed to be resident when API is being called and |
Rohit Grover |
37:c29c330d942c | 607 | * can be freed or reused once the set procedure is complete. Set procedure |
Rohit Grover |
37:c29c330d942c | 608 | * completion is indicated by the event \ref DM_EVT_SERVICE_CONTEXT_STORED. |
Rohit Grover |
37:c29c330d942c | 609 | * The Event result is notified along with the event and indicates success or failure of |
Rohit Grover |
37:c29c330d942c | 610 | * this procedure. |
Rohit Grover |
37:c29c330d942c | 611 | * |
Rohit Grover |
37:c29c330d942c | 612 | * @retval NRF_SUCCESS On success, else an error code indicating reason for failure. |
Rohit Grover |
37:c29c330d942c | 613 | * @retval NRF_ERROR_INVALID_STATE If the API is called without module initialization and/or |
Rohit Grover |
37:c29c330d942c | 614 | * application registration. |
Rohit Grover |
37:c29c330d942c | 615 | * @retval NRF_ERROR_NULL If p_handle is NULL. |
Rohit Grover |
37:c29c330d942c | 616 | * @retval NRF_ERROR_INVALID_ADDR If the peer is not identified by the handle provided by the application. |
Rohit Grover |
37:c29c330d942c | 617 | */ |
Rohit Grover |
37:c29c330d942c | 618 | api_result_t dm_service_context_set(dm_handle_t const * p_handle, |
Rohit Grover |
37:c29c330d942c | 619 | dm_service_context_t const * p_context); |
Rohit Grover |
37:c29c330d942c | 620 | |
Rohit Grover |
37:c29c330d942c | 621 | /** |
Rohit Grover |
37:c29c330d942c | 622 | * @brief Function for getting Service Context for a peer device identified by 'p_handle' parameter. |
Rohit Grover |
37:c29c330d942c | 623 | * |
Rohit Grover |
37:c29c330d942c | 624 | * @details Get Service Context for a peer device identified by the 'p_handle' parameter. If |
Rohit Grover |
37:c29c330d942c | 625 | * this API returns NRF_SUCCESS, DM_EVT_SERVICE_CONTEXT_LOADED event is notified to the |
Rohit Grover |
37:c29c330d942c | 626 | * application. The event result is notified along with the event indicates success or failure |
Rohit Grover |
37:c29c330d942c | 627 | * of this procedure. |
Rohit Grover |
37:c29c330d942c | 628 | * |
Rohit Grover |
37:c29c330d942c | 629 | * @param[in] p_handle Identifies peer device for which procedure is requested. |
Rohit Grover |
37:c29c330d942c | 630 | * @param[in] p_context Application context being requested. The context information includes length |
Rohit Grover |
37:c29c330d942c | 631 | * of the data and a pointer to the data. Note that requesting a 'get' |
Rohit Grover |
37:c29c330d942c | 632 | * of application does not need to provide memory, the pointer to data will be |
Rohit Grover |
37:c29c330d942c | 633 | * pointing to service data and hence no data movement is involved. |
Rohit Grover |
37:c29c330d942c | 634 | * |
Rohit Grover |
37:c29c330d942c | 635 | * @retval NRF_SUCCESS On success, else an error code indicating reason for failure. |
Rohit Grover |
37:c29c330d942c | 636 | * @retval NRF_ERROR_INVALID_STATE In case API is called without module initialization and/or |
Rohit Grover |
37:c29c330d942c | 637 | * application registration. |
Rohit Grover |
37:c29c330d942c | 638 | * @retval NRF_ERROR_NULL If p_handle is NULL. |
Rohit Grover |
37:c29c330d942c | 639 | * @retval NRF_ERROR_INVALID_ADDR If the peer is not identified by the handle provided by the application. |
Rohit Grover |
37:c29c330d942c | 640 | */ |
Rohit Grover |
37:c29c330d942c | 641 | api_result_t dm_service_context_get(dm_handle_t const * p_handle, |
Rohit Grover |
37:c29c330d942c | 642 | dm_service_context_t * p_context); |
Rohit Grover |
37:c29c330d942c | 643 | |
Rohit Grover |
37:c29c330d942c | 644 | /** |
Rohit Grover |
37:c29c330d942c | 645 | * @brief Function for deleting a Service Context for a peer device identified by the 'p_handle' parameter. |
Rohit Grover |
37:c29c330d942c | 646 | * |
Rohit Grover |
37:c29c330d942c | 647 | * @details This API allows application to delete a Service Context identified for a peer device |
Rohit Grover |
37:c29c330d942c | 648 | * identified by the 'p_handle' parameter. If this API returns NRF_SUCCESS, |
Rohit Grover |
37:c29c330d942c | 649 | * DM_EVT_SERVICE_CONTEXT_DELETED event is notified to the application. |
Rohit Grover |
37:c29c330d942c | 650 | * Event result is notified along with the event and indicates success or failure of this |
Rohit Grover |
37:c29c330d942c | 651 | * procedure. |
Rohit Grover |
37:c29c330d942c | 652 | * |
Rohit Grover |
37:c29c330d942c | 653 | * @param[in] p_handle Identifies peer device for which procedure is requested. |
Rohit Grover |
37:c29c330d942c | 654 | * |
Rohit Grover |
37:c29c330d942c | 655 | * @retval NRF_SUCCESS On success, else an error code indicating reason for failure. |
Rohit Grover |
37:c29c330d942c | 656 | * @retval NRF_ERROR_INVALID_STATE If the API is called without module initialization and/or |
Rohit Grover |
37:c29c330d942c | 657 | * application registration. |
Rohit Grover |
37:c29c330d942c | 658 | * @retval NRF_ERROR_NULL If p_handle is NULL. |
Rohit Grover |
37:c29c330d942c | 659 | * @retval NRF_ERROR_INVALID_ADDR If the peer is not identified by the handle provided by the application. |
Rohit Grover |
37:c29c330d942c | 660 | */ |
Rohit Grover |
37:c29c330d942c | 661 | api_result_t dm_service_context_delete(dm_handle_t const * p_handle); |
Rohit Grover |
37:c29c330d942c | 662 | |
Rohit Grover |
37:c29c330d942c | 663 | /** |
Rohit Grover |
37:c29c330d942c | 664 | * @brief Function for setting Application Context for a peer device identified by the 'p_handle' parameter. |
Rohit Grover |
37:c29c330d942c | 665 | * |
Rohit Grover |
37:c29c330d942c | 666 | * @details This application allows the setting of the application context for the peer device identified by |
Rohit Grover |
37:c29c330d942c | 667 | * the 'p_handle'. Application context is stored persistently by the module and can be |
Rohit Grover |
37:c29c330d942c | 668 | * requested by the application at any time using the \ref dm_application_context_get |
Rohit Grover |
37:c29c330d942c | 669 | * API. Note that this procedure is permitted only for bonded devices. If the |
Rohit Grover |
37:c29c330d942c | 670 | * device is not bonded, application context cannot be set. However, it is not mandatory |
Rohit Grover |
37:c29c330d942c | 671 | * that the bonded device is connected when requesting this procedure. |
Rohit Grover |
37:c29c330d942c | 672 | * |
Rohit Grover |
37:c29c330d942c | 673 | * @param[in] p_handle Identifies peer device for which procedure is requested. |
Rohit Grover |
37:c29c330d942c | 674 | * |
Rohit Grover |
37:c29c330d942c | 675 | * @param[in] p_context Application context being set. The context information includes length of the |
Rohit Grover |
37:c29c330d942c | 676 | * data and pointer to the contextual data being set. The memory pointed to by |
Rohit Grover |
37:c29c330d942c | 677 | * the data pointer is assumed to be resident when API is being called and |
Rohit Grover |
37:c29c330d942c | 678 | * can be freed or reused once the set procedure is complete. Set procedure |
Rohit Grover |
37:c29c330d942c | 679 | * completion is notified by the event \ref DM_EVT_APPL_CONTEXT_STORED. |
Rohit Grover |
37:c29c330d942c | 680 | * The event result is notified along with the event and indicates success or |
Rohit Grover |
37:c29c330d942c | 681 | * failure of this procedure. |
Rohit Grover |
37:c29c330d942c | 682 | * |
Rohit Grover |
37:c29c330d942c | 683 | * @retval NRF_SUCCESS On success, else an error code indicating reason for failure. |
Rohit Grover |
37:c29c330d942c | 684 | * @retval NRF_ERROR_INVALID_STATE If the API is called without module initialization and/or |
Rohit Grover |
37:c29c330d942c | 685 | * application registration. |
Rohit Grover |
37:c29c330d942c | 686 | * @retval NRF_ERROR_NULL If p_handle and/or p_context is NULL. |
Rohit Grover |
37:c29c330d942c | 687 | * @retval NRF_ERROR_INVALID_ADDR If peer is not identified the handle provided by the application. |
Rohit Grover |
37:c29c330d942c | 688 | * |
Rohit Grover |
37:c29c330d942c | 689 | * @note The API returns FEATURE_NOT_ENABLED in case DEVICE_MANAGER_APP_CONTEXT_SIZE is set to zero. |
Rohit Grover |
37:c29c330d942c | 690 | */ |
Rohit Grover |
37:c29c330d942c | 691 | api_result_t dm_application_context_set(dm_handle_t const * p_handle, |
Rohit Grover |
37:c29c330d942c | 692 | dm_application_context_t const * p_context); |
Rohit Grover |
37:c29c330d942c | 693 | |
Rohit Grover |
37:c29c330d942c | 694 | /** |
Rohit Grover |
37:c29c330d942c | 695 | * @brief Function for getting Application Context for a peer device identified by the 'p_handle' parameter. |
Rohit Grover |
37:c29c330d942c | 696 | * |
Rohit Grover |
37:c29c330d942c | 697 | * @details Get Application Context for a peer device identified by the 'p_handle' parameter. If |
Rohit Grover |
37:c29c330d942c | 698 | * this API returns NRF_SUCCESS, DM_EVT_APPL_CONTEXT_LOADED event is notified to the |
Rohit Grover |
37:c29c330d942c | 699 | * application. Event result notified along with the event indicates success or failure |
Rohit Grover |
37:c29c330d942c | 700 | * of this procedure. |
Rohit Grover |
37:c29c330d942c | 701 | * |
Rohit Grover |
37:c29c330d942c | 702 | * @param[in] p_handle Identifies peer device for which procedure is requested. |
Rohit Grover |
37:c29c330d942c | 703 | * @param[in] p_context Application context being requested. The context information includes |
Rohit Grover |
37:c29c330d942c | 704 | * length of data and pointer to the contextual data is provided. |
Rohit Grover |
37:c29c330d942c | 705 | * |
Rohit Grover |
37:c29c330d942c | 706 | * @retval NRF_SUCCESS On success, else an error code indicating reason for failure. |
Rohit Grover |
37:c29c330d942c | 707 | * @retval NRF_ERROR_INVALID_STATE If the API is called without module initialization and/or |
Rohit Grover |
37:c29c330d942c | 708 | * application registration. |
Rohit Grover |
37:c29c330d942c | 709 | * @retval NRF_ERROR_NULL If p_handle and/or p_context is NULL. |
Rohit Grover |
37:c29c330d942c | 710 | * @retval NRF_ERROR_INVALID_ADDR If the peer is not identified by the handle provided by the application. |
Rohit Grover |
37:c29c330d942c | 711 | * @retval DM_NO_APP_CONTEXT If no application context was set that can be fetched. |
Rohit Grover |
37:c29c330d942c | 712 | * |
Rohit Grover |
37:c29c330d942c | 713 | * @note The API returns FEATURE_NOT_ENABLED in case DEVICE_MANAGER_APP_CONTEXT_SIZE is set to |
Rohit Grover |
37:c29c330d942c | 714 | * zero. |
Rohit Grover |
37:c29c330d942c | 715 | */ |
Rohit Grover |
37:c29c330d942c | 716 | api_result_t dm_application_context_get(dm_handle_t const * p_handle, |
Rohit Grover |
37:c29c330d942c | 717 | dm_application_context_t * p_context); |
Rohit Grover |
37:c29c330d942c | 718 | |
Rohit Grover |
37:c29c330d942c | 719 | /** |
Rohit Grover |
37:c29c330d942c | 720 | * @brief Function for deleting Application Context for a peer device identified by the 'p_handle' parameter. |
Rohit Grover |
37:c29c330d942c | 721 | * |
Rohit Grover |
37:c29c330d942c | 722 | * @details Delete Application Context for a peer device identified by the 'p_handle' parameter. If |
Rohit Grover |
37:c29c330d942c | 723 | * this API returns NRF_SUCCESS, DM_EVT_APPL_CONTEXT_DELETED event is notified to the |
Rohit Grover |
37:c29c330d942c | 724 | * application. The event result notified along with the event and indicates success or failure |
Rohit Grover |
37:c29c330d942c | 725 | * of this procedure. |
Rohit Grover |
37:c29c330d942c | 726 | * |
Rohit Grover |
37:c29c330d942c | 727 | * @param[in] p_handle Identifies peer device for which procedure is requested. |
Rohit Grover |
37:c29c330d942c | 728 | * |
Rohit Grover |
37:c29c330d942c | 729 | * @retval NRF_SUCCESS On success, else an error code indicating reason for failure. |
Rohit Grover |
37:c29c330d942c | 730 | * @retval NRF_ERROR_INVALID_STATE If the API is called without module initialization and/or |
Rohit Grover |
37:c29c330d942c | 731 | * application registration. |
Rohit Grover |
37:c29c330d942c | 732 | * @retval NRF_ERROR_NULL If the p_handle is NULL. |
Rohit Grover |
37:c29c330d942c | 733 | * @retval NRF_ERROR_INVALID_ADDR If peer is not identified the handle provided by the application. |
Rohit Grover |
37:c29c330d942c | 734 | * @retval DM_NO_APP_CONTEXT If no application context was set that can be deleted. |
Rohit Grover |
37:c29c330d942c | 735 | * |
Rohit Grover |
37:c29c330d942c | 736 | * @note The API returns FEATURE_NOT_ENABLED if the DEVICE_MANAGER_APP_CONTEXT_SIZE is set to zero. |
Rohit Grover |
37:c29c330d942c | 737 | */ |
Rohit Grover |
37:c29c330d942c | 738 | api_result_t dm_application_context_delete(dm_handle_t const * p_handle); |
Rohit Grover |
37:c29c330d942c | 739 | |
Rohit Grover |
37:c29c330d942c | 740 | /** @} */ |
Rohit Grover |
37:c29c330d942c | 741 | |
Rohit Grover |
37:c29c330d942c | 742 | |
Rohit Grover |
37:c29c330d942c | 743 | /** |
Rohit Grover |
37:c29c330d942c | 744 | * @defgroup utility_api Utility APIs |
Rohit Grover |
37:c29c330d942c | 745 | * @{ |
Rohit Grover |
37:c29c330d942c | 746 | * @brief This section describes the utility APIs offered by the module. |
Rohit Grover |
37:c29c330d942c | 747 | * |
Rohit Grover |
37:c29c330d942c | 748 | * @details APIs defined in this section are utility or assisting/helper APIs. |
Rohit Grover |
37:c29c330d942c | 749 | */ |
Rohit Grover |
37:c29c330d942c | 750 | /** |
Rohit Grover |
37:c29c330d942c | 751 | * @brief Function for Setting/Copying Application instance to Device Manager handle. |
Rohit Grover |
37:c29c330d942c | 752 | * |
Rohit Grover |
37:c29c330d942c | 753 | * @param[in] p_appl_instance Application instance to be set. |
Rohit Grover |
37:c29c330d942c | 754 | * @param[out] p_handle Device Manager handle for which the instance is to be copied. |
Rohit Grover |
37:c29c330d942c | 755 | * |
Rohit Grover |
37:c29c330d942c | 756 | * @retval NRF_SUCCESS On success, else an error code indicating reason for failure. |
Rohit Grover |
37:c29c330d942c | 757 | * @retval NRF_ERROR_INVALID_STATE If the API is called without module initialization and/or |
Rohit Grover |
37:c29c330d942c | 758 | * application registration. |
Rohit Grover |
37:c29c330d942c | 759 | * @retval NRF_ERROR_NULL If p_handle and/or p_addr is NULL. |
Rohit Grover |
37:c29c330d942c | 760 | */ |
Rohit Grover |
37:c29c330d942c | 761 | api_result_t dm_application_instance_set(dm_application_instance_t const * p_appl_instance, |
Rohit Grover |
37:c29c330d942c | 762 | dm_handle_t * p_handle); |
Rohit Grover |
37:c29c330d942c | 763 | |
Rohit Grover |
37:c29c330d942c | 764 | /** |
Rohit Grover |
37:c29c330d942c | 765 | * @brief Function for getting a peer's device address. |
Rohit Grover |
37:c29c330d942c | 766 | * |
Rohit Grover |
37:c29c330d942c | 767 | * @param[in] p_handle Identifies the peer device whose address is requested. Can not be NULL. |
Rohit Grover |
37:c29c330d942c | 768 | * @param[out] p_addr Pointer where address is to be copied. Can not be NULL. |
Rohit Grover |
37:c29c330d942c | 769 | * |
Rohit Grover |
37:c29c330d942c | 770 | * @retval NRF_SUCCESS On success, else an error code indicating reason for failure. |
Rohit Grover |
37:c29c330d942c | 771 | * @retval NRF_ERROR_INVALID_STATE If the API is called without module initialization and/or |
Rohit Grover |
37:c29c330d942c | 772 | * application registration. |
Rohit Grover |
37:c29c330d942c | 773 | * @retval NRF_ERROR_NULL If p_handle and/or p_addr is NULL. |
Rohit Grover |
37:c29c330d942c | 774 | * @retval NRF_ERROR_NOT_FOUND If the peer could not be identified. |
Rohit Grover |
37:c29c330d942c | 775 | */ |
Rohit Grover |
37:c29c330d942c | 776 | api_result_t dm_peer_addr_get(dm_handle_t const * p_handle, |
Rohit Grover |
37:c29c330d942c | 777 | ble_gap_addr_t * p_addr); |
Rohit Grover |
37:c29c330d942c | 778 | |
Rohit Grover |
37:c29c330d942c | 779 | /** |
Rohit Grover |
37:c29c330d942c | 780 | * @brief Function for setting/updating a peer's device address. |
Rohit Grover |
37:c29c330d942c | 781 | * |
Rohit Grover |
37:c29c330d942c | 782 | * @param[in] p_handle Identifies the peer device whose address is requested to be set/updated. |
Rohit Grover |
37:c29c330d942c | 783 | * @param[out] p_addr Address to be set/updated. |
Rohit Grover |
37:c29c330d942c | 784 | * |
Rohit Grover |
37:c29c330d942c | 785 | * @retval NRF_SUCCESS On success, else an error code indicating reason for failure. |
Rohit Grover |
37:c29c330d942c | 786 | * @retval NRF_ERROR_INVALID_STATE If the API is called without module initialization and/or |
Rohit Grover |
37:c29c330d942c | 787 | * application registration. |
Rohit Grover |
37:c29c330d942c | 788 | * @retval NRF_ERROR_NULL If p_handle and/or p_addr is NULL. |
Rohit Grover |
37:c29c330d942c | 789 | * @retval NRF_ERROR_INVALID_ADDR If the peer is not identified by the handle provided by the application. |
Rohit Grover |
37:c29c330d942c | 790 | * @retval NRF_ERROR_INVALID_PARAM If this procedure is requested while connected to the peer or if the address |
Rohit Grover |
37:c29c330d942c | 791 | * type was set to BLE_GAP_ADDR_TYPE_RANDOM_PRIVATE_RESOLVABLE. |
Rohit Grover |
37:c29c330d942c | 792 | * |
Rohit Grover |
37:c29c330d942c | 793 | * @note Setting or updating a peer's device address is permitted |
Rohit Grover |
37:c29c330d942c | 794 | * only for a peer that is bonded and disconnected. |
Rohit Grover |
37:c29c330d942c | 795 | * @note Updated address is reflected only after DM_EVT_DEVICE_CONTEXT_STORED is notified to the |
Rohit Grover |
37:c29c330d942c | 796 | * application for this bonded device instance. In order to avoid abnormal behaviour, it is |
Rohit Grover |
37:c29c330d942c | 797 | * recommended to not invite/initiate connections on the updated address unless this event |
Rohit Grover |
37:c29c330d942c | 798 | * has been notified. |
Rohit Grover |
37:c29c330d942c | 799 | */ |
Rohit Grover |
37:c29c330d942c | 800 | api_result_t dm_peer_addr_set(dm_handle_t const * p_handle, |
Rohit Grover |
37:c29c330d942c | 801 | ble_gap_addr_t const * p_addr); |
Rohit Grover |
37:c29c330d942c | 802 | |
Rohit Grover |
37:c29c330d942c | 803 | /** |
Rohit Grover |
37:c29c330d942c | 804 | * @brief Function for initializing Device Manager handle. |
Rohit Grover |
37:c29c330d942c | 805 | * |
Rohit Grover |
37:c29c330d942c | 806 | * @param[in] p_handle Device Manager handle to be initialized. |
Rohit Grover |
37:c29c330d942c | 807 | * |
Rohit Grover |
37:c29c330d942c | 808 | * @retval NRF_SUCCESS On success. |
Rohit Grover |
37:c29c330d942c | 809 | * @retval NRF_ERROR_NULL If p_handle is NULL. |
Rohit Grover |
37:c29c330d942c | 810 | * |
Rohit Grover |
37:c29c330d942c | 811 | * @note This routine is permitted before initialization of the module. |
Rohit Grover |
37:c29c330d942c | 812 | */ |
Rohit Grover |
37:c29c330d942c | 813 | api_result_t dm_handle_initialize(dm_handle_t * p_handle); |
Rohit Grover |
37:c29c330d942c | 814 | |
Rohit Grover |
37:c29c330d942c | 815 | #ifdef GAP_CENTRAL |
Rohit Grover |
37:c29c330d942c | 816 | /** |
Rohit Grover |
37:c29c330d942c | 817 | * @brief Function for getting distributed keys for a device. |
Rohit Grover |
37:c29c330d942c | 818 | * |
Rohit Grover |
37:c29c330d942c | 819 | * @details This routine is used to get distributed keys with a bonded device. This API is currently |
Rohit Grover |
37:c29c330d942c | 820 | * only available on S120 (GAP Central role). |
Rohit Grover |
37:c29c330d942c | 821 | * |
Rohit Grover |
37:c29c330d942c | 822 | * @param[in] p_handle Device Manager handle identifying the peer. |
Rohit Grover |
37:c29c330d942c | 823 | * |
Rohit Grover |
37:c29c330d942c | 824 | * @param[out] p_key_dist Pointer to distributed keys. |
Rohit Grover |
37:c29c330d942c | 825 | * |
Rohit Grover |
37:c29c330d942c | 826 | * @retval NRF_SUCCESS On success, else an error code indicating reason for failure. |
Rohit Grover |
37:c29c330d942c | 827 | * @retval NRF_ERROR_INVALID_STATE If the API is called without module initialization and/or |
Rohit Grover |
37:c29c330d942c | 828 | * application registration. |
Rohit Grover |
37:c29c330d942c | 829 | * @retval NRF_ERROR_NULL If the p_handle and/or p_key_dist pointer is NULL. |
Rohit Grover |
37:c29c330d942c | 830 | * @retval NRF_ERROR_INVALID_ADDR If the peer is not identified by the handle provided by the application. |
Rohit Grover |
37:c29c330d942c | 831 | */ |
Rohit Grover |
37:c29c330d942c | 832 | api_result_t dm_distributed_keys_get(dm_handle_t const * p_handle, |
Rohit Grover |
37:c29c330d942c | 833 | ble_gap_sec_keyset_t * p_key_dist); |
Rohit Grover |
37:c29c330d942c | 834 | #endif // GAP_CENTRAL |
Rohit Grover |
37:c29c330d942c | 835 | /** @} */ |
Rohit Grover |
37:c29c330d942c | 836 | /** @} */ |
Rohit Grover |
37:c29c330d942c | 837 | /** @} */ |
Rohit Grover |
37:c29c330d942c | 838 | #endif // DEVICE_MANAGER_H__ |
Rohit Grover |
37:c29c330d942c | 839 |