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