device_manager.h

00001 /*
00002  * Copyright (c) Nordic Semiconductor ASA
00003  * All rights reserved.
00004  *
00005  * Redistribution and use in source and binary forms, with or without modification,
00006  * are permitted provided that the following conditions are met:
00007  *
00008  *   1. Redistributions of source code must retain the above copyright notice, this
00009  *   list of conditions and the following disclaimer.
00010  *
00011  *   2. Redistributions in binary form must reproduce the above copyright notice, this
00012  *   list of conditions and the following disclaimer in the documentation and/or
00013  *   other materials provided with the distribution.
00014  *
00015  *   3. Neither the name of Nordic Semiconductor ASA nor the names of other
00016  *   contributors to this software may be used to endorse or promote products
00017  *   derived from this software without specific prior written permission.
00018  *
00019  *
00020  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
00021  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
00022  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
00023  * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
00024  * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
00025  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
00026  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
00027  * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
00028  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
00029  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00030  *
00031  */
00032 
00033 /**
00034  * @file device_manager.h
00035  *
00036  * @defgroup device_manager Device Manager
00037  * @ingroup ble_sdk_lib
00038  * @{
00039  * @brief Device Manager Application Interface Abstraction.
00040  *
00041  * @details The Device Manager module manages Active and Bonded Peers. Management of peer includes
00042  *          book keeping of contextual information like the Security Keys, GATT
00043  *          configuration and any application specific information.
00044  *
00045  *          Active Peers are devices which are connected, and may or may not be bonded.
00046  *          Bonded Peers are devices which are bonded, and may or may not be Active (Connected).
00047  *          Active Bonded Peer refers to a device which is connected and bonded.
00048  *
00049  *          Paired Devices refers to peer devices that are connected and have necessary context
00050  *          establishment/exchange for the current connection session. On disconnect,
00051  *          all contextual information is flushed. For example, SMP Information Exchanged during
00052  *          pairing and GATT Configuration is not retained on disconnection.
00053  *
00054  *          Note that this module allows management of contextual information but 
00055  *          does not provide an interface for connection management. Therefore, entering connectible
00056  *          mode, connection establishment, or disconnection of a link with peer is not in scope
00057  *          of this module.
00058  *
00059  *          For bonded peers, the contextual information is required to be retained on disconnection
00060  *          and power cycling. Persistent storage of contextual information is handled by the
00061  *          module. This module categorizes the contextual information into 3 categories:
00062  *             - <b>Bonding Information</b>
00063  *               Bond information is the information exchanged between local and peer device to
00064  *               establish a bond. It also includes peer identification information,
00065  *               like the peer address or the IRK or both. From here on this category of information
00066  *               is referred to as Device Context.
00067  *             - <b>Service/Protocol Information</b>
00068  *               Service/Protocol information is the information retained for the peer to save on one-time
00069  *               procedures like the GATT Service Discovery procedures and Service Configurations.
00070  *               It allows devices to resume data exchange on subsequent reconnection without having
00071  *               to perform initial set-up procedures each time. From here on this category is
00072  *               referred to as Service Context.
00073  *             - <b>Application Information</b>
00074  *               Application information is the context that the application would like to associate with
00075  *               each of the bonded device. For example, if the application chooses to rank its peers
00076  *               in order to manage them better, the rank information could be treated as
00077  *               Application Information. This storage space is provided to save the application from
00078  *               maintaining a mapping table with each Device Instance and Application Information.
00079  *               However, if the application have no use for this, it is possible to not
00080  *               use or employ this at compile time. From here on this category of information is
00081  *               referred to as Application Context.
00082  */
00083 
00084 
00085 #ifndef DEVICE_MANAGER_H__
00086 #define DEVICE_MANAGER_H__
00087 
00088 #include <stdint.h>
00089 #include <stdbool.h>
00090 #include "sdk_common.h"
00091 #include "ble.h"
00092 #include "ble_gap.h"
00093 #include "device_manager_cnfg.h "
00094 
00095 #ifdef __cplusplus
00096 extern "C" {
00097 #endif
00098 
00099 /**
00100  * @defgroup dm_service_cntext_types Service/Protocol Types
00101  *
00102  * @brief Describes the possible types of Service/Protocol Contexts for a bonded/peer device.
00103  *
00104  * @details Possible Service/Protocol context per peer device. The Device Manager provides the
00105  *          functionality of persistently storing the Service/Protocol context and can automatically
00106  *          load them when needed.
00107  *          For example system attributes for a GATT Server. Based on the nature of the application, 
00108  *          not all service types may be needed. The application can specify
00109  *          only the service/protocol context it wants to use at the time of registration.
00110  * @{
00111  */
00112 #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 */
00113 #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 */
00114 #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 */
00115 #define DM_PROTOCOL_CNTXT_ALL                                                                     \
00116         (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.  */
00117 /** @} */
00118 
00119 
00120 /**
00121  * @defgroup dm_events Device Manager Events
00122  *
00123  * @brief This section describes the device manager events that are notified to the application.
00124  *
00125  * @details The Device Manager notifies the application of various asynchronous events using the
00126  *          asynchronous event notification callback. All events has been categorized into:
00127  *          a. General.
00128  *          b. Link Status.
00129  *          c. Context Management.
00130  *
00131  *          In the callback, these events are notified along with handle that uniquely identifies:
00132  *          application instance, active instance (if applicable), device instance
00133  *          bonding instance, (if applicable) and service instance.
00134  *          Not all events are pertaining to an active connection, for example a context deletion event could occur even if the peer
00135  *          is not connected. Also, general category of events may not be pertaining to any specific peer.
00136  *          See also \ref dm_event_cb_t and \ref dm_register.
00137  * @{
00138  */
00139 /**
00140  * @defgroup general_events General Events
00141  *
00142  * @brief General or miscellaneous events.
00143  *
00144  * @details This category of events are general events not pertaining to a peer or context.
00145  *
00146  * @{
00147  */
00148 #define DM_EVT_RFU   0x00 /**< Reserved for future use, is never notified. */
00149 #define DM_EVT_ERROR 0x01 /**< Device Manager Event Error. */
00150 /** @} */
00151 
00152 /**
00153  * @defgroup link_status_events Link Status Events
00154  *
00155  * @brief Link Status Events.
00156  *
00157  * @details This category of events notify the application of the link status. Event result associated
00158  *          with the event is provided along with the event in the callback to provide more details of
00159  *          whether a procedure succeeded or failed and assist the application in decision making of
00160  *          how to proceed. For example if a DM_DEVICE_CONNECT_IND is indicated with NRF_SUCCESS
00161  *          result, the application may want to proceed with discovering and association with
00162  *          service of the peer. However, if indicated with a failure result, the application may
00163  *          want to take an alternate action such as reattempting to connect or go into a
00164  *          sleep mode.
00165  *
00166  * @{
00167  */
00168 #define DM_EVT_CONNECTION              0x11 /**< Indicates that link with the peer is established. */
00169 #define DM_EVT_DISCONNECTION           0x12 /**< Indicates that link with peer is torn down. */
00170 #define DM_EVT_SECURITY_SETUP          0x13 /**< Security procedure for link started indication */
00171 #define DM_EVT_SECURITY_SETUP_COMPLETE 0x14 /**< Security procedure for link completion indication. */
00172 #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.  */
00173 #define DM_EVT_SECURITY_SETUP_REFRESH  0x16 /**< Indicates that the security on the link was re-established. */
00174 /** @} */
00175 
00176 /**
00177  * @defgroup context_mgmt_events Context Management Events
00178  *
00179  * @brief Context Management Events.
00180  *
00181  * @details These events notify the application of the status of context loading and storing.
00182  *
00183  * @{
00184  */
00185 #define DM_EVT_DEVICE_CONTEXT_LOADED   0x21 /**< Indicates that device context for a peer is loaded. */
00186 #define DM_EVT_DEVICE_CONTEXT_STORED   0x22 /**< Indicates that device context is stored persistently. */
00187 #define DM_EVT_DEVICE_CONTEXT_DELETED  0x23 /**< Indicates that device context is deleted. */
00188 #define DM_EVT_SERVICE_CONTEXT_LOADED  0x31 /**< Indicates that service context for a peer is loaded. */
00189 #define DM_EVT_SERVICE_CONTEXT_STORED  0x32 /**< Indicates that service context is stored persistently. */
00190 #define DM_EVT_SERVICE_CONTEXT_DELETED 0x33 /**< Indicates that service context is deleted. */
00191 #define DM_EVT_APPL_CONTEXT_LOADED     0x41 /**< Indicates that application context for a peer is loaded. */
00192 #define DM_EVT_APPL_CONTEXT_STORED     0x42 /**< Indicates that application context is stored persistently. */
00193 #define DM_EVT_APPL_CONTEXT_DELETED    0x43 /**< Indicates that application context is deleted. */
00194 /** @} */
00195 /** @} */
00196 
00197 #define DM_INVALID_ID 0xFF /**< Invalid instance idenitifer. */
00198 
00199 /**
00200  * @defgroup dm_data_structure Device Manager Data Types
00201  *
00202  * @brief This section describes all the data types exposed by the module to the application.
00203  * @{
00204  */
00205 
00206 /**
00207  * @brief Application Instance.
00208  *
00209  * @details Application instance uniquely identifies an application. The identifier is allocated by
00210  *          the device manager when application registers with the module. The application is
00211  *          expected to identify itself with this instance identifier when initiating subsequent
00212  *          requests. Application should use the utility API \ref dm_application_instance_set in
00213  *          order to set its application instance in dm_handle_t needed for all subsequent APIs.
00214  *          See also \ref dm_register.
00215  */
00216 typedef uint8_t dm_application_instance_t;
00217 
00218 /**
00219  * @brief Connection Instance.
00220  *
00221  * @details Identifies connection instance for an active device. This instance is allocated by the 
00222  *          device manager when a connection is established and is notified with DM_EVT_CONNECTION
00223  *          with the event result NRF_SUCCESS.
00224  */
00225 typedef uint8_t dm_connection_instance_t;
00226 
00227 /**
00228  * @brief Device Instance.
00229  *
00230  * @details Uniquely identifies a bonded peer device. The peer device may or may not be connected.
00231  *          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.
00232  *          In case of the peripheral: When the bonding procedure is successful, the DM_EVT_SECURITY_SETUP_COMPLETE event with success event result, is received.
00233  *          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.
00234  */
00235 typedef uint8_t dm_device_instance_t;
00236 
00237 /**
00238  * @brief Service Instance.
00239  *
00240  * @details Uniquely identifies a peer device. The peer device may or may not be connected. This
00241  *          instance is allocated by the device manager when a device is bonded and is notified
00242  *          when security procedures have been initiated.
00243  *          Security Procedures initiation is notified with DM_SECURITY_SETUP_IND with
00244  *          success event result. In case the event result indicates that the module cannot add more
00245  *          bonded devices, no instance is allocated. Application can chose to disconnect the link.
00246  */
00247 typedef uint8_t dm_service_instance_t;
00248 
00249 /**
00250  * @brief Service/Protocol Type Identifier.
00251  *
00252  * @details Uniquely identifies a service or a protocol type. Service/Protocol Type identification
00253  *          is needed as each service/protocol can have its own contextual data.
00254  *          This allows the peer to access more than one service at a time. \ref dm_service_cntext_types describes the
00255  *          list of services/protocols supported.
00256  */
00257 typedef uint8_t service_type_t;
00258 
00259 /**@brief Device Manager Master identification and encryption information. */
00260 typedef struct dm_enc_key
00261 {
00262     ble_gap_enc_info_t  enc_info;  /**< GAP encryption information. */
00263     ble_gap_master_id_t master_id; /**< Master identification. */
00264 } dm_enc_key_t;
00265 
00266 /** @brief Device Manager identity and address information. */
00267 typedef struct dm_id_key
00268 {
00269   ble_gap_irk_t  id_info;      /**< Identity information. */
00270   ble_gap_addr_t id_addr_info; /**< Identity address information. */
00271 } dm_id_key_t;
00272 
00273 /** @brief Device Manager signing information. */
00274 typedef struct dm_sign_key
00275 {
00276     ble_gap_sign_info_t sign_key; /**< GAP signing information. */
00277 } dm_sign_key_t;
00278 
00279 /** @brief Security keys. */
00280 typedef struct dm_sec_keyset
00281 {
00282     union 
00283     {
00284         dm_enc_key_t       * p_enc_key;  /**< Pointer to Device Manager encryption information structure. */
00285     } enc_key;
00286     dm_id_key_t   * p_id_key;            /**< Identity key, or NULL. */
00287     dm_sign_key_t * p_sign_key;          /**< Signing key, or NULL. */
00288 } dm_sec_keys_t;
00289 
00290 /** @brief Device Manager security key set. */
00291 typedef struct
00292 {
00293   dm_sec_keys_t keys_periph;  /**< Keys distributed by the device in the Peripheral role. */
00294   dm_sec_keys_t keys_central; /**< Keys distributed by the device in the Central role. */
00295 } dm_sec_keyset_t;
00296 
00297 /**
00298  * @brief Device Handle used for unique identification of each peer.
00299  *
00300  * @details This data type is used to uniquely identify each peer device. A peer device could be
00301  *          active and/or bonded. Therefore an instance for active and bonded is provided.
00302  *          However, the application is expected to treat this is an opaque structure and use this for
00303  *          all API interactions once stored on appropriate events.
00304  *          See \ref dm_events.
00305  */
00306 typedef struct device_handle
00307 {
00308     dm_application_instance_t    appl_id;       /**< Identifies the application instances for the device that is being managed. */
00309     dm_connection_instance_t     connection_id; /**< Identifies the active connection instance. */
00310     dm_device_instance_t         device_id;     /**< Identifies peer instance in the data base. */
00311     dm_service_instance_t        service_id;    /**< Service instance identifier. */
00312 } dm_handle_t;
00313 
00314 /**
00315  * @brief Definition of Data Context.
00316  *
00317  * @details Defines contextual data format, it consists of context data length and pointer to data.
00318  */
00319 typedef struct
00320 {
00321     uint32_t  flags;  /**< Additional flags identifying data. */
00322     uint32_t  len;    /**< Length of data. */
00323     uint8_t * p_data; /**< Pointer to contextual data, a copy is made of the data. */
00324 } dm_context_t;
00325 
00326 
00327 /**
00328  * @brief Device Context.
00329  *
00330  * @details Defines "device context" type for a device managed by device manager.
00331  */
00332 typedef dm_context_t dm_device_context_t;
00333 
00334 /**
00335  * @brief Service Context.
00336  *
00337  * @details Service context data for a service identified by the 'service_type' field.
00338  */
00339 typedef struct
00340 {
00341     service_type_t service_type; /**< Identifies the service/protocol to which the context data is related. */
00342     dm_context_t   context_data; /**< Contains length and pointer to context data */
00343 } dm_service_context_t;
00344 
00345 /**
00346  * @brief Application context.
00347  *
00348  * @details The application context can be used by the application to map any application level
00349  *          information that is to be mapped with a particular peer.
00350  *          For bonded peers, this information will be stored by the bond manager persistently.
00351  *          Note that the device manager treats this information as an
00352  *          opaque block of bytes.
00353  *          Necessary APIs to get and set this context for a peer have been provided.
00354  */
00355 typedef dm_context_t dm_application_context_t;
00356 
00357 /**
00358  * @brief Event parameters.
00359  *
00360  * @details Defines event parameters for each of the events notified by the module.
00361  */
00362 typedef union
00363 {
00364     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. */
00365     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. */
00366     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. */
00367     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. */
00368 } dm_event_param_t;
00369 
00370 /**
00371  * @brief Asynchronous events details notified to the application by the module.
00372  *
00373  * @details Defines event type along with event parameters notified to the application by the
00374  *          module.
00375  */
00376 typedef struct
00377 {
00378     uint8_t          event_id;       /**< Identifies the event. See \ref dm_events for details on event types and their significance. */
00379     dm_event_param_t event_param;    /**< Event parameters. Can be NULL if the event does not have any parameters. */
00380     uint16_t         event_paramlen; /**< Length of the event parameters, is zero if the event does not have any parameters. */
00381 } dm_event_t;
00382 
00383 /**
00384  * @brief Event notification callback registered by application with the module.
00385  *
00386  * @details Event notification callback registered by application with the module when registering
00387  *          the module using \ref dm_register API.
00388  *
00389  * @param[in] p_handle   Identifies the peer for which the event is being notified.
00390  * @param[in] p_event    Identifies the event, any associated parameters and parameter length.
00391  *                       See \ref dm_events for details on event types and their significance.
00392  * @param[in,out] event_result   Provide additional information on the event. 
00393  *                      In addition to SDK error codes there is also a return value
00394  *                      indicating if maximum number of connections has been reached when connecting or bonding.
00395  *
00396  * @retval NRF_SUCCESS on success, or a failure to indicate if it could handle the event
00397  *         successfully. There is no action taken in case application returns a failure.
00398  */
00399 typedef ret_code_t (*dm_event_cb_t)(dm_handle_t const * p_handle,
00400                                     dm_event_t const  * p_event,
00401                                     ret_code_t        event_result);
00402 
00403 /**
00404  * @brief Initialization Parameters.
00405  *
00406  * @details Indicates the application parameters. Currently this only encompasses clearing
00407  *          all persistent data.
00408  */
00409 typedef struct
00410 {
00411     bool clear_persistent_data; /**< Set to true in case the module should clear all persistent data. */
00412 } dm_init_param_t;
00413 
00414 /**
00415  * @brief Application Registration Parameters.
00416  *
00417  * @details Parameters needed by the module when registering with it.
00418  */
00419 typedef struct
00420 {
00421     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. */
00422     uint8_t              service_type; /**< Bit mask identifying services that the application intends to support for all peers. */
00423     ble_gap_sec_params_t sec_param;    /**< Security parameters to be used for the application. */
00424 } dm_application_param_t;
00425 
00426 /**
00427  * @brief Defines possible security status/states.
00428  *
00429  * @details Defines possible security status/states of a link when requested by application using
00430  *          the \ref dm_security_status_req.
00431  */
00432 typedef enum
00433 {
00434     NOT_ENCRYPTED,          /**< The link is not secured. */
00435     ENCRYPTION_IN_PROGRESS, /**< Link security is being established.*/
00436     ENCRYPTED               /**< The link is secure.*/
00437 } dm_security_status_t;
00438 /** @} */
00439 
00440 /**
00441  * @defgroup dm_api Device Module APIs
00442  *
00443  * @brief This section describes APIs exposed by the module.
00444  *
00445  * @details This section describes APIs exposed by the module. The APIs have been categorized to provide
00446  *          better and specific look up for developers. Categories are:
00447  *          - Set up APIs.
00448  *          - Context Management APIs.
00449  *          - Utility APIs.
00450  *
00451  *          MSCs describe usage of these APIs.  
00452  *          See @ref dm_msc.
00453  * @{
00454  */
00455 /**
00456  * @defgroup dm_setup_api Device Module Set-up APIs
00457  *
00458  * @brief Initialization & registration APIs that are pre-requisite for all other module procedures.
00459  * @details This section describes the Module Initialization and Registration APIs needed to be set up by
00460  *          the application before device manager can start managing devices and device contexts
00461  *          for the application.
00462  *
00463  * @{
00464  */
00465 
00466 /**
00467  * @brief Module Initialization Routine.
00468  *
00469  * @details Function for initializing the module. Must called before any other APIs of the module are used.
00470  *
00471  * @param[in] p_init_param Initialization parameters.
00472  *
00473  * @retval NRF_SUCCESS On success, else an error code indicating reason for failure.
00474  *
00475  * @note It is mandatory that pstorage is initialized before initializing this module.
00476  */
00477 ret_code_t dm_init(dm_init_param_t const * p_init_param);
00478 
00479 /**
00480  * @brief Function for registering the application.
00481  *
00482  * @details This routine is used by the application to register for asynchronous events with the
00483  *          device manager. During registration the application also indicates the services that it
00484  *          intends to support on this instance. It is possible to register multiple times with the
00485  *          device manager. At least one instance shall be registered with the device manager after
00486  *          the module has been initialized.
00487  *          Maximum number of application instances device manager can support is determined
00488  *          by DM_MAX_APPLICATIONS.
00489  *
00490  *          All applications must be registered before initiating or accepting connections from the peer.     
00491  *
00492  * @param[in]  p_appl_param    Application parameters.
00493  * @param[out] p_appl_instance Application Instance Identifier in case registration is successful.
00494  *
00495  * @retval NRF_SUCCESS             On success, else an error code indicating reason for failure.
00496  * @retval NRF_ERROR_INVALID_STATE If the API is called without module initialization.
00497  * @retval NRF_ERROR_NO_MEM        If module cannot support more applications.
00498  *
00499  * @note Currently only one application instance is supported by the module.
00500  */
00501 ret_code_t dm_register(dm_application_instance_t    * p_appl_instance,
00502                        dm_application_param_t const * p_appl_param);
00503 
00504 /**
00505  * @brief Function for handling BLE events.
00506  *
00507  * @details BLE Event Handler for the module. This routine should be called from BLE stack event
00508  *          dispatcher for the module to work as expected.
00509  *
00510  * @param[in] p_ble_evt BLE stack event being dispatched to the function.
00511  *
00512  */
00513 void dm_ble_evt_handler(ble_evt_t * p_ble_evt);
00514 
00515 /** @} */
00516 
00517 
00518 /**
00519  * @defgroup dm_security_api APIs to set up or read status of security on a link.
00520  *
00521  * @brief This section describes APIs to set up Security. These APIs require that the peer is
00522  *        connected before the procedures can be requested.
00523  *
00524  * @details This group allows application to request security procedures
00525  *          or get the status of the security on a link.
00526  * @{
00527  */
00528 /**
00529  * @brief Function for requesting setting up security on a link.
00530  *
00531  * @details This API initiates security procedures with a peer device.
00532  *          @note For the GAP Central role, in case peer is not bonded, request to bond/pair is
00533  *          initiated. If it is bonded, the link is re-encrypted using the existing bond information.
00534  *          For the GAP peripheral role, a Slave security request is sent.
00535  * @details If a pairing procedure is initiated successfully, application is notified of
00536  *          @ref DM_EVT_SECURITY_SETUP_COMPLETE. A result indicating success or failure is notified along with the event.
00537  *          In case the link is re-encrypted using existing bond information, @ref DM_EVT_LINK_SECURED is
00538  *          notified to the application.
00539  *
00540  * @param[in] p_handle Identifies the link on which security is desired.
00541  *
00542  * @retval NRF_SUCCESS             On success, else an error code indicating reason for failure.
00543  * @retval NRF_ERROR_INVALID_STATE If the API is called without module initialization and/or
00544  *                                 application registration.
00545  * @retval NRF_ERROR_NULL          If p_handle is NULL.
00546  * @retval NRF_ERROR_INVALID_ADDR  If the peer is not identified by the handle provided by the application
00547  *                                 or if the peer is not connected when this procedure is requested.
00548  */
00549 ret_code_t dm_security_setup_req(dm_handle_t * p_handle);
00550 
00551 /**
00552  * @brief Function for reading the status of the security on a link.
00553  *
00554  * @details This API allows application to query status of security on a link.
00555  *
00556  * @param[in]  p_handle  Identifies the link on which security is desired.
00557  * @param[out] p_status  Pointer where security status is provided to the application.
00558  *                       See \ref dm_security_status_t for possible statuses that can be expected.
00559  *
00560  * @retval NRF_SUCCESS             Or appropriate error code indicating reason for failure.
00561  * @retval NRF_ERROR_INVALID_STATE If the API is called without module initialization and/or
00562  *                                 application registration.
00563  * @retval NRF_ERROR_NULL          If p_handle or p_status is NULL.
00564  * @retval NRF_ERROR_INVALID_ADDR  If peer is not identified by the handle provided by the application
00565  *                                 or if peer is not connected when this procedure is requested.
00566  */
00567 ret_code_t dm_security_status_req(dm_handle_t const * p_handle, dm_security_status_t * p_status);
00568 
00569 /**
00570  * @brief Function for creating the whitelist.
00571  *
00572  * @details This API allows application to create whitelist based on bonded peer devices in module
00573  *          data base.
00574  *
00575  * @param[in]  p_handle       Identifies the application requesting whitelist creation.
00576  * @param[in,out] p_whitelist Pointer where created whitelist is provided to the application.
00577  *
00578  * @note 'addr_count' and 'irk_count' fields of the structure should be populated with the maximum
00579  *       number of devices that the application wishes to request in the whitelist. 
00580  *       If the number of bonded devices is less than requested, the fields are updated with that number of devices.
00581  *       If the number of devices are more than requested, the module will populate the list
00582  *       with devices in the order the bond was established with the peer devices. Also, if this routine is
00583  *       called when a connection exists with one or more peer devices,
00584  *       those connected devices are not added to the whitelist.
00585  *
00586  * @retval NRF_SUCCESS             On success, else an error code indicating reason for failure.
00587  * @retval NRF_ERROR_INVALID_STATE If the API is called without module initialization and/or
00588  *                                 application registration.
00589  * @retval NRF_ERROR_NULL          If p_handle or p_whitelist is NULL.
00590  */
00591 ret_code_t dm_whitelist_create(dm_application_instance_t const * p_handle,
00592                                ble_gap_whitelist_t             * p_whitelist);
00593 
00594 /** @} */
00595 
00596 
00597 /**
00598  * @defgroup dm_cntxt_mgmt_api Context Management APIs
00599  *
00600  * @brief Utility APIs offered by the device manager to get information about the peer if and
00601  *        when needed.
00602  *
00603  * @details This group of API allow the application to access information that is not required to be
00604  *          maintained by the application but may be needed. Hence it is possible to get the
00605  *          information from the module instead of mapping all the information with a device
00606  *          context.
00607  * @{
00608  */
00609 
00610 ret_code_t dm_device_add(dm_handle_t               * p_handle,
00611                          dm_device_context_t const * p_context);
00612 
00613 /**
00614  * @brief Function for deleting a peer device context and all related information from the database.
00615  *
00616  * @details Delete peer device context and all related information from database. If
00617  *          this API returns NRF_SUCCESS, DM_EVT_DEVICE_CONTEXT_DELETED event is notified to the
00618  *          application. Event result notified along with the event indicates success or failure
00619  *          of this procedure.
00620  *
00621  * @param[in] p_handle Identifies the peer device to be deleted.
00622  *
00623  * @retval NRF_SUCCESS             on success, else an error code indicating reason for failure.
00624  * @retval NRF_ERROR_INVALID_STATE In the API is called without module initialization and/or
00625  *                                 application registration.
00626  * @retval NRF_ERROR_NULL          If p_handle is NULL.
00627  * @retval NRF_ERROR_INVALID_ADDR  If peer is not identified the handle provided by the application.
00628  *
00629  * @note Deleting device context results in deleting service and application context for the
00630  *       bonded device. The respective events DM_EVT_SERVICE_CONTEXT_DELETED and
00631  *       DM_EVT_APPL_CONTEXT_DELETED are not notified to the application.
00632  */
00633 ret_code_t dm_device_delete(dm_handle_t const * p_handle);
00634 
00635 /**
00636  * @brief Function for deleting all peer device context and all related information from the database.
00637  *
00638  * @details Delete peer device context and all related information from database. If
00639  *          this API returns NRF_SUCCESS, DM_EVT_DEVICE_CONTEXT_DELETED event is notified to the
00640  *          application for each device that is deleted from the data base. Event result
00641  *          notified along with the event indicates success or failure of this procedure.
00642  *
00643  * @param[in] p_handle Identifies application instance that is requesting
00644  *                     the deletion of all bonded devices.
00645  *
00646  * @retval NRF_SUCCESS             On success, else an error code indicating reason for failure.
00647  * @retval NRF_ERROR_INVALID_STATE If the API is called without module initialization and/or
00648  *                                 application registration.
00649  * @retval NRF_ERROR_NULL          If p_handle is NULL.
00650  * @retval NRF_ERROR_INVALID_ADDR  If peer is not identified the handle provided by the application.
00651  *
00652  * @note Deleting device context results in deleting both service and application context for the
00653  *       bonded device. The respective events DM_EVT_SERVICE_CONTEXT_DELETED and
00654  *       DM_EVT_APPL_CONTEXT_DELETED are not notified to the application.
00655  */
00656 ret_code_t dm_device_delete_all(dm_application_instance_t const * p_handle);
00657 
00658 /**
00659  * @brief Function for setting Service Context for a peer device identified by 'p_handle' parameter.
00660  *
00661  * @details This API allows application to Set Service Context for a peer device identified by the
00662  *          'p_handle' parameter. This API is useful when the Service Context cannot be requested
00663  *          from the SoftDevice, but needs to be assembled by the application or an another module.
00664  *          (or when service context is exchanged in an out of band way.)
00665  *          This API could also be used to trigger a storing of service context into persistent
00666  *          memory. If this is desired, a NULL pointer could be passed to the p_context.
00667  *
00668  * @param[in] p_handle  Identifies peer device for which the procedure is requested.
00669  * @param[in] p_context Service context being set. The context information includes length of
00670  *                      data and pointer to the contextual data being set. The memory pointed to by
00671  *                      the pointer to data is assumed to be resident when API is being called and
00672  *                      can be freed or reused once the set procedure is complete. Set procedure
00673  *                      completion is indicated by the event \ref DM_EVT_SERVICE_CONTEXT_STORED.
00674  *                      The Event result is notified along with the event and indicates success or failure of
00675  *                      this procedure.
00676  *
00677  * @retval NRF_SUCCESS             On success, else an error code indicating reason for failure.
00678  * @retval NRF_ERROR_INVALID_STATE If the API is called without module initialization and/or
00679  *                                 application registration.
00680  * @retval NRF_ERROR_NULL          If p_handle is NULL.
00681  * @retval NRF_ERROR_INVALID_ADDR  If the peer is not identified by the handle provided by the application.
00682  */
00683 ret_code_t dm_service_context_set(dm_handle_t const          * p_handle,
00684                                   dm_service_context_t const * p_context);
00685 
00686 /**
00687  * @brief Function for getting Service Context for a peer device identified by 'p_handle' parameter.
00688  *
00689  * @details Get Service Context for a peer device identified by the 'p_handle' parameter. If
00690  *          this API returns NRF_SUCCESS, DM_EVT_SERVICE_CONTEXT_LOADED event is notified to the
00691  *          application. The event result is notified along with the event indicates success or failure
00692  *          of this procedure.
00693  *
00694  * @param[in] p_handle  Identifies peer device for which procedure is requested.
00695  * @param[in] p_context Application context being requested. The context information includes length
00696  *                      of the data and a pointer to the data. Note that requesting a 'get'
00697  *                      of application does not need to provide memory, the pointer to data will be
00698  *                      pointing to service data and hence no data movement is involved.
00699  *
00700  * @retval NRF_SUCCESS             On success, else an error code indicating reason for failure.
00701  * @retval NRF_ERROR_INVALID_STATE In case API is called without module initialization and/or
00702  *                                 application registration.
00703  * @retval NRF_ERROR_NULL          If p_handle is NULL.
00704  * @retval NRF_ERROR_INVALID_ADDR  If the peer is not identified by the handle provided by the application.
00705  */
00706 ret_code_t dm_service_context_get(dm_handle_t const    * p_handle,
00707                                   dm_service_context_t * p_context);
00708 
00709 /**
00710  * @brief Function for deleting a Service Context for a peer device identified by the 'p_handle' parameter.
00711  *
00712  * @details This API allows application to delete a Service Context identified for a peer device
00713  *          identified by the 'p_handle' parameter. If this API returns NRF_SUCCESS,
00714  *          DM_EVT_SERVICE_CONTEXT_DELETED event is notified to the application. 
00715  *          Event result is notified along with the event and indicates success or failure of this
00716  *          procedure.
00717  *
00718  * @param[in] p_handle Identifies peer device for which procedure is requested.
00719  *
00720  * @retval NRF_SUCCESS             On success, else an error code indicating reason for failure.
00721  * @retval NRF_ERROR_INVALID_STATE If the API is called without module initialization and/or
00722  *                                 application registration.
00723  * @retval NRF_ERROR_NULL          If p_handle is NULL.
00724  * @retval NRF_ERROR_INVALID_ADDR  If the peer is not identified by the handle provided by the application.
00725  */
00726 ret_code_t dm_service_context_delete(dm_handle_t const * p_handle);
00727 
00728 /**
00729  * @brief Function for setting Application Context for a peer device identified by the 'p_handle' parameter.
00730  *
00731  * @details This application allows the setting of the application context for the peer device identified by
00732  *          the 'p_handle'. Application context is stored persistently by the module and can be
00733  *          requested by the application at any time using the \ref dm_application_context_get
00734  *          API. Note that this procedure is permitted only for bonded devices. If the
00735  *          device is not bonded, application context cannot be set. However, it is not mandatory
00736  *          that the bonded device is connected when requesting this procedure.
00737  *
00738  * @param[in] p_handle  Identifies peer device for which procedure is requested.
00739  *
00740  * @param[in] p_context Application context being set. The context information includes length of the
00741  *                      data and pointer to the contextual data being set. The memory pointed to by
00742  *                      the data pointer is assumed to be resident when API is being called and
00743  *                      can be freed or reused once the set procedure is complete. Set procedure
00744  *                      completion is notified by the event \ref DM_EVT_APPL_CONTEXT_STORED.
00745  *                      The event result is notified along with the event and indicates success or
00746  *                      failure of this procedure.
00747  *
00748  * @retval NRF_SUCCESS             On success, else an error code indicating reason for failure.
00749  * @retval NRF_ERROR_INVALID_STATE If the API is called without module initialization and/or
00750  *                                 application registration.
00751  * @retval NRF_ERROR_NULL          If p_handle and/or p_context is NULL.
00752  * @retval NRF_ERROR_INVALID_ADDR  If peer is not identified the handle provided by the application.
00753  *
00754  * @note The API returns FEATURE_NOT_ENABLED in case DEVICE_MANAGER_APP_CONTEXT_SIZE is set to zero.
00755  */
00756 ret_code_t dm_application_context_set(dm_handle_t const              * p_handle,
00757                                       dm_application_context_t const * p_context);
00758 
00759 /**
00760  * @brief Function for getting Application Context for a peer device identified by the 'p_handle' parameter.
00761  *
00762  * @details Get Application Context for a peer device identified by the 'p_handle' parameter. If
00763  *          this API returns NRF_SUCCESS, DM_EVT_APPL_CONTEXT_LOADED event is notified to the
00764  *          application. Event result notified along with the event indicates success or failure
00765  *          of this procedure.
00766  *
00767  * @param[in] p_handle  Identifies peer device for which procedure is requested.
00768  * @param[in] p_context Application context being requested. The context information includes
00769  *                      length of data and pointer to the contextual data is provided.
00770  *
00771  * @retval NRF_SUCCESS             On success, else an error code indicating reason for failure.
00772  * @retval NRF_ERROR_INVALID_STATE If the API is called without module initialization and/or
00773  *                                 application registration.
00774  * @retval NRF_ERROR_NULL          If p_handle and/or p_context is NULL.
00775  * @retval NRF_ERROR_INVALID_ADDR  If the peer is not identified by the handle provided by the application.
00776  * @retval DM_NO_APP_CONTEXT       If no application context was set that can be fetched.
00777  *
00778  * @note The API returns FEATURE_NOT_ENABLED in case DEVICE_MANAGER_APP_CONTEXT_SIZE is set to
00779  *       zero.
00780  */
00781 ret_code_t dm_application_context_get(dm_handle_t const        * p_handle,
00782                                       dm_application_context_t * p_context);
00783 
00784 /**
00785  * @brief Function for deleting Application Context for a peer device identified by the 'p_handle' parameter.
00786  *
00787  * @details Delete Application Context for a peer device identified by the 'p_handle' parameter. If
00788  *          this API returns NRF_SUCCESS, DM_EVT_APPL_CONTEXT_DELETED event is notified to the
00789  *          application. The event result notified along with the event and indicates success or failure
00790  *          of this procedure.
00791  *
00792  * @param[in] p_handle Identifies peer device for which procedure is requested.
00793  *
00794  * @retval NRF_SUCCESS             On success, else an error code indicating reason for failure.
00795  * @retval NRF_ERROR_INVALID_STATE If the API is called without module initialization and/or
00796  *                                 application registration.
00797  * @retval NRF_ERROR_NULL          If the p_handle is NULL.
00798  * @retval NRF_ERROR_INVALID_ADDR  If peer is not identified the handle provided by the application.
00799  * @retval DM_NO_APP_CONTEXT       If no application context was set that can be deleted.
00800  *
00801  * @note The API returns FEATURE_NOT_ENABLED if the DEVICE_MANAGER_APP_CONTEXT_SIZE is set to zero.
00802  */
00803 ret_code_t dm_application_context_delete(dm_handle_t const * p_handle);
00804 
00805 /** @} */
00806 
00807 
00808 /**
00809  * @defgroup utility_api Utility APIs
00810  * @{
00811  * @brief This section describes the utility APIs offered by the module.
00812  *
00813  * @details APIs defined in this section are utility or assisting/helper APIs.
00814  */
00815 /**
00816  * @brief Function for Setting/Copying Application instance to Device Manager handle.
00817  *
00818  * @param[in]  p_appl_instance Application instance to be set.
00819  * @param[out] p_handle        Device Manager handle for which the instance is to be copied.
00820  *
00821  * @retval NRF_SUCCESS             On success, else an error code indicating reason for failure.
00822  * @retval NRF_ERROR_INVALID_STATE If the API is called without module initialization and/or
00823  *                                 application registration.
00824  * @retval NRF_ERROR_NULL          If p_handle and/or p_addr is NULL.
00825  */
00826 ret_code_t dm_application_instance_set(dm_application_instance_t const * p_appl_instance,
00827                                        dm_handle_t                     * p_handle);
00828 
00829 /**
00830  * @brief Function for getting a peer's device address.
00831  *
00832  * @param[in]  p_handle Identifies the peer device whose address is requested. Can not be NULL.
00833  * @param[out] p_addr   Pointer where address is to be copied. Can not be NULL.
00834  *
00835  * @retval NRF_SUCCESS             On success, else an error code indicating reason for failure.
00836  * @retval NRF_ERROR_INVALID_STATE If the API is called without module initialization and/or
00837  *                                 application registration.
00838  * @retval NRF_ERROR_NULL          If p_handle and/or p_addr is NULL.
00839  * @retval NRF_ERROR_NOT_FOUND     If the peer could not be identified.
00840  */
00841 ret_code_t dm_peer_addr_get(dm_handle_t const * p_handle,
00842                             ble_gap_addr_t    * p_addr);
00843 
00844 /**
00845  * @brief Function for setting/updating a peer's device address.
00846  *
00847  * @param[in]  p_handle Identifies the peer device whose address is requested to be set/updated.
00848  * @param[out] p_addr   Address to be set/updated.
00849  *
00850  * @retval NRF_SUCCESS             On success, else an error code indicating reason for failure.
00851  * @retval NRF_ERROR_INVALID_STATE If the API is called without module initialization and/or
00852  *                                 application registration.
00853  * @retval NRF_ERROR_NULL          If p_handle and/or p_addr is NULL.
00854  * @retval NRF_ERROR_INVALID_ADDR  If the peer is not identified by the handle provided by the application.
00855  * @retval NRF_ERROR_INVALID_PARAM If this procedure is requested while connected to the peer or if the address
00856  *                                 type was set to BLE_GAP_ADDR_TYPE_RANDOM_PRIVATE_RESOLVABLE.
00857  *
00858  * @note Setting or updating a peer's device address is permitted 
00859  *       only for a peer that is bonded and disconnected.
00860  * @note Updated address is reflected only after DM_EVT_DEVICE_CONTEXT_STORED is notified to the
00861  *       application for this bonded device instance. In order to avoid abnormal behaviour, it is
00862  *       recommended to not invite/initiate connections on the updated address unless this event
00863  *       has been notified.
00864  */
00865 ret_code_t dm_peer_addr_set(dm_handle_t const    * p_handle,
00866                             ble_gap_addr_t const * p_addr);
00867 
00868 /**
00869  * @brief Function for initializing Device Manager handle.
00870  *
00871  * @param[in] p_handle Device Manager handle to be initialized.
00872  *
00873  * @retval NRF_SUCCESS    On success.
00874  * @retval NRF_ERROR_NULL If p_handle is NULL.
00875  *
00876  * @note This routine is permitted before initialization of the module.
00877  */
00878 ret_code_t dm_handle_initialize(dm_handle_t * p_handle);
00879 
00880 /**
00881  * @brief Function for getting distributed keys for a device.
00882  *
00883  * @param[in]  p_handle   Device Manager handle identifying the peer.
00884  * @param[out] p_key_dist Pointer to distributed keys.
00885  *
00886  * @retval NRF_SUCCESS             On success, else an error code indicating reason for failure.
00887  * @retval NRF_ERROR_INVALID_STATE If the API is called without module initialization and/or
00888  *                                 application registration.
00889  * @retval NRF_ERROR_NULL          If the p_handle and/or p_key_dist pointer is NULL.
00890  * @retval NRF_ERROR_INVALID_ADDR  If the peer is not identified by the handle provided by the application.
00891  */
00892 ret_code_t dm_distributed_keys_get(dm_handle_t const * p_handle,
00893                                    dm_sec_keyset_t   * p_key_dist);
00894 
00895 /**
00896  * @brief Function for getting the corresponding dm_handle_t based on the connection handle.
00897  *
00898  * @param[in]     conn_handle Connection handle as provided by the SoftDevice.
00899  * @param[in,out] p_handle    Pointer to the p_handle containg the application instance for the 
00900  *                            registered application. If the application instance is valid then 
00901  *                            the p_handle will be filled with requested data.
00902  *
00903  * @retval NRF_SUCCESS          On success, else an error code indicating reason for failure.
00904  * @retval NRF_ERROR_NULL       If the p_handle pointer is NULL.
00905  * @retval NRF_ERROR_NOT_FOUND  If no p_handle is found for the provided connection handle.
00906  */
00907 ret_code_t dm_handle_get(uint16_t conn_handle, dm_handle_t * p_handle);
00908 
00909 #ifdef __cplusplus
00910 }
00911 #endif
00912 
00913 /** @} */
00914 /** @} */
00915 /** @} */
00916 #endif // DEVICE_MANAGER_H__