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