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_NRF52_DK/TARGET_NORDIC/TARGET_NRF5/sdk/ble/device_manager/device_manager.h@136:ef9c61f8c49f, 2017-02-14 (annotated)

Committer:
Kojto
Date:
Tue Feb 14 11:24:20 2017 +0000
Revision:
136:ef9c61f8c49f
Parent:
123:b0220dba8be7 
Release 136 of the mbed library



Ports for Upcoming Targets





Fixes and Changes



3432: Target STM USBHOST support https://github.com/ARMmbed/mbed-os/pull/3432

3181: NUCLEO_F207ZG extending PeripheralPins.c: all available alternate functions can be used now https://github.com/ARMmbed/mbed-os/pull/3181

3626: NUCLEO_F412ZG : Add USB Device +Host https://github.com/ARMmbed/mbed-os/pull/3626

3628: Fix warnings https://github.com/ARMmbed/mbed-os/pull/3628

3629: STM32: L0 LL layer https://github.com/ARMmbed/mbed-os/pull/3629

3632: IDE Export support for platform VK_RZ_A1H https://github.com/ARMmbed/mbed-os/pull/3632

3642: Missing IRQ pin fix for platform VK_RZ_A1H https://github.com/ARMmbed/mbed-os/pull/3642

3664: Fix ncs36510 sleep definitions https://github.com/ARMmbed/mbed-os/pull/3664

3655: [STM32F4] Modify folder structure https://github.com/ARMmbed/mbed-os/pull/3655

3657: [STM32L4] Modify folder structure https://github.com/ARMmbed/mbed-os/pull/3657

3658: [STM32F3] Modify folder structure https://github.com/ARMmbed/mbed-os/pull/3658

3685: STM32: I2C: reset state machine https://github.com/ARMmbed/mbed-os/pull/3685

3692: uVisor: Standardize available legacy heap and stack https://github.com/ARMmbed/mbed-os/pull/3692

3621: Fix for #2884, LPC824: export to LPCXpresso, target running with wron https://github.com/ARMmbed/mbed-os/pull/3621

3649: [STM32F7] Modify folder structure  https://github.com/ARMmbed/mbed-os/pull/3649

3695: Enforce device_name is valid in targets.json https://github.com/ARMmbed/mbed-os/pull/3695

3723: NCS36510: spi_format function bug fix https://github.com/ARMmbed/mbed-os/pull/3723

Who changed what in which revision?

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