mbed official / mbed

The official Mbed 2 C/C++ SDK provides the software platform and libraries to build your applications.

Dependents:   hello SerialTestv11 SerialTestv12 Sierpinski ... more

mbed 2

This is the mbed 2 library. If you'd like to learn about Mbed OS please see the mbed-os docs.

TARGET_TY51822R3/TOOLCHAIN_IAR/device_manager.h@171:3a7713b1edbc, 2018-11-08 (annotated)

Committer:
AnnaBridge
Date:
Thu Nov 08 11:45:42 2018 +0000
Revision:
171:3a7713b1edbc
Parent:
TARGET_TY51822R3/TARGET_NORDIC/TARGET_NRF5x/TARGET_SDK_11/ble/device_manager/device_manager.h@169:a7c7b631e539 
mbed library. Release version 164

Who changed what in which revision?

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