Nordic Semiconductor / nRF51822

Nordic stack and drivers for the mbed BLE API

Dependents:   BLE_ANCS_SDAPI BLE_temperature BLE_HeartRate writable_gatt ... more

TARGET_MCU_NRF51822/sdk/source/ble/device_manager/device_manager.h@638:c90ae1400bf2, 2016-09-14 (annotated)

Committer:
Vincent Coubard
Date:
Wed Sep 14 14:39:43 2016 +0100
Revision:
638:c90ae1400bf2
Sync with bdab10dc0f90748b6989c8b577771bb403ca6bd8 from ARMmbed/mbed-os.

Who changed what in which revision?

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