ble_gap.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  *   4. This software must only be used in a processor manufactured by Nordic
00020  *   Semiconductor ASA, or in a processor manufactured by a third party that
00021  *   is used in combination with a processor manufactured by Nordic Semiconductor.
00022  *
00023  *
00024  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
00025  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
00026  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
00027  * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
00028  * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
00029  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
00030  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
00031  * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
00032  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
00033  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00034  *
00035  */
00036 
00037 /**
00038   @addtogroup BLE_GAP Generic Access Profile (GAP)
00039   @{
00040   @brief Definitions and prototypes for the GAP interface.
00041  */
00042 
00043 #ifndef BLE_GAP_H__
00044 #define BLE_GAP_H__
00045 
00046 #include "ble_types.h"
00047 #include "ble_ranges.h"
00048 #include "nrf_svc.h"
00049 
00050 #ifdef __cplusplus
00051 extern "C" {
00052 #endif
00053 
00054 /**@addtogroup BLE_GAP_ENUMERATIONS Enumerations
00055  * @{ */
00056 
00057 /**@brief GAP API SVC numbers.
00058  */
00059 enum BLE_GAP_SVCS
00060 {
00061   SD_BLE_GAP_ADDRESS_SET  = BLE_GAP_SVC_BASE,  /**< Set own Bluetooth Address. */
00062   SD_BLE_GAP_ADDRESS_GET,                      /**< Get own Bluetooth Address. */
00063   SD_BLE_GAP_ADV_DATA_SET,                     /**< Set Advertising Data. */
00064   SD_BLE_GAP_ADV_START,                        /**< Start Advertising. */
00065   SD_BLE_GAP_ADV_STOP,                         /**< Stop Advertising. */
00066   SD_BLE_GAP_CONN_PARAM_UPDATE,                /**< Connection Parameter Update. */
00067   SD_BLE_GAP_DISCONNECT,                       /**< Disconnect. */
00068   SD_BLE_GAP_TX_POWER_SET,                     /**< Set TX Power. */
00069   SD_BLE_GAP_APPEARANCE_SET,                   /**< Set Appearance. */
00070   SD_BLE_GAP_APPEARANCE_GET,                   /**< Get Appearance. */
00071   SD_BLE_GAP_PPCP_SET,                         /**< Set PPCP. */
00072   SD_BLE_GAP_PPCP_GET,                         /**< Get PPCP. */
00073   SD_BLE_GAP_DEVICE_NAME_SET,                  /**< Set Device Name. */
00074   SD_BLE_GAP_DEVICE_NAME_GET,                  /**< Get Device Name. */
00075   SD_BLE_GAP_AUTHENTICATE,                     /**< Initiate Pairing/Bonding. */
00076   SD_BLE_GAP_SEC_PARAMS_REPLY,                 /**< Reply with Security Parameters. */
00077   SD_BLE_GAP_AUTH_KEY_REPLY,                   /**< Reply with an authentication key. */
00078   SD_BLE_GAP_LESC_DHKEY_REPLY,                 /**< Reply with an LE Secure Connections DHKey. */
00079   SD_BLE_GAP_KEYPRESS_NOTIFY,                  /**< Notify of a keypress during an authentication procedure. */
00080   SD_BLE_GAP_LESC_OOB_DATA_GET,                /**< Get the local LE Secure Connections OOB data. */
00081   SD_BLE_GAP_LESC_OOB_DATA_SET,                /**< Set the remote LE Secure Connections OOB data. */
00082   SD_BLE_GAP_ENCRYPT,                          /**< Initiate encryption procedure. */
00083   SD_BLE_GAP_SEC_INFO_REPLY,                   /**< Reply with Security Information. */
00084   SD_BLE_GAP_CONN_SEC_GET,                     /**< Obtain connection security level. */
00085   SD_BLE_GAP_RSSI_START,                       /**< Start reporting of changes in RSSI. */
00086   SD_BLE_GAP_RSSI_STOP,                        /**< Stop reporting of changes in RSSI. */
00087   SD_BLE_GAP_SCAN_START,                       /**< Start Scanning. */
00088   SD_BLE_GAP_SCAN_STOP,                        /**< Stop Scanning. */
00089   SD_BLE_GAP_CONNECT,                          /**< Connect. */
00090   SD_BLE_GAP_CONNECT_CANCEL,                   /**< Cancel ongoing connection procedure. */
00091   SD_BLE_GAP_RSSI_GET,                         /**< Get the last RSSI sample. */
00092 };
00093 
00094 /**@brief GAP Event IDs.
00095  * IDs that uniquely identify an event coming from the stack to the application.
00096  */
00097 enum BLE_GAP_EVTS
00098 {
00099   BLE_GAP_EVT_CONNECTED  = BLE_GAP_EVT_BASE,    /**< Connection established.                         \n See @ref ble_gap_evt_connected_t.            */
00100   BLE_GAP_EVT_DISCONNECTED,                     /**< Disconnected from peer.                         \n See @ref ble_gap_evt_disconnected_t.         */
00101   BLE_GAP_EVT_CONN_PARAM_UPDATE,                /**< Connection Parameters updated.                  \n See @ref ble_gap_evt_conn_param_update_t.    */
00102   BLE_GAP_EVT_SEC_PARAMS_REQUEST,               /**< Request to provide security parameters.         \n Reply with @ref sd_ble_gap_sec_params_reply.  \n See @ref ble_gap_evt_sec_params_request_t. */
00103   BLE_GAP_EVT_SEC_INFO_REQUEST,                 /**< Request to provide security information.        \n Reply with @ref sd_ble_gap_sec_info_reply.    \n See @ref ble_gap_evt_sec_info_request_t.   */
00104   BLE_GAP_EVT_PASSKEY_DISPLAY,                  /**< Request to display a passkey to the user.       \n In LESC Numeric Comparison, reply with @ref sd_ble_gap_auth_key_reply. \n See @ref ble_gap_evt_passkey_display_t. */
00105   BLE_GAP_EVT_KEY_PRESSED,                      /**< Notification of a keypress on the remote device.\n See @ref ble_gap_evt_key_pressed_t           */
00106   BLE_GAP_EVT_AUTH_KEY_REQUEST,                 /**< Request to provide an authentication key.       \n Reply with @ref sd_ble_gap_auth_key_reply.    \n See @ref ble_gap_evt_auth_key_request_t.   */
00107   BLE_GAP_EVT_LESC_DHKEY_REQUEST,               /**< Request to calculate an LE Secure Connections DHKey. \n Reply with @ref sd_ble_gap_lesc_dhkey_reply.  \n See @ref ble_gap_evt_lesc_dhkey_request_t */
00108   BLE_GAP_EVT_AUTH_STATUS,                      /**< Authentication procedure completed with status. \n See @ref ble_gap_evt_auth_status_t.          */
00109   BLE_GAP_EVT_CONN_SEC_UPDATE,                  /**< Connection security updated.                    \n See @ref ble_gap_evt_conn_sec_update_t.      */
00110   BLE_GAP_EVT_TIMEOUT,                          /**< Timeout expired.                                \n See @ref ble_gap_evt_timeout_t.              */
00111   BLE_GAP_EVT_RSSI_CHANGED,                     /**< RSSI report.                                    \n See @ref ble_gap_evt_rssi_changed_t.         */
00112   BLE_GAP_EVT_ADV_REPORT,                       /**< Advertising report.                             \n See @ref ble_gap_evt_adv_report_t.           */
00113   BLE_GAP_EVT_SEC_REQUEST,                      /**< Security Request.                               \n See @ref ble_gap_evt_sec_request_t.          */
00114   BLE_GAP_EVT_CONN_PARAM_UPDATE_REQUEST,        /**< Connection Parameter Update Request.            \n Reply with @ref sd_ble_gap_conn_param_update. \n See @ref ble_gap_evt_conn_param_update_request_t. */
00115   BLE_GAP_EVT_SCAN_REQ_REPORT,                  /**< Scan request report.                            \n See @ref ble_gap_evt_scan_req_report_t.      */
00116 };
00117 
00118 /**@brief GAP Option IDs.
00119  * IDs that uniquely identify a GAP option.
00120  */
00121 enum BLE_GAP_OPTS
00122 {
00123   BLE_GAP_OPT_CH_MAP  = BLE_GAP_OPT_BASE,       /**< Channel Map. @ref ble_gap_opt_ch_map_t  */
00124   BLE_GAP_OPT_LOCAL_CONN_LATENCY,               /**< Local connection latency. @ref ble_gap_opt_local_conn_latency_t */
00125   BLE_GAP_OPT_PASSKEY,                          /**< Set passkey. @ref ble_gap_opt_passkey_t */
00126   BLE_GAP_OPT_PRIVACY,                          /**< Custom privacy. @ref ble_gap_opt_privacy_t */
00127   BLE_GAP_OPT_SCAN_REQ_REPORT,                  /**< Scan request report. @ref ble_gap_opt_scan_req_report_t */
00128   BLE_GAP_OPT_COMPAT_MODE                       /**< Compatibility mode. @ref ble_gap_opt_compat_mode_t */
00129 };
00130 
00131 /** @} */
00132 
00133 /**@addtogroup BLE_GAP_DEFINES Defines
00134  * @{ */
00135 
00136 /**@defgroup BLE_ERRORS_GAP SVC return values specific to GAP
00137  * @{ */
00138 #define BLE_ERROR_GAP_UUID_LIST_MISMATCH            (NRF_GAP_ERR_BASE + 0x000)  /**< UUID list does not contain an integral number of UUIDs. */
00139 #define BLE_ERROR_GAP_DISCOVERABLE_WITH_WHITELIST   (NRF_GAP_ERR_BASE + 0x001)  /**< Use of Whitelist not permitted with discoverable advertising. */
00140 #define BLE_ERROR_GAP_INVALID_BLE_ADDR              (NRF_GAP_ERR_BASE + 0x002)  /**< The upper two bits of the address do not correspond to the specified address type. */
00141 #define BLE_ERROR_GAP_WHITELIST_IN_USE              (NRF_GAP_ERR_BASE + 0x003)  /**< Attempt to overwrite the whitelist while already in use by another operation. */
00142 /**@} */
00143 
00144 
00145 /**@defgroup BLE_GAP_ROLES GAP Roles
00146  * @note Not explicitly used in peripheral API, but will be relevant for central API.
00147  * @{ */
00148 #define BLE_GAP_ROLE_INVALID     0x0            /**< Invalid Role. */
00149 #define BLE_GAP_ROLE_PERIPH      0x1            /**< Peripheral Role. */
00150 #define BLE_GAP_ROLE_CENTRAL     0x2            /**< Central Role. */
00151 /**@} */
00152 
00153 
00154 /**@defgroup BLE_GAP_TIMEOUT_SOURCES GAP Timeout sources
00155  * @{ */
00156 #define BLE_GAP_TIMEOUT_SRC_ADVERTISING                0x00 /**< Advertising timeout. */
00157 #define BLE_GAP_TIMEOUT_SRC_SECURITY_REQUEST           0x01 /**< Security request timeout. */
00158 #define BLE_GAP_TIMEOUT_SRC_SCAN                       0x02 /**< Scanning timeout. */
00159 #define BLE_GAP_TIMEOUT_SRC_CONN                       0x03 /**< Connection timeout. */
00160 /**@} */
00161 
00162 
00163 /**@defgroup BLE_GAP_ADDR_TYPES GAP Address types
00164  * @{ */
00165 #define BLE_GAP_ADDR_TYPE_PUBLIC                        0x00 /**< Public address. */
00166 #define BLE_GAP_ADDR_TYPE_RANDOM_STATIC                 0x01 /**< Random Static address. */
00167 #define BLE_GAP_ADDR_TYPE_RANDOM_PRIVATE_RESOLVABLE     0x02 /**< Private Resolvable address. */
00168 #define BLE_GAP_ADDR_TYPE_RANDOM_PRIVATE_NON_RESOLVABLE 0x03 /**< Private Non-Resolvable address. */
00169 /**@} */
00170 
00171 /**@defgroup BLE_GAP_ADDR_CYCLE_MODES GAP Address cycle modes
00172  * @{ */
00173 #define BLE_GAP_ADDR_CYCLE_MODE_NONE      0x00 /**< Set addresses directly, no automatic address cycling. */
00174 #define BLE_GAP_ADDR_CYCLE_MODE_AUTO      0x01 /**< Automatically generate and update private addresses. */
00175 /** @} */
00176 
00177 /**@brief The default interval in seconds at which a private address is refreshed when address cycle mode is @ref BLE_GAP_ADDR_CYCLE_MODE_AUTO.  */
00178 #define BLE_GAP_DEFAULT_PRIVATE_ADDR_CYCLE_INTERVAL_S (60 * 15)
00179 
00180 /** @brief BLE address length. */
00181 #define BLE_GAP_ADDR_LEN            6
00182 
00183 
00184 /**@defgroup BLE_GAP_AD_TYPE_DEFINITIONS GAP Advertising and Scan Response Data format
00185  * @note Found at https://www.bluetooth.org/Technical/AssignedNumbers/generic_access_profile.htm
00186  * @{ */
00187 #define BLE_GAP_AD_TYPE_FLAGS                               0x01 /**< Flags for discoverability. */
00188 #define BLE_GAP_AD_TYPE_16BIT_SERVICE_UUID_MORE_AVAILABLE   0x02 /**< Partial list of 16 bit service UUIDs. */
00189 #define BLE_GAP_AD_TYPE_16BIT_SERVICE_UUID_COMPLETE         0x03 /**< Complete list of 16 bit service UUIDs. */
00190 #define BLE_GAP_AD_TYPE_32BIT_SERVICE_UUID_MORE_AVAILABLE   0x04 /**< Partial list of 32 bit service UUIDs. */
00191 #define BLE_GAP_AD_TYPE_32BIT_SERVICE_UUID_COMPLETE         0x05 /**< Complete list of 32 bit service UUIDs. */
00192 #define BLE_GAP_AD_TYPE_128BIT_SERVICE_UUID_MORE_AVAILABLE  0x06 /**< Partial list of 128 bit service UUIDs. */
00193 #define BLE_GAP_AD_TYPE_128BIT_SERVICE_UUID_COMPLETE        0x07 /**< Complete list of 128 bit service UUIDs. */
00194 #define BLE_GAP_AD_TYPE_SHORT_LOCAL_NAME                    0x08 /**< Short local device name. */
00195 #define BLE_GAP_AD_TYPE_COMPLETE_LOCAL_NAME                 0x09 /**< Complete local device name. */
00196 #define BLE_GAP_AD_TYPE_TX_POWER_LEVEL                      0x0A /**< Transmit power level. */
00197 #define BLE_GAP_AD_TYPE_CLASS_OF_DEVICE                     0x0D /**< Class of device. */
00198 #define BLE_GAP_AD_TYPE_SIMPLE_PAIRING_HASH_C               0x0E /**< Simple Pairing Hash C. */
00199 #define BLE_GAP_AD_TYPE_SIMPLE_PAIRING_RANDOMIZER_R         0x0F /**< Simple Pairing Randomizer R. */
00200 #define BLE_GAP_AD_TYPE_SECURITY_MANAGER_TK_VALUE           0x10 /**< Security Manager TK Value. */
00201 #define BLE_GAP_AD_TYPE_SECURITY_MANAGER_OOB_FLAGS          0x11 /**< Security Manager Out Of Band Flags. */
00202 #define BLE_GAP_AD_TYPE_SLAVE_CONNECTION_INTERVAL_RANGE     0x12 /**< Slave Connection Interval Range. */
00203 #define BLE_GAP_AD_TYPE_SOLICITED_SERVICE_UUIDS_16BIT       0x14 /**< List of 16-bit Service Solicitation UUIDs. */
00204 #define BLE_GAP_AD_TYPE_SOLICITED_SERVICE_UUIDS_128BIT      0x15 /**< List of 128-bit Service Solicitation UUIDs. */
00205 #define BLE_GAP_AD_TYPE_SERVICE_DATA                        0x16 /**< Service Data - 16-bit UUID. */
00206 #define BLE_GAP_AD_TYPE_PUBLIC_TARGET_ADDRESS               0x17 /**< Public Target Address. */
00207 #define BLE_GAP_AD_TYPE_RANDOM_TARGET_ADDRESS               0x18 /**< Random Target Address. */
00208 #define BLE_GAP_AD_TYPE_APPEARANCE                          0x19 /**< Appearance. */
00209 #define BLE_GAP_AD_TYPE_ADVERTISING_INTERVAL                0x1A /**< Advertising Interval. */
00210 #define BLE_GAP_AD_TYPE_LE_BLUETOOTH_DEVICE_ADDRESS         0x1B /**< LE Bluetooth Device Address. */
00211 #define BLE_GAP_AD_TYPE_LE_ROLE                             0x1C /**< LE Role. */
00212 #define BLE_GAP_AD_TYPE_SIMPLE_PAIRING_HASH_C256            0x1D /**< Simple Pairing Hash C-256. */
00213 #define BLE_GAP_AD_TYPE_SIMPLE_PAIRING_RANDOMIZER_R256      0x1E /**< Simple Pairing Randomizer R-256. */
00214 #define BLE_GAP_AD_TYPE_SERVICE_DATA_32BIT_UUID             0x20 /**< Service Data - 32-bit UUID. */
00215 #define BLE_GAP_AD_TYPE_SERVICE_DATA_128BIT_UUID            0x21 /**< Service Data - 128-bit UUID. */
00216 #define BLE_GAP_AD_TYPE_URI                                 0x24 /**< URI */
00217 #define BLE_GAP_AD_TYPE_3D_INFORMATION_DATA                 0x3D /**< 3D Information Data. */
00218 #define BLE_GAP_AD_TYPE_MANUFACTURER_SPECIFIC_DATA          0xFF /**< Manufacturer Specific Data. */
00219 /**@} */
00220 
00221 
00222 /**@defgroup BLE_GAP_ADV_FLAGS GAP Advertisement Flags
00223  * @{ */
00224 #define BLE_GAP_ADV_FLAG_LE_LIMITED_DISC_MODE         (0x01)   /**< LE Limited Discoverable Mode. */
00225 #define BLE_GAP_ADV_FLAG_LE_GENERAL_DISC_MODE         (0x02)   /**< LE General Discoverable Mode. */
00226 #define BLE_GAP_ADV_FLAG_BR_EDR_NOT_SUPPORTED         (0x04)   /**< BR/EDR not supported. */
00227 #define BLE_GAP_ADV_FLAG_LE_BR_EDR_CONTROLLER         (0x08)   /**< Simultaneous LE and BR/EDR, Controller. */
00228 #define BLE_GAP_ADV_FLAG_LE_BR_EDR_HOST               (0x10)   /**< Simultaneous LE and BR/EDR, Host. */
00229 #define BLE_GAP_ADV_FLAGS_LE_ONLY_LIMITED_DISC_MODE   (BLE_GAP_ADV_FLAG_LE_LIMITED_DISC_MODE | BLE_GAP_ADV_FLAG_BR_EDR_NOT_SUPPORTED)   /**< LE Limited Discoverable Mode, BR/EDR not supported. */
00230 #define BLE_GAP_ADV_FLAGS_LE_ONLY_GENERAL_DISC_MODE   (BLE_GAP_ADV_FLAG_LE_GENERAL_DISC_MODE | BLE_GAP_ADV_FLAG_BR_EDR_NOT_SUPPORTED)   /**< LE General Discoverable Mode, BR/EDR not supported. */
00231 /**@} */
00232 
00233 
00234 /**@defgroup BLE_GAP_ADV_INTERVALS GAP Advertising interval max and min
00235  * @{ */
00236 #define BLE_GAP_ADV_INTERVAL_MIN        0x0020 /**< Minimum Advertising interval in 625 us units, i.e. 20 ms. */
00237 #define BLE_GAP_ADV_NONCON_INTERVAL_MIN 0x00A0 /**< Minimum Advertising interval in 625 us units for non connectable mode, i.e. 100 ms. */
00238 #define BLE_GAP_ADV_INTERVAL_MAX        0x4000 /**< Maximum Advertising interval in 625 us units, i.e. 10.24 s. */
00239  /**@}  */
00240 
00241 
00242 /**@defgroup BLE_GAP_SCAN_INTERVALS GAP Scan interval max and min
00243  * @{ */
00244 #define BLE_GAP_SCAN_INTERVAL_MIN       0x0004 /**< Minimum Scan interval in 625 us units, i.e. 2.5 ms. */
00245 #define BLE_GAP_SCAN_INTERVAL_MAX       0x4000 /**< Maximum Scan interval in 625 us units, i.e. 10.24 s. */
00246  /** @}  */
00247 
00248 
00249 /**@defgroup BLE_GAP_SCAN_WINDOW GAP Scan window max and min
00250  * @{ */
00251 #define BLE_GAP_SCAN_WINDOW_MIN         0x0004 /**< Minimum Scan window in 625 us units, i.e. 2.5 ms. */
00252 #define BLE_GAP_SCAN_WINDOW_MAX         0x4000 /**< Maximum Scan window in 625 us units, i.e. 10.24 s. */
00253  /** @}  */
00254 
00255 
00256 /**@defgroup BLE_GAP_SCAN_TIMEOUT GAP Scan timeout max and min
00257  * @{ */
00258 #define BLE_GAP_SCAN_TIMEOUT_MIN        0x0001 /**< Minimum Scan timeout in seconds. */
00259 #define BLE_GAP_SCAN_TIMEOUT_MAX        0xFFFF /**< Maximum Scan timeout in seconds. */
00260  /** @}  */
00261 
00262 
00263 /**@brief Maximum size of advertising data in octets. */
00264 #define  BLE_GAP_ADV_MAX_SIZE           31
00265 
00266 
00267 /**@defgroup BLE_GAP_ADV_TYPES GAP Advertising types
00268  * @{ */
00269 #define BLE_GAP_ADV_TYPE_ADV_IND          0x00   /**< Connectable undirected. */
00270 #define BLE_GAP_ADV_TYPE_ADV_DIRECT_IND   0x01   /**< Connectable directed. */
00271 #define BLE_GAP_ADV_TYPE_ADV_SCAN_IND     0x02   /**< Scannable undirected. */
00272 #define BLE_GAP_ADV_TYPE_ADV_NONCONN_IND  0x03   /**< Non connectable undirected. */
00273 /**@} */
00274 
00275 
00276 /**@defgroup BLE_GAP_ADV_FILTER_POLICIES GAP Advertising filter policies
00277  * @{ */
00278 #define BLE_GAP_ADV_FP_ANY                0x00   /**< Allow scan requests and connect requests from any device. */
00279 #define BLE_GAP_ADV_FP_FILTER_SCANREQ     0x01   /**< Filter scan requests with whitelist. */
00280 #define BLE_GAP_ADV_FP_FILTER_CONNREQ     0x02   /**< Filter connect requests with whitelist. */
00281 #define BLE_GAP_ADV_FP_FILTER_BOTH        0x03   /**< Filter both scan and connect requests with whitelist. */
00282 /**@} */
00283 
00284 
00285 /**@defgroup BLE_GAP_ADV_TIMEOUT_VALUES GAP Advertising timeout values
00286  * @{ */
00287 #define BLE_GAP_ADV_TIMEOUT_LIMITED_MAX      180 /**< Maximum advertising time in limited discoverable mode (TGAP(lim_adv_timeout) = 180s). */
00288 #define BLE_GAP_ADV_TIMEOUT_GENERAL_UNLIMITED  0 /**< Unlimited advertising in general discoverable mode. */
00289 /**@} */
00290 
00291 
00292 /**@defgroup BLE_GAP_DISC_MODES GAP Discovery modes
00293  * @{ */
00294 #define BLE_GAP_DISC_MODE_NOT_DISCOVERABLE  0x00   /**< Not discoverable discovery Mode. */
00295 #define BLE_GAP_DISC_MODE_LIMITED           0x01   /**< Limited Discovery Mode. */
00296 #define BLE_GAP_DISC_MODE_GENERAL           0x02   /**< General Discovery Mode. */
00297 /**@} */
00298 
00299 /**@defgroup BLE_GAP_IO_CAPS GAP IO Capabilities
00300  * @{ */
00301 #define BLE_GAP_IO_CAPS_DISPLAY_ONLY      0x00   /**< Display Only. */
00302 #define BLE_GAP_IO_CAPS_DISPLAY_YESNO     0x01   /**< Display and Yes/No entry. */
00303 #define BLE_GAP_IO_CAPS_KEYBOARD_ONLY     0x02   /**< Keyboard Only. */
00304 #define BLE_GAP_IO_CAPS_NONE              0x03   /**< No I/O capabilities. */
00305 #define BLE_GAP_IO_CAPS_KEYBOARD_DISPLAY  0x04   /**< Keyboard and Display. */
00306 /**@} */
00307 
00308 /**@defgroup BLE_GAP_AUTH_KEY_TYPES GAP Authentication Key Types
00309  * @{ */
00310 #define BLE_GAP_AUTH_KEY_TYPE_NONE        0x00   /**< No key (may be used to reject). */
00311 #define BLE_GAP_AUTH_KEY_TYPE_PASSKEY     0x01   /**< 6-digit Passkey. */
00312 #define BLE_GAP_AUTH_KEY_TYPE_OOB         0x02   /**< Out Of Band data. */
00313 /**@} */
00314 
00315 /**@defgroup BLE_GAP_KP_NOT_TYPES GAP Keypress Notification Types
00316  * @{ */
00317 #define BLE_GAP_KP_NOT_TYPE_PASSKEY_START       0x00   /**< Passkey entry started. */
00318 #define BLE_GAP_KP_NOT_TYPE_PASSKEY_DIGIT_IN    0x01   /**< Passkey digit entered. */
00319 #define BLE_GAP_KP_NOT_TYPE_PASSKEY_DIGIT_OUT   0x02   /**< Passkey digit erased. */
00320 #define BLE_GAP_KP_NOT_TYPE_PASSKEY_CLEAR       0x03   /**< Passkey cleared. */
00321 #define BLE_GAP_KP_NOT_TYPE_PASSKEY_END         0x04   /**< Passkey entry completed. */
00322 /**@} */
00323 
00324 /**@defgroup BLE_GAP_SEC_STATUS GAP Security status
00325  * @{ */
00326 #define BLE_GAP_SEC_STATUS_SUCCESS                0x00  /**< Procedure completed with success. */
00327 #define BLE_GAP_SEC_STATUS_TIMEOUT                0x01  /**< Procedure timed out. */
00328 #define BLE_GAP_SEC_STATUS_PDU_INVALID            0x02  /**< Invalid PDU received. */
00329 #define BLE_GAP_SEC_STATUS_RFU_RANGE1_BEGIN       0x03  /**< Reserved for Future Use range #1 begin. */
00330 #define BLE_GAP_SEC_STATUS_RFU_RANGE1_END         0x80  /**< Reserved for Future Use range #1 end. */
00331 #define BLE_GAP_SEC_STATUS_PASSKEY_ENTRY_FAILED   0x81  /**< Passkey entry failed (user cancelled or other). */
00332 #define BLE_GAP_SEC_STATUS_OOB_NOT_AVAILABLE      0x82  /**< Out of Band Key not available. */
00333 #define BLE_GAP_SEC_STATUS_AUTH_REQ               0x83  /**< Authentication requirements not met. */
00334 #define BLE_GAP_SEC_STATUS_CONFIRM_VALUE          0x84  /**< Confirm value failed. */
00335 #define BLE_GAP_SEC_STATUS_PAIRING_NOT_SUPP       0x85  /**< Pairing not supported.  */
00336 #define BLE_GAP_SEC_STATUS_ENC_KEY_SIZE           0x86  /**< Encryption key size. */
00337 #define BLE_GAP_SEC_STATUS_SMP_CMD_UNSUPPORTED    0x87  /**< Unsupported SMP command. */
00338 #define BLE_GAP_SEC_STATUS_UNSPECIFIED            0x88  /**< Unspecified reason. */
00339 #define BLE_GAP_SEC_STATUS_REPEATED_ATTEMPTS      0x89  /**< Too little time elapsed since last attempt. */
00340 #define BLE_GAP_SEC_STATUS_INVALID_PARAMS         0x8A  /**< Invalid parameters. */
00341 #define BLE_GAP_SEC_STATUS_DHKEY_FAILURE          0x8B  /**< DHKey check failure. */
00342 #define BLE_GAP_SEC_STATUS_NUM_COMP_FAILURE       0x8C  /**< Numeric Comparison failure. */
00343 #define BLE_GAP_SEC_STATUS_BR_EDR_IN_PROG         0x8D  /**< BR/EDR pairing in progress. */
00344 #define BLE_GAP_SEC_STATUS_X_TRANS_KEY_DISALLOWED 0x8E  /**< BR/EDR Link Key cannot be used for LE keys. */
00345 #define BLE_GAP_SEC_STATUS_RFU_RANGE2_BEGIN       0x8F  /**< Reserved for Future Use range #2 begin. */
00346 #define BLE_GAP_SEC_STATUS_RFU_RANGE2_END         0xFF  /**< Reserved for Future Use range #2 end. */
00347 /**@} */
00348 
00349 /**@defgroup BLE_GAP_SEC_STATUS_SOURCES GAP Security status sources
00350  * @{ */
00351 #define BLE_GAP_SEC_STATUS_SOURCE_LOCAL           0x00  /**< Local failure. */
00352 #define BLE_GAP_SEC_STATUS_SOURCE_REMOTE          0x01  /**< Remote failure. */
00353 /**@} */
00354 
00355 /**@defgroup BLE_GAP_CP_LIMITS GAP Connection Parameters Limits
00356  * @{ */
00357 #define BLE_GAP_CP_MIN_CONN_INTVL_NONE           0xFFFF  /**< No new minimum connection interval specified in connect parameters. */
00358 #define BLE_GAP_CP_MIN_CONN_INTVL_MIN            0x0006  /**< Lowest minimum connection interval permitted, in units of 1.25 ms, i.e. 7.5 ms. */
00359 #define BLE_GAP_CP_MIN_CONN_INTVL_MAX            0x0C80  /**< Highest minimum connection interval permitted, in units of 1.25 ms, i.e. 4 s. */
00360 #define BLE_GAP_CP_MAX_CONN_INTVL_NONE           0xFFFF  /**< No new maximum connection interval specified in connect parameters. */
00361 #define BLE_GAP_CP_MAX_CONN_INTVL_MIN            0x0006  /**< Lowest maximum connection interval permitted, in units of 1.25 ms, i.e. 7.5 ms. */
00362 #define BLE_GAP_CP_MAX_CONN_INTVL_MAX            0x0C80  /**< Highest maximum connection interval permitted, in units of 1.25 ms, i.e. 4 s. */
00363 #define BLE_GAP_CP_SLAVE_LATENCY_MAX             0x01F3  /**< Highest slave latency permitted, in connection events. */
00364 #define BLE_GAP_CP_CONN_SUP_TIMEOUT_NONE         0xFFFF  /**< No new supervision timeout specified in connect parameters. */
00365 #define BLE_GAP_CP_CONN_SUP_TIMEOUT_MIN          0x000A  /**< Lowest supervision timeout permitted, in units of 10 ms, i.e. 100 ms. */
00366 #define BLE_GAP_CP_CONN_SUP_TIMEOUT_MAX          0x0C80  /**< Highest supervision timeout permitted, in units of 10 ms, i.e. 32 s. */
00367 /**@} */
00368 
00369 
00370 /**@brief GAP device name maximum length. */
00371 #define BLE_GAP_DEVNAME_MAX_LEN           31
00372 
00373 /**@brief Disable RSSI events for connections */
00374 #define BLE_GAP_RSSI_THRESHOLD_INVALID    0xFF
00375 
00376 /**@defgroup BLE_GAP_CONN_SEC_MODE_SET_MACROS GAP attribute security requirement setters
00377  *
00378  * See @ref ble_gap_conn_sec_mode_t.
00379  * @{ */
00380 /**@brief Set sec_mode pointed to by ptr to have no access rights.*/
00381 #define BLE_GAP_CONN_SEC_MODE_SET_NO_ACCESS(ptr)          do {(ptr)->sm = 0; (ptr)->lv = 0;} while(0)
00382 /**@brief Set sec_mode pointed to by ptr to require no protection, open link.*/
00383 #define BLE_GAP_CONN_SEC_MODE_SET_OPEN(ptr)               do {(ptr)->sm = 1; (ptr)->lv = 1;} while(0)
00384 /**@brief Set sec_mode pointed to by ptr to require encryption, but no MITM protection.*/
00385 #define BLE_GAP_CONN_SEC_MODE_SET_ENC_NO_MITM(ptr)        do {(ptr)->sm = 1; (ptr)->lv = 2;} while(0)
00386 /**@brief Set sec_mode pointed to by ptr to require encryption and MITM protection.*/
00387 #define BLE_GAP_CONN_SEC_MODE_SET_ENC_WITH_MITM(ptr)      do {(ptr)->sm = 1; (ptr)->lv = 3;} while(0)
00388 /**@brief Set sec_mode pointed to by ptr to require LESC encryption and MITM protection.*/
00389 #define BLE_GAP_CONN_SEC_MODE_SET_LESC_ENC_WITH_MITM(ptr) do {(ptr)->sm = 1; (ptr)->lv = 4;} while(0)
00390 /**@brief Set sec_mode pointed to by ptr to require signing or encryption, no MITM protection needed.*/
00391 #define BLE_GAP_CONN_SEC_MODE_SET_SIGNED_NO_MITM(ptr)     do {(ptr)->sm = 2; (ptr)->lv = 1;} while(0)
00392 /**@brief Set sec_mode pointed to by ptr to require signing or encryption with MITM protection.*/
00393 #define BLE_GAP_CONN_SEC_MODE_SET_SIGNED_WITH_MITM(ptr)   do {(ptr)->sm = 2; (ptr)->lv = 2;} while(0)
00394 /**@} */
00395 
00396 
00397 /**@brief GAP Security Random Number Length. */
00398 #define BLE_GAP_SEC_RAND_LEN 8
00399 
00400 /**@brief GAP Security Key Length. */
00401 #define BLE_GAP_SEC_KEY_LEN 16
00402 
00403 /**@brief GAP LE Secure Connections Elliptic Curve Diffie-Hellman P-256 Public Key Length. */
00404 #define BLE_GAP_LESC_P256_PK_LEN 64
00405 
00406 /**@brief GAP LE Secure Connections Elliptic Curve Diffie-Hellman DHKey Length. */
00407 #define BLE_GAP_LESC_DHKEY_LEN   32
00408 
00409 /**@brief GAP Passkey Length. */
00410 #define BLE_GAP_PASSKEY_LEN 6
00411 
00412 /**@brief Maximum amount of addresses in a whitelist. */
00413 #define BLE_GAP_WHITELIST_ADDR_MAX_COUNT (8)
00414 
00415 /**@brief Maximum amount of IRKs in a whitelist.
00416  * @note  The number of IRKs is limited to 8, even if the hardware supports more.
00417  */
00418 #define BLE_GAP_WHITELIST_IRK_MAX_COUNT (8)
00419 
00420 /**@defgroup GAP_SEC_MODES GAP Security Modes
00421  * @{ */
00422 #define BLE_GAP_SEC_MODE 0x00 /**< No key (may be used to reject). */
00423 /**@} */
00424 /** @} */
00425 
00426 /**@addtogroup BLE_GAP_STRUCTURES Structures
00427  * @{ */
00428 
00429 /**
00430  * @brief BLE GAP initialization parameters.
00431  */
00432 typedef struct
00433 {
00434   uint8_t                   periph_conn_count;  /**< Number of connections acting as a peripheral  */
00435   uint8_t                   central_conn_count; /**< Number of connections acting as a central */
00436   uint8_t                   central_sec_count;  /**< Number of SMP instances for all connections acting as a central. */
00437 } ble_gap_enable_params_t;
00438 
00439 /**@brief Bluetooth Low Energy address. */
00440 typedef struct
00441 {
00442   uint8_t addr_type;                    /**< See @ref BLE_GAP_ADDR_TYPES. */
00443   uint8_t addr[BLE_GAP_ADDR_LEN];       /**< 48-bit address, LSB format. */
00444 } ble_gap_addr_t;
00445 
00446 
00447 /**@brief GAP connection parameters.
00448  *
00449  * @note  When ble_conn_params_t is received in an event, both min_conn_interval and
00450  *        max_conn_interval will be equal to the connection interval set by the central.
00451  *
00452  * @note If both conn_sup_timeout and max_conn_interval are specified, then the following constraint applies:
00453  *       conn_sup_timeout * 4 > (1 + slave_latency) * max_conn_interval
00454  *       that corresponds to the following Bluetooth Spec requirement:
00455  *       The Supervision_Timeout in milliseconds shall be larger than
00456  *       (1 + Conn_Latency) * Conn_Interval_Max * 2, where Conn_Interval_Max is given in milliseconds.
00457  */
00458 typedef struct
00459 {
00460   uint16_t min_conn_interval;         /**< Minimum Connection Interval in 1.25 ms units, see @ref BLE_GAP_CP_LIMITS.*/
00461   uint16_t max_conn_interval;         /**< Maximum Connection Interval in 1.25 ms units, see @ref BLE_GAP_CP_LIMITS.*/
00462   uint16_t slave_latency;             /**< Slave Latency in number of connection events, see @ref BLE_GAP_CP_LIMITS.*/
00463   uint16_t conn_sup_timeout;          /**< Connection Supervision Timeout in 10 ms units, see @ref BLE_GAP_CP_LIMITS.*/
00464 } ble_gap_conn_params_t;
00465 
00466 
00467 /**@brief GAP connection security modes.
00468  *
00469  * Security Mode 0 Level 0: No access permissions at all (this level is not defined by the Bluetooth Core specification).\n
00470  * Security Mode 1 Level 1: No security is needed (aka open link).\n
00471  * Security Mode 1 Level 2: Encrypted link required, MITM protection not necessary.\n
00472  * Security Mode 1 Level 3: MITM protected encrypted link required.\n
00473  * Security Mode 1 Level 4: LESC MITM protected encrypted link required.\n
00474  * Security Mode 2 Level 1: Signing or encryption required, MITM protection not necessary.\n
00475  * Security Mode 2 Level 2: MITM protected signing required, unless link is MITM protected encrypted.\n
00476  */
00477 typedef struct
00478 {
00479   uint8_t sm : 4;                     /**< Security Mode (1 or 2), 0 for no permissions at all. */
00480   uint8_t lv : 4;                     /**< Level (1, 2, 3 or 4), 0 for no permissions at all. */
00481 
00482 } ble_gap_conn_sec_mode_t;
00483 
00484 
00485 /**@brief GAP connection security status.*/
00486 typedef struct
00487 {
00488   ble_gap_conn_sec_mode_t sec_mode;           /**< Currently active security mode for this connection.*/
00489   uint8_t                 encr_key_size;      /**< Length of currently active encryption key, 7 to 16 octets (only applicable for bonding procedures). */
00490 } ble_gap_conn_sec_t;
00491 
00492 
00493 /**@brief Identity Resolving Key. */
00494 typedef struct
00495 {
00496   uint8_t irk[BLE_GAP_SEC_KEY_LEN];   /**< Array containing IRK. */
00497 } ble_gap_irk_t;
00498 
00499 
00500 /**@brief Whitelist structure. */
00501 typedef struct
00502 {
00503   ble_gap_addr_t    **pp_addrs;        /**< Pointer to an array of device address pointers, pointing to addresses to be used in whitelist. NULL if none are given. */
00504   uint8_t             addr_count;      /**< Count of device addresses in array, up to @ref BLE_GAP_WHITELIST_ADDR_MAX_COUNT. */
00505   ble_gap_irk_t     **pp_irks;         /**< Pointer to an array of Identity Resolving Key (IRK) pointers, each pointing to an IRK in the whitelist. NULL if none are given. */
00506   uint8_t             irk_count;       /**< Count of IRKs in array, up to @ref BLE_GAP_WHITELIST_IRK_MAX_COUNT. */
00507 } ble_gap_whitelist_t;
00508 
00509 /**@brief Channel mask for RF channels used in advertising. */
00510 typedef struct
00511 {
00512   uint8_t ch_37_off : 1;  /**< Setting this bit to 1 will turn off advertising on channel 37 */
00513   uint8_t ch_38_off : 1;  /**< Setting this bit to 1 will turn off advertising on channel 38 */
00514   uint8_t ch_39_off : 1;  /**< Setting this bit to 1 will turn off advertising on channel 39 */
00515 } ble_gap_adv_ch_mask_t;
00516 
00517 /**@brief GAP advertising parameters.*/
00518 typedef struct
00519 {
00520   uint8_t               type;                 /**< See @ref BLE_GAP_ADV_TYPES. */
00521   ble_gap_addr_t       *p_peer_addr;          /**< For @ref BLE_GAP_ADV_TYPE_ADV_DIRECT_IND mode only, known peer address. */
00522   uint8_t               fp;                   /**< Filter Policy, see @ref BLE_GAP_ADV_FILTER_POLICIES. */
00523   ble_gap_whitelist_t  *p_whitelist;          /**< Pointer to whitelist, NULL if no whitelist or the current active whitelist is to be used. */
00524   uint16_t              interval;             /**< Advertising interval between 0x0020 and 0x4000 in 0.625 ms units (20ms to 10.24s), see @ref BLE_GAP_ADV_INTERVALS.
00525                                                    - If type equals @ref BLE_GAP_ADV_TYPE_ADV_DIRECT_IND, this parameter must be set to 0 for high duty cycle directed advertising.
00526                                                    - If type equals @ref BLE_GAP_ADV_TYPE_ADV_DIRECT_IND, set @ref BLE_GAP_ADV_INTERVAL_MIN <= interval <= @ref BLE_GAP_ADV_INTERVAL_MAX for low duty cycle advertising.*/
00527   uint16_t              timeout;              /**< Advertising timeout between 0x0001 and 0x3FFF in seconds, 0x0000 disables timeout. See also @ref BLE_GAP_ADV_TIMEOUT_VALUES. If type equals @ref BLE_GAP_ADV_TYPE_ADV_DIRECT_IND, this parameter must be set to 0 for High duty cycle directed advertising. */
00528   ble_gap_adv_ch_mask_t channel_mask;         /**< Advertising channel mask. See @ref ble_gap_adv_ch_mask_t. */
00529 } ble_gap_adv_params_t;
00530 
00531 
00532 /**@brief GAP scanning parameters. */
00533 typedef struct
00534 {
00535   uint8_t                 active    : 1;        /**< If 1, perform active scanning (scan requests). */
00536   uint8_t                 selective : 1;        /**< If 1, ignore unknown devices (non whitelisted). */
00537   ble_gap_whitelist_t *   p_whitelist;          /**< Pointer to whitelist, NULL if no whitelist or the current active whitelist is to be used. */
00538   uint16_t                interval;             /**< Scan interval between 0x0004 and 0x4000 in 0.625ms units (2.5ms to 10.24s). */
00539   uint16_t                window;               /**< Scan window between 0x0004 and 0x4000 in 0.625ms units (2.5ms to 10.24s). */
00540   uint16_t                timeout;              /**< Scan timeout between 0x0001 and 0xFFFF in seconds, 0x0000 disables timeout. */
00541 } ble_gap_scan_params_t;
00542 
00543 
00544 /** @brief Keys that can be exchanged during a bonding procedure. */
00545 typedef struct
00546 {
00547   uint8_t enc     : 1;                        /**< Long Term Key and Master Identification. */
00548   uint8_t id      : 1;                        /**< Identity Resolving Key and Identity Address Information. */
00549   uint8_t sign    : 1;                        /**< Connection Signature Resolving Key. */
00550   uint8_t link    : 1;                        /**< Derive the Link Key from the LTK. */
00551 } ble_gap_sec_kdist_t;
00552 
00553 
00554 /**@brief GAP security parameters. */
00555 typedef struct
00556 {
00557   uint8_t               bond      : 1;             /**< Perform bonding. */
00558   uint8_t               mitm      : 1;             /**< Enable Man In The Middle protection. */
00559   uint8_t               lesc      : 1;             /**< Enable LE Secure Connection pairing. */
00560   uint8_t               keypress  : 1;             /**< Enable generation of keypress notifications. */
00561   uint8_t               io_caps   : 3;             /**< IO capabilities, see @ref BLE_GAP_IO_CAPS. */
00562   uint8_t               oob       : 1;             /**< Out Of Band data available. */
00563   uint8_t               min_key_size;              /**< Minimum encryption key size in octets between 7 and 16. If 0 then not applicable in this instance. */
00564   uint8_t               max_key_size;              /**< Maximum encryption key size in octets between min_key_size and 16. */
00565   ble_gap_sec_kdist_t   kdist_own;                 /**< Key distribution bitmap: keys that the local device will distribute. */
00566   ble_gap_sec_kdist_t   kdist_peer;                /**< Key distribution bitmap: keys that the remote device will distribute. */
00567 } ble_gap_sec_params_t;
00568 
00569 
00570 /**@brief GAP Encryption Information. */
00571 typedef struct
00572 {
00573   uint8_t   ltk[BLE_GAP_SEC_KEY_LEN];   /**< Long Term Key. */
00574   uint8_t   lesc : 1;                   /**< Key generated using LE Secure Connections. */
00575   uint8_t   auth : 1;                   /**< Authenticated Key. */
00576   uint8_t   ltk_len : 6;                /**< LTK length in octets. */
00577 } ble_gap_enc_info_t;
00578 
00579 
00580 /**@brief GAP Master Identification. */
00581 typedef struct
00582 {
00583   uint16_t  ediv;                       /**< Encrypted Diversifier. */
00584   uint8_t   rand[BLE_GAP_SEC_RAND_LEN]; /**< Random Number. */
00585 } ble_gap_master_id_t;
00586 
00587 
00588 /**@brief GAP Signing Information. */
00589 typedef struct
00590 {
00591   uint8_t   csrk[BLE_GAP_SEC_KEY_LEN];        /**< Connection Signature Resolving Key. */
00592 } ble_gap_sign_info_t;
00593 
00594 /**@brief GAP LE Secure Connections P-256 Public Key. */
00595 typedef struct
00596 {
00597   uint8_t   pk[BLE_GAP_LESC_P256_PK_LEN];        /**< LE Secure Connections Elliptic Curve Diffie-Hellman P-256 Public Key. Stored in the standard SMP protocol format: {X,Y} both in little-endian. */
00598 } ble_gap_lesc_p256_pk_t;
00599 
00600 /**@brief GAP LE Secure Connections DHKey. */
00601 typedef struct
00602 {
00603   uint8_t   key[BLE_GAP_LESC_DHKEY_LEN];        /**< LE Secure Connections Elliptic Curve Diffie-Hellman Key. Stored in little-endian. */
00604 } ble_gap_lesc_dhkey_t;
00605 
00606 /**@brief GAP LE Secure Connections OOB data. */
00607 typedef struct
00608 {
00609   ble_gap_addr_t  addr;                          /**< Bluetooth address of the device. */
00610   uint8_t         r[BLE_GAP_SEC_KEY_LEN];        /**< Random Number. */
00611   uint8_t         c[BLE_GAP_SEC_KEY_LEN];        /**< Confirm Value. */
00612 } ble_gap_lesc_oob_data_t;
00613 
00614 /**@brief Event structure for @ref BLE_GAP_EVT_CONNECTED. */
00615 typedef struct
00616 {
00617   ble_gap_addr_t        peer_addr;              /**< Bluetooth address of the peer device. */
00618   ble_gap_addr_t        own_addr;               /**< Bluetooth address of the local device used during connection setup. */
00619   uint8_t               role;                   /**< BLE role for this connection, see @ref BLE_GAP_ROLES */
00620   uint8_t               irk_match :1;           /**< If 1, peer device's address resolved using an IRK. */
00621   uint8_t               irk_match_idx  :7;      /**< Index in IRK list where the address was matched. */
00622   ble_gap_conn_params_t conn_params;            /**< GAP Connection Parameters. */
00623 } ble_gap_evt_connected_t;
00624 
00625 
00626 /**@brief Event structure for @ref BLE_GAP_EVT_DISCONNECTED. */
00627 typedef struct
00628 {
00629   uint8_t reason;                               /**< HCI error code, see @ref BLE_HCI_STATUS_CODES. */
00630 } ble_gap_evt_disconnected_t;
00631 
00632 
00633 /**@brief Event structure for @ref BLE_GAP_EVT_CONN_PARAM_UPDATE. */
00634 typedef struct
00635 {
00636   ble_gap_conn_params_t conn_params;            /**<  GAP Connection Parameters. */
00637 } ble_gap_evt_conn_param_update_t;
00638 
00639 
00640 /**@brief Event structure for @ref BLE_GAP_EVT_SEC_PARAMS_REQUEST. */
00641 typedef struct
00642 {
00643   ble_gap_sec_params_t peer_params;             /**< Initiator Security Parameters. */
00644 } ble_gap_evt_sec_params_request_t;
00645 
00646 
00647 /**@brief Event structure for @ref BLE_GAP_EVT_SEC_INFO_REQUEST. */
00648 typedef struct
00649 {
00650   ble_gap_addr_t      peer_addr;                     /**< Bluetooth address of the peer device. */
00651   ble_gap_master_id_t master_id;                     /**< Master Identification for LTK lookup. */
00652   uint8_t             enc_info  : 1;                 /**< If 1, Encryption Information required. */
00653   uint8_t             id_info   : 1;                 /**< If 1, Identity Information required. */
00654   uint8_t             sign_info : 1;                 /**< If 1, Signing Information required. */
00655 } ble_gap_evt_sec_info_request_t;
00656 
00657 
00658 /**@brief Event structure for @ref BLE_GAP_EVT_PASSKEY_DISPLAY. */
00659 typedef struct
00660 {
00661   uint8_t passkey[BLE_GAP_PASSKEY_LEN];         /**< 6-digit passkey in ASCII ('0'-'9' digits only). */
00662   uint8_t match_request : 1;                    /**< If 1 requires the application to report the match using @ref sd_ble_gap_auth_key_reply 
00663                                                      with either @ref BLE_GAP_AUTH_KEY_TYPE_NONE if there is no match or 
00664                                                      @ref BLE_GAP_AUTH_KEY_TYPE_PASSKEY if there is a match. */
00665 } ble_gap_evt_passkey_display_t;
00666 
00667 /**@brief Event structure for @ref BLE_GAP_EVT_KEY_PRESSED. */
00668 typedef struct
00669 {
00670   uint8_t kp_not;         /**< Keypress notification type, see @ref BLE_GAP_KP_NOT_TYPES. */
00671 } ble_gap_evt_key_pressed_t;
00672 
00673 
00674 /**@brief Event structure for @ref BLE_GAP_EVT_AUTH_KEY_REQUEST. */
00675 typedef struct
00676 {
00677   uint8_t key_type;                             /**< See @ref BLE_GAP_AUTH_KEY_TYPES. */
00678 } ble_gap_evt_auth_key_request_t;
00679 
00680 /**@brief Event structure for @ref BLE_GAP_EVT_LESC_DHKEY_REQUEST. */
00681 typedef struct
00682 {
00683   ble_gap_lesc_p256_pk_t *p_pk_peer;  /**< LE Secure Connections remote P-256 Public Key. This will point to the application-supplied memory 
00684                                            inside the keyset during the call to @ref sd_ble_gap_sec_params_reply. */
00685   uint8_t oobd_req       :1;          /**< LESC OOB data required. A call to @ref sd_ble_gap_lesc_oob_data_set is required to complete the procedure. */
00686 } ble_gap_evt_lesc_dhkey_request_t;
00687 
00688 
00689 /**@brief Security levels supported.
00690  * @note See Bluetooth Specification Version 4.2 Volume 3, Part C, Chapter 10, Section 10.2.1.
00691 */
00692 typedef struct
00693 {
00694   uint8_t lv1 : 1;                              /**< If 1: Level 1 is supported. */
00695   uint8_t lv2 : 1;                              /**< If 1: Level 2 is supported. */
00696   uint8_t lv3 : 1;                              /**< If 1: Level 3 is supported. */
00697   uint8_t lv4 : 1;                              /**< If 1: Level 4 is supported. */
00698 } ble_gap_sec_levels_t;
00699 
00700 
00701 /**@brief Encryption Key. */
00702 typedef struct
00703 {
00704   ble_gap_enc_info_t    enc_info;             /**< Encryption Information. */
00705   ble_gap_master_id_t   master_id;            /**< Master Identification. */
00706 } ble_gap_enc_key_t;
00707 
00708 
00709 /**@brief Identity Key. */
00710 typedef struct
00711 {
00712   ble_gap_irk_t         id_info;              /**< Identity Information. */
00713   ble_gap_addr_t        id_addr_info;         /**< Identity Address Information. */
00714 } ble_gap_id_key_t;
00715 
00716 
00717 /**@brief Security Keys. */
00718 typedef struct
00719 {
00720   ble_gap_enc_key_t      *p_enc_key;           /**< Encryption Key, or NULL. */
00721   ble_gap_id_key_t       *p_id_key;            /**< Identity Key, or NULL. */
00722   ble_gap_sign_info_t    *p_sign_key;          /**< Signing Key, or NULL. */
00723   ble_gap_lesc_p256_pk_t *p_pk;                /**< LE Secure Connections P-256 Public Key. When in debug mode the application must use the value defined 
00724                                                     in the Core Bluetooth Specification v4.2 Vol.3, Part H, Section 2.3.5.6.1 */
00725 } ble_gap_sec_keys_t;
00726 
00727 
00728 /**@brief Security key set for both local and peer keys. */
00729 typedef struct
00730 {
00731   ble_gap_sec_keys_t            keys_own;     /**< Keys distributed by the local device. For LE Secure Connections the encryption key will be generated locally and will always be stored if bonding. */
00732   ble_gap_sec_keys_t            keys_peer;    /**< Keys distributed by the remote device. For LE Secure Connections, p_enc_key must always be NULL. */
00733 } ble_gap_sec_keyset_t;
00734 
00735 
00736 /**@brief Event structure for @ref BLE_GAP_EVT_AUTH_STATUS. */
00737 typedef struct
00738 {
00739   uint8_t               auth_status;            /**< Authentication status, see @ref BLE_GAP_SEC_STATUS. */
00740   uint8_t               error_src : 2;          /**< On error, source that caused the failure, see @ref BLE_GAP_SEC_STATUS_SOURCES. */
00741   uint8_t               bonded : 1;             /**< Procedure resulted in a bond. */
00742   ble_gap_sec_levels_t  sm1_levels;             /**< Levels supported in Security Mode 1. */
00743   ble_gap_sec_levels_t  sm2_levels;             /**< Levels supported in Security Mode 2. */
00744   ble_gap_sec_kdist_t   kdist_own;              /**< Bitmap stating which keys were exchanged (distributed) by the local device. If bonding with LE Secure Connections, the enc bit will be always set. */
00745   ble_gap_sec_kdist_t   kdist_peer;             /**< Bitmap stating which keys were exchanged (distributed) by the remote device. If bonding with LE Secure Connections, the enc bit will never be set. */
00746 } ble_gap_evt_auth_status_t;
00747 
00748 
00749 /**@brief Event structure for @ref BLE_GAP_EVT_CONN_SEC_UPDATE. */
00750 typedef struct
00751 {
00752   ble_gap_conn_sec_t conn_sec;                  /**< Connection security level. */
00753 } ble_gap_evt_conn_sec_update_t;
00754 
00755 
00756 /**@brief Event structure for @ref BLE_GAP_EVT_TIMEOUT. */
00757 typedef struct
00758 {
00759   uint8_t src;                                  /**< Source of timeout event, see @ref BLE_GAP_TIMEOUT_SOURCES. */
00760 } ble_gap_evt_timeout_t;
00761 
00762 
00763 /**@brief Event structure for @ref BLE_GAP_EVT_RSSI_CHANGED. */
00764 typedef struct
00765 {
00766   int8_t  rssi;                               /**< Received Signal Strength Indication in dBm. */
00767 } ble_gap_evt_rssi_changed_t;
00768 
00769 
00770 /**@brief Event structure for @ref BLE_GAP_EVT_ADV_REPORT. */
00771 typedef struct
00772 {
00773   ble_gap_addr_t peer_addr;                     /**< Bluetooth address of the peer device. */
00774   int8_t         rssi;                          /**< Received Signal Strength Indication in dBm. */
00775   uint8_t        scan_rsp : 1;                  /**< If 1, the report corresponds to a scan response and the type field may be ignored. */
00776   uint8_t        type     : 2;                  /**< See @ref BLE_GAP_ADV_TYPES. Only valid if the scan_rsp field is 0. */
00777   uint8_t        dlen     : 5;                  /**< Advertising or scan response data length. */
00778   uint8_t        data[BLE_GAP_ADV_MAX_SIZE];    /**< Advertising or scan response data. */
00779 } ble_gap_evt_adv_report_t;
00780 
00781 
00782 /**@brief Event structure for @ref BLE_GAP_EVT_SEC_REQUEST. */
00783 typedef struct
00784 {
00785   uint8_t    bond       : 1;                       /**< Perform bonding. */
00786   uint8_t    mitm       : 1;                       /**< Man In The Middle protection requested. */
00787   uint8_t    lesc       : 1;                       /**< LE Secure Connections requested. */
00788   uint8_t    keypress   : 1;                       /**< Generation of keypress notifications requested. */
00789 } ble_gap_evt_sec_request_t;
00790 
00791 
00792 /**@brief Event structure for @ref BLE_GAP_EVT_CONN_PARAM_UPDATE_REQUEST. */
00793 typedef struct
00794 {
00795   ble_gap_conn_params_t conn_params;            /**<  GAP Connection Parameters. */
00796 } ble_gap_evt_conn_param_update_request_t;
00797 
00798 
00799 /**@brief Event structure for @ref BLE_GAP_EVT_SCAN_REQ_REPORT. */
00800 typedef struct
00801 {
00802   int8_t                  rssi;              /**< Received Signal Strength Indication in dBm. */
00803   ble_gap_addr_t          peer_addr;         /**< Bluetooth address of the peer device. */
00804 } ble_gap_evt_scan_req_report_t;
00805 
00806 
00807 
00808 /**@brief GAP event structure. */
00809 typedef struct
00810 {
00811   uint16_t conn_handle;                                     /**< Connection Handle on which event occurred. */
00812   union                                                     /**< union alternative identified by evt_id in enclosing struct. */
00813   {
00814     ble_gap_evt_connected_t                   connected;                    /**< Connected Event Parameters. */
00815     ble_gap_evt_disconnected_t                disconnected;                 /**< Disconnected Event Parameters. */
00816     ble_gap_evt_conn_param_update_t           conn_param_update;            /**< Connection Parameter Update Parameters. */
00817     ble_gap_evt_sec_params_request_t          sec_params_request;           /**< Security Parameters Request Event Parameters. */
00818     ble_gap_evt_sec_info_request_t            sec_info_request;             /**< Security Information Request Event Parameters. */
00819     ble_gap_evt_passkey_display_t             passkey_display;              /**< Passkey Display Event Parameters. */
00820     ble_gap_evt_key_pressed_t                 key_pressed;                  /**< Key Pressed Event Parameters. */
00821     ble_gap_evt_auth_key_request_t            auth_key_request;             /**< Authentication Key Request Event Parameters. */
00822     ble_gap_evt_lesc_dhkey_request_t          lesc_dhkey_request;           /**< LE Secure Connections DHKey calculation request. */
00823     ble_gap_evt_auth_status_t                 auth_status;                  /**< Authentication Status Event Parameters. */
00824     ble_gap_evt_conn_sec_update_t             conn_sec_update;              /**< Connection Security Update Event Parameters. */
00825     ble_gap_evt_timeout_t                     timeout;                      /**< Timeout Event Parameters. */
00826     ble_gap_evt_rssi_changed_t                rssi_changed;                 /**< RSSI Event parameters. */
00827     ble_gap_evt_adv_report_t                  adv_report;                   /**< Advertising Report Event Parameters. */
00828     ble_gap_evt_sec_request_t                 sec_request;                  /**< Security Request Event Parameters. */
00829     ble_gap_evt_conn_param_update_request_t   conn_param_update_request;    /**< Connection Parameter Update Parameters. */
00830     ble_gap_evt_scan_req_report_t             scan_req_report;              /**< Scan Request Report parameters. */
00831   } params;                                                                 /**< Event Parameters. */
00832 
00833 } ble_gap_evt_t;
00834 
00835 
00836 /**@brief Channel Map option.
00837  *        Used with @ref sd_ble_opt_get to get the current channel map
00838  *        or @ref sd_ble_opt_set to set a new channel map. When setting the
00839  *        channel map, it applies to all current and future connections. When getting the
00840  *        current channel map, it applies to a single connection and the connection handle
00841  *        must be supplied.
00842  *
00843  * @note  Setting the channel map may take some time, depending on connection parameters.
00844  *        The time taken may be different for each connection and the get operation will
00845  *        return the previous channel map until the new one has taken effect.
00846  *
00847  * @note  After setting the channel map, by spec it can not be set again until at least 1 s has passed.
00848  *        See Bluetooth Specification Version 4.1 Volume 2, Part E, Section 7.3.46.
00849  *
00850  * @retval ::NRF_SUCCESS Get or set successful.
00851  * @retval ::NRF_ERROR_BUSY Channel map was set again before enough time had passed.
00852  * @retval ::NRF_ERROR_INVALID_STATE Invalid state to perform operation.
00853  * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid connection handle supplied for get.
00854  * @retval ::NRF_ERROR_NOT_SUPPORTED Returned by sd_ble_opt_set in peripheral-only SoftDevices.
00855  *
00856  */
00857 typedef struct
00858 {
00859   uint16_t conn_handle;                   /**< Connection Handle (only applicable for get) */
00860   uint8_t ch_map[5];                      /**< Channel Map (37-bit). */
00861 } ble_gap_opt_ch_map_t;
00862 
00863 
00864 /**@brief Local connection latency option.
00865  *
00866  *        Local connection latency is a feature which enables the slave to improve
00867  *        current consumption by ignoring the slave latency set by the peer. The
00868  *        local connection latency can only be set to a multiple of the slave latency,
00869  *        and cannot be longer than half of the supervision timeout.
00870  *
00871  *        Used with @ref sd_ble_opt_set to set the local connection latency. The
00872  *        @ref sd_ble_opt_get is not supported for this option, but the actual
00873  *        local connection latency (unless set to NULL) is set as a return parameter
00874  *        when setting the option.
00875  *
00876  * @note  The latency set will be truncated down to the closest slave latency event
00877  *        multiple, or the nearest multiple before half of the supervision timeout.
00878  *
00879  * @note  The local connection latency is disabled by default, and needs to be enabled for new
00880  *        connections and whenever the connection is updated.
00881  *
00882  * @retval ::NRF_SUCCESS Set successfully.
00883  * @retval ::NRF_ERROR_NOT_SUPPORTED Get is not supported.
00884  * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid connection handle parameter.
00885  */
00886 typedef struct
00887 {
00888   uint16_t   conn_handle;                       /**< Connection Handle */
00889   uint16_t   requested_latency;                 /**< Requested local connection latency. */
00890   uint16_t * p_actual_latency;                  /**< Pointer to storage for the actual local connection latency (can be set to NULL to skip return value). */
00891 } ble_gap_opt_local_conn_latency_t;
00892 
00893 
00894 /**@brief Passkey Option.
00895  *
00896  *        Structure containing the passkey to be used during pairing. This can be used with @ref
00897  *        sd_ble_opt_set to make the SoftDevice use a pre-programmed passkey for authentication
00898  *        instead of generating a random one.
00899  *
00900  * @note  @ref sd_ble_opt_get is not supported for this option.
00901  *
00902  */
00903 typedef struct
00904 {
00905   uint8_t * p_passkey;                          /**< Pointer to 6-digit ASCII string (digit 0..9 only, no NULL termination) passkey to be used during pairing. If this is NULL, the SoftDevice will generate a random passkey if required.*/
00906 } ble_gap_opt_passkey_t;
00907 
00908 
00909 /**@brief Custom Privacy Option.
00910  *
00911  *        This structure is used with both @ref sd_ble_opt_set (as input) and with
00912  *        @ref sd_ble_opt_get (as output).
00913  *
00914  *        Structure containing:
00915  *        - A pointer to an IRK to set (if input), or a place to store a read IRK (if output).
00916  *        - A private address refresh cycle.
00917  *
00918  * @note  The specified address cycle interval is used when the address cycle mode is
00919  *        @ref BLE_GAP_ADDR_CYCLE_MODE_AUTO. If 0 is given, the address will not be automatically
00920  *        refreshed at all. The default interval is @ref BLE_GAP_DEFAULT_PRIVATE_ADDR_CYCLE_INTERVAL_S.
00921  *
00922  * @note  If the current address cycle mode is @ref BLE_GAP_ADDR_CYCLE_MODE_AUTO, the address will immediately be
00923  *        refreshed when a custom privacy option is set. A new address can be generated manually by calling
00924  *        @ref sd_ble_gap_address_set with the same type again.
00925  *
00926  * @note  If the IRK is updated, the new IRK becomes the one to be distributed in all
00927  *        bonding procedures performed after @ref sd_ble_opt_set returns.
00928  *
00929  * @retval ::NRF_SUCCESS Set or read successfully.
00930  * @retval ::NRF_ERROR_INVALID_ADDR The pointer to IRK storage is invalid.
00931  */
00932 typedef struct
00933 {
00934   ble_gap_irk_t * p_irk;        /**< When input: Pointer to custom IRK, or NULL to use/reset to the device's default IRK. When output: Pointer to where the current IRK is to be stored, or NULL to not read out the IRK. */
00935   uint16_t        interval_s;   /**< When input: Custom private address cycle interval in seconds. When output: The current private address cycle interval. */
00936 } ble_gap_opt_privacy_t;
00937 
00938 
00939 /**@brief Scan request report option.
00940  *
00941  *        This can be used with @ref sd_ble_opt_set to make the SoftDevice send
00942  *        @ref BLE_GAP_EVT_SCAN_REQ_REPORT events.
00943  *
00944  *  @note   Due to the limited space reserved for scan request report events,
00945  *          not all received scan requests will be reported.
00946  *
00947  *  @note   If whitelisting is used, only whitelisted requests are reported.
00948  *
00949  *  @retval ::NRF_SUCCESS Set successfully.
00950  *  @retval ::NRF_ERROR_INVALID_STATE When advertising is ongoing while the option is set.
00951  */
00952 typedef struct
00953 {
00954    uint8_t enable : 1;                           /**< Enable scan request reports. */
00955 } ble_gap_opt_scan_req_report_t;
00956 
00957 /**@brief Compatibility mode option.
00958  *
00959  *        This can be used with @ref sd_ble_opt_set to enable and disable
00960  *        compatibility modes. Compatibility modes are disabled by default.
00961  *
00962  *  @note  Compatibility mode 1 enables interoperability with devices that do not support
00963  *         a value of 0 for the WinOffset parameter in the Link Layer CONNECT_REQ packet.
00964  *
00965  *  @retval ::NRF_SUCCESS Set successfully.
00966  *  @retval ::NRF_ERROR_INVALID_STATE When connection creation is ongoing while mode 1 is set.
00967  */
00968 typedef struct
00969 {
00970    uint8_t mode_1_enable : 1;                           /**< Enable compatibility mode 1.*/
00971 } ble_gap_opt_compat_mode_t;
00972 
00973 /**@brief Option structure for GAP options. */
00974 typedef union
00975 {
00976   ble_gap_opt_ch_map_t                  ch_map;                    /**< Parameters for the Channel Map option. */
00977   ble_gap_opt_local_conn_latency_t      local_conn_latency;        /**< Parameters for the Local connection latency option */
00978   ble_gap_opt_passkey_t                 passkey;                   /**< Parameters for the Passkey option.*/
00979   ble_gap_opt_privacy_t                 privacy;                   /**< Parameters for the Custom privacy option. */
00980   ble_gap_opt_scan_req_report_t         scan_req_report;           /**< Parameters for the scan request report option.*/
00981   ble_gap_opt_compat_mode_t             compat_mode;               /**< Parameters for the compatibility mode option.*/
00982 } ble_gap_opt_t;
00983 /**@} */
00984 
00985 
00986 /**@addtogroup BLE_GAP_FUNCTIONS Functions
00987  * @{ */
00988 
00989 /**@brief Set local Bluetooth address.
00990  *
00991  * @note If the address cycle mode is @ref BLE_GAP_ADDR_CYCLE_MODE_AUTO, the address type is required to
00992  * be @ref BLE_GAP_ADDR_TYPE_RANDOM_PRIVATE_RESOLVABLE or
00993  * @ref BLE_GAP_ADDR_TYPE_RANDOM_PRIVATE_NON_RESOLVABLE. The given address is ignored and the
00994  * SoftDevice will generate a new private address automatically every
00995  * @ref BLE_GAP_DEFAULT_PRIVATE_ADDR_CYCLE_INTERVAL_S seconds. If this API
00996  * call is used again with the same parameters, the SoftDevice will immediately
00997  * generate a new private address to replace the current address.
00998  *
00999  * @note If the application wishes to use a @ref BLE_GAP_ADDR_TYPE_PUBLIC or
01000  * @ref BLE_GAP_ADDR_TYPE_RANDOM_STATIC address, the cycle mode must be
01001  * @ref BLE_GAP_ADDR_CYCLE_MODE_NONE.
01002  *
01003  * @note By default the SoftDevice will set an address of type @ref BLE_GAP_ADDR_TYPE_RANDOM_STATIC upon being
01004  * enabled. The address is a random number populated during the IC manufacturing process and remains unchanged
01005  * for the lifetime of each IC.
01006  *
01007  * @note If this API function is called while advertising or scanning, the softdevice will immediately update the
01008  * advertising or scanning address without the need to stop the procedure in the following cases:
01009  *   - If the previously set address is of type @ref BLE_GAP_ADDR_TYPE_PUBLIC and the new address
01010  *   is also of type @ref BLE_GAP_ADDR_TYPE_PUBLIC
01011  *   - If the previously set address is not @ref BLE_GAP_ADDR_TYPE_PUBLIC and the new address is
01012  *   also not @ref BLE_GAP_ADDR_TYPE_PUBLIC.
01013  * If the address is changed from a @ref BLE_GAP_ADDR_TYPE_PUBLIC address to another type or from
01014  * another type to a @ref BLE_GAP_ADDR_TYPE_PUBLIC address, the change will take effect the next
01015  * time an advertising or scanning procedure is started.
01016  *
01017  * @note If the address cycle mode is @ref BLE_GAP_ADDR_CYCLE_MODE_NONE and the application is
01018  *       using privacy, the application must take care to generate and set new private addresses
01019  *       periodically to comply with the Privacy specification in Bluetooth Core Spec.
01020  *
01021  * @mscs
01022  * @mmsc{@ref BLE_GAP_ADV_MSC}
01023  * @endmscs
01024  *
01025  * @param[in] addr_cycle_mode Address cycle mode, see @ref BLE_GAP_ADDR_CYCLE_MODES.
01026  * @param[in] p_addr          Pointer to address structure.
01027  *
01028  * @retval ::NRF_SUCCESS Address successfully set.
01029  * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
01030  * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameters.
01031  * @retval ::BLE_ERROR_GAP_INVALID_BLE_ADDR Invalid address.
01032  * @retval ::NRF_ERROR_BUSY The stack is busy, process pending events and retry.
01033  * @retval ::NRF_ERROR_INVALID_STATE Invalid state to perform operation.
01034  */
01035 SVCALL(SD_BLE_GAP_ADDRESS_SET, uint32_t, sd_ble_gap_address_set(uint8_t addr_cycle_mode, ble_gap_addr_t const *p_addr));
01036 
01037 
01038 /**@brief Get local Bluetooth address.
01039  *
01040  * @param[out] p_addr Pointer to address structure to be filled in.
01041  *
01042  * @retval ::NRF_SUCCESS Address successfully retrieved.
01043  * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
01044  */
01045 SVCALL(SD_BLE_GAP_ADDRESS_GET, uint32_t, sd_ble_gap_address_get(ble_gap_addr_t *p_addr));
01046 
01047 
01048 /**@brief Set, clear or update advertising and scan response data.
01049  *
01050  * @note The format of the advertising data will be checked by this call to ensure interoperability.
01051  *       Limitations imposed by this API call to the data provided include having a flags data type in the scan response data and
01052  *       duplicating the local name in the advertising data and scan response data.
01053  *
01054  * @note To clear the advertising data and set it to a 0-length packet, simply provide a valid pointer (p_data/p_sr_data) with its corresponding
01055  *        length (dlen/srdlen) set to 0.
01056  *
01057  * @note The call will fail if p_data and p_sr_data are both NULL since this would have no effect.
01058  *
01059  * @mscs
01060  * @mmsc{@ref BLE_GAP_ADV_MSC}
01061  * @mmsc{@ref BLE_GAP_WL_SHARE_MSC}
01062  * @endmscs
01063  *
01064  * @param[in] p_data    Raw data to be placed in advertising packet. If NULL, no changes are made to the current advertising packet data.
01065  * @param[in] dlen      Data length for p_data. Max size: @ref BLE_GAP_ADV_MAX_SIZE octets. Should be 0 if p_data is NULL, can be 0 if p_data is not NULL.
01066  * @param[in] p_sr_data Raw data to be placed in scan response packet. If NULL, no changes are made to the current scan response packet data.
01067  * @param[in] srdlen    Data length for p_sr_data. Max size: @ref BLE_GAP_ADV_MAX_SIZE octets. Should be 0 if p_sr_data is NULL, can be 0 if p_data is not NULL.
01068  *
01069  * @retval ::NRF_SUCCESS Advertising data successfully updated or cleared.
01070  * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied, both p_data and p_sr_data cannot be NULL.
01071  * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
01072  * @retval ::NRF_ERROR_INVALID_FLAGS Invalid combination of advertising flags supplied.
01073  * @retval ::NRF_ERROR_INVALID_DATA Invalid data type(s) supplied, check the advertising data format specification.
01074  * @retval ::NRF_ERROR_INVALID_LENGTH Invalid data length(s) supplied.
01075  * @retval ::NRF_ERROR_NOT_SUPPORTED Unsupported data type.
01076  * @retval ::BLE_ERROR_GAP_UUID_LIST_MISMATCH Invalid UUID list supplied.
01077  */
01078 SVCALL(SD_BLE_GAP_ADV_DATA_SET, uint32_t, sd_ble_gap_adv_data_set(uint8_t const *p_data, uint8_t dlen, uint8_t const *p_sr_data, uint8_t srdlen));
01079 
01080 
01081 /**@brief Start advertising (GAP Discoverable, Connectable modes, Broadcast Procedure).
01082  *
01083  * @note An application can start an advertising procedure for broadcasting purposes while a connection
01084  *       is active. After a @ref BLE_GAP_EVT_CONNECTED event is received, this function may therefore
01085  *       be called to start a broadcast advertising procedure. The advertising procedure
01086  *       cannot however be connectable (it must be of type @ref BLE_GAP_ADV_TYPE_ADV_SCAN_IND or
01087  *       @ref BLE_GAP_ADV_TYPE_ADV_NONCONN_IND). @note Only one advertiser may be active at any time.
01088  *
01089  * @note To use the currently active whitelist set p_adv_params->p_whitelist to NULL.
01090  *
01091  * @events
01092  * @event{@ref BLE_GAP_EVT_CONNECTED, Generated after connection has been established through connectable advertising.}
01093  * @event{@ref BLE_GAP_EVT_TIMEOUT, Advertisement has timed out.}
01094  * @endevents
01095  *
01096  * @mscs
01097  * @mmsc{@ref BLE_GAP_ADV_MSC}
01098  * @mmsc{@ref BLE_GAP_WL_SHARE_MSC}
01099  * @endmscs
01100  *
01101  * @param[in] p_adv_params Pointer to advertising parameters structure.
01102  *
01103  * @retval ::NRF_SUCCESS The BLE stack has started advertising.
01104  * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
01105  * @retval ::NRF_ERROR_INVALID_STATE Invalid state to perform operation.
01106  * @retval ::NRF_ERROR_CONN_COUNT The limit of available connections has been reached; connectable advertiser cannot be started.
01107  * @retval ::NRF_ERROR_NO_MEM The configured memory pools (see @ref ble_conn_bw_counts_t) are not large enough for the
01108  *                            bandwidth selected for this connection.
01109  * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied, check the accepted ranges and limits.
01110  * @retval ::BLE_ERROR_GAP_INVALID_BLE_ADDR Invalid Bluetooth address supplied.
01111  * @retval ::BLE_ERROR_GAP_DISCOVERABLE_WITH_WHITELIST Discoverable mode and whitelist incompatible.
01112  * @retval ::NRF_ERROR_BUSY The stack is busy, process pending events and retry.
01113  * @retval ::BLE_ERROR_GAP_WHITELIST_IN_USE Unable to replace the whitelist while another operation is using it.
01114  * @retval ::NRF_ERROR_RESOURCES Not enough BLE role slots available.
01115  *                               Stop one or more currently active roles (Central, Peripheral or Observer) and try again
01116  */
01117 SVCALL(SD_BLE_GAP_ADV_START, uint32_t, sd_ble_gap_adv_start(ble_gap_adv_params_t const *p_adv_params));
01118 
01119 
01120 /**@brief Stop advertising (GAP Discoverable, Connectable modes, Broadcast Procedure).
01121  *
01122  * @mscs
01123  * @mmsc{@ref BLE_GAP_ADV_MSC}
01124  * @mmsc{@ref BLE_GAP_WL_SHARE_MSC}
01125  * @endmscs
01126  *
01127  * @retval ::NRF_SUCCESS The BLE stack has stopped advertising.
01128  * @retval ::NRF_ERROR_INVALID_STATE Invalid state to perform operation (most probably not in advertising state).
01129  */
01130 SVCALL(SD_BLE_GAP_ADV_STOP, uint32_t, sd_ble_gap_adv_stop(void));
01131 
01132 
01133 /**@brief Update connection parameters.
01134  *
01135  * @details In the central role this will initiate a Link Layer connection parameter update procedure,
01136  *          otherwise in the peripheral role, this will send the corresponding L2CAP request and wait for
01137  *          the central to perform the procedure. In both cases, and regardless of success or failure, the application
01138  *          will be informed of the result with a @ref BLE_GAP_EVT_CONN_PARAM_UPDATE event.
01139  *
01140  * @details This function can be used as a central both to reply to a @ref BLE_GAP_EVT_CONN_PARAM_UPDATE_REQUEST or to start the procedure unrequested.
01141  *
01142  * @events
01143  * @event{@ref BLE_GAP_EVT_CONN_PARAM_UPDATE, Result of the connection parameter update procedure.}
01144  * @endevents
01145  *
01146  * @mscs
01147  * @mmsc{@ref BLE_GAP_CPU_MSC}
01148  * @mmsc{@ref BLE_GAP_CENTRAL_ENC_AUTH_MUTEX_MSC}
01149  * @mmsc{@ref BLE_GAP_MULTILINK_CPU_MSC}
01150  * @mmsc{@ref BLE_GAP_MULTILINK_CTRL_PROC_MSC}
01151  * @mmsc{@ref BLE_GAP_CENTRAL_CPU_MSC}
01152  * @endmscs
01153  *
01154  * @param[in] conn_handle Connection handle.
01155  * @param[in] p_conn_params  Pointer to desired connection parameters. If NULL is provided on a peripheral role,
01156  *                           the parameters in the PPCP characteristic of the GAP service will be used instead.
01157  *                           If NULL is provided on a central role and in response to a @ref BLE_GAP_EVT_CONN_PARAM_UPDATE_REQUEST, the peripheral request will be rejected
01158  *
01159  * @retval ::NRF_SUCCESS The Connection Update procedure has been started successfully.
01160  * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
01161  * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied, check parameter limits and constraints.
01162  * @retval ::NRF_ERROR_INVALID_STATE Invalid state to perform operation.
01163  * @retval ::NRF_ERROR_BUSY Procedure already in progress or not allowed at this time, process pending events and wait for pending procedures to complete and retry.
01164  * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid connection handle supplied.
01165  * @retval ::NRF_ERROR_NO_MEM Not enough memory to complete operation.
01166  */
01167 SVCALL(SD_BLE_GAP_CONN_PARAM_UPDATE, uint32_t, sd_ble_gap_conn_param_update(uint16_t conn_handle, ble_gap_conn_params_t const *p_conn_params));
01168 
01169 
01170 /**@brief Disconnect (GAP Link Termination).
01171  *
01172  * @details This call initiates the disconnection procedure, and its completion will be communicated to the application
01173  *          with a @ref BLE_GAP_EVT_DISCONNECTED event.
01174  *
01175  * @events
01176  * @event{@ref BLE_GAP_EVT_DISCONNECTED, Generated when disconnection procedure is complete.}
01177  * @endevents
01178  *
01179  * @mscs
01180  * @mmsc{@ref BLE_GAP_CONN_MSC}
01181  * @endmscs
01182  *
01183  * @param[in] conn_handle Connection handle.
01184  * @param[in] hci_status_code HCI status code, see @ref BLE_HCI_STATUS_CODES (accepted values are @ref BLE_HCI_REMOTE_USER_TERMINATED_CONNECTION and @ref BLE_HCI_CONN_INTERVAL_UNACCEPTABLE).
01185  *
01186  * @retval ::NRF_SUCCESS The disconnection procedure has been started successfully.
01187  * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied.
01188  * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid connection handle supplied.
01189  * @retval ::NRF_ERROR_INVALID_STATE Invalid state to perform operation (disconnection is already in progress).
01190  */
01191 SVCALL(SD_BLE_GAP_DISCONNECT, uint32_t, sd_ble_gap_disconnect(uint16_t conn_handle, uint8_t hci_status_code));
01192 
01193 
01194 /**@brief Set the radio's transmit power.
01195  *
01196  * @param[in] tx_power Radio transmit power in dBm (accepted values are -40, -30, -20, -16, -12, -8, -4, 0, and 4 dBm).
01197  *
01198  * @note The -30dBm setting is only available on nRF51 series ICs.
01199  * @note The -40dBm setting is only available on nRF52 series ICs.
01200  *
01201  * @retval ::NRF_SUCCESS Successfully changed the transmit power.
01202  * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied.
01203  */
01204 SVCALL(SD_BLE_GAP_TX_POWER_SET, uint32_t, sd_ble_gap_tx_power_set(int8_t tx_power));
01205 
01206 
01207 /**@brief Set GAP Appearance value.
01208  *
01209  * @param[in] appearance Appearance (16-bit), see @ref BLE_APPEARANCES.
01210  *
01211  * @retval ::NRF_SUCCESS  Appearance value set successfully.
01212  * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied.
01213  */
01214 SVCALL(SD_BLE_GAP_APPEARANCE_SET, uint32_t, sd_ble_gap_appearance_set(uint16_t appearance));
01215 
01216 
01217 /**@brief Get GAP Appearance value.
01218  *
01219  * @param[out] p_appearance Pointer to appearance (16-bit) to be filled in, see @ref BLE_APPEARANCES.
01220  *
01221  * @retval ::NRF_SUCCESS Appearance value retrieved successfully.
01222  * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
01223  */
01224 SVCALL(SD_BLE_GAP_APPEARANCE_GET, uint32_t, sd_ble_gap_appearance_get(uint16_t *p_appearance));
01225 
01226 
01227 /**@brief Set GAP Peripheral Preferred Connection Parameters.
01228  *
01229  * @param[in] p_conn_params Pointer to a @ref ble_gap_conn_params_t structure with the desired parameters.
01230  *
01231  * @retval ::NRF_SUCCESS Peripheral Preferred Connection Parameters set successfully.
01232  * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
01233  * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied.
01234  */
01235 SVCALL(SD_BLE_GAP_PPCP_SET, uint32_t, sd_ble_gap_ppcp_set(ble_gap_conn_params_t const *p_conn_params));
01236 
01237 
01238 /**@brief Get GAP Peripheral Preferred Connection Parameters.
01239  *
01240  * @param[out] p_conn_params Pointer to a @ref ble_gap_conn_params_t structure where the parameters will be stored.
01241  *
01242  * @retval ::NRF_SUCCESS Peripheral Preferred Connection Parameters retrieved successfully.
01243  * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
01244  */
01245 SVCALL(SD_BLE_GAP_PPCP_GET, uint32_t, sd_ble_gap_ppcp_get(ble_gap_conn_params_t *p_conn_params));
01246 
01247 
01248 /**@brief Set GAP device name.
01249  *
01250  * @param[in] p_write_perm Write permissions for the Device Name characteristic, see @ref ble_gap_conn_sec_mode_t.
01251  * @param[in] p_dev_name Pointer to a UTF-8 encoded, <b>non NULL-terminated</b> string.
01252  * @param[in] len Length of the UTF-8, <b>non NULL-terminated</b> string pointed to by p_dev_name in octets (must be smaller or equal than @ref BLE_GAP_DEVNAME_MAX_LEN).
01253  *
01254  * @retval ::NRF_SUCCESS GAP device name and permissions set successfully.
01255  * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
01256  * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied.
01257  * @retval ::NRF_ERROR_DATA_SIZE Invalid data size(s) supplied.
01258  */
01259 SVCALL(SD_BLE_GAP_DEVICE_NAME_SET, uint32_t, sd_ble_gap_device_name_set(ble_gap_conn_sec_mode_t const *p_write_perm, uint8_t const *p_dev_name, uint16_t len));
01260 
01261 
01262 /**@brief Get GAP device name.
01263  *
01264  * @note          If the device name is longer than the size of the supplied buffer,
01265  *                p_len will return the complete device name length,
01266  *                and not the number of bytes actually returned in p_dev_name.
01267  *                The application may use this information to allocate a suitable buffer size.
01268  *
01269  * @param[out]    p_dev_name Pointer to an empty buffer where the UTF-8 <b>non NULL-terminated</b> string will be placed. Set to NULL to obtain the complete device name length.
01270  * @param[in,out] p_len      Length of the buffer pointed by p_dev_name, complete device name length on output.
01271  *
01272  * @retval ::NRF_SUCCESS GAP device name retrieved successfully.
01273  * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
01274  * @retval ::NRF_ERROR_DATA_SIZE Invalid data size(s) supplied.
01275  */
01276 SVCALL(SD_BLE_GAP_DEVICE_NAME_GET, uint32_t, sd_ble_gap_device_name_get(uint8_t *p_dev_name, uint16_t *p_len));
01277 
01278 
01279 /**@brief Initiate the GAP Authentication procedure.
01280  *
01281  * @details In the central role, this function will send an SMP Pairing Request (or an SMP Pairing Failed if rejected),
01282  *          otherwise in the peripheral role, an SMP Security Request will be sent.
01283  *
01284  * @events
01285  * @event{Depending on the security parameters set and the packet exchanges with the peer\, the following events may be generated:}
01286  * @event{@ref BLE_GAP_EVT_SEC_PARAMS_REQUEST}
01287  * @event{@ref BLE_GAP_EVT_SEC_INFO_REQUEST}
01288  * @event{@ref BLE_GAP_EVT_PASSKEY_DISPLAY}
01289  * @event{@ref BLE_GAP_EVT_KEY_PRESSED}
01290  * @event{@ref BLE_GAP_EVT_AUTH_KEY_REQUEST}
01291  * @event{@ref BLE_GAP_EVT_LESC_DHKEY_REQUEST}
01292  * @event{@ref BLE_GAP_EVT_CONN_SEC_UPDATE}
01293  * @event{@ref BLE_GAP_EVT_AUTH_STATUS}
01294  * @event{@ref BLE_GAP_EVT_TIMEOUT}
01295  * @endevents
01296  *
01297  * @mscs
01298  * @mmsc{@ref BLE_GAP_PERIPH_SEC_REQ_MSC}
01299  * @mmsc{@ref BLE_GAP_CENTRAL_SEC_REQ_MSC}
01300  * @mmsc{@ref BLE_GAP_CENTRAL_ENC_AUTH_MUTEX_MSC}
01301  * @mmsc{@ref BLE_GAP_CENTRAL_PAIRING_JW_MSC}
01302  * @mmsc{@ref BLE_GAP_CENTRAL_BONDING_JW_MSC}
01303  * @mmsc{@ref BLE_GAP_CENTRAL_BONDING_PK_PERIPH_MSC}
01304  * @mmsc{@ref BLE_GAP_CENTRAL_BONDING_PK_PERIPH_OOB_MSC}
01305  * @mmsc{@ref BLE_GAP_CENTRAL_LESC_PAIRING_JW_MSC}
01306  * @mmsc{@ref BLE_GAP_CENTRAL_LESC_BONDING_NC_MSC}
01307  * @mmsc{@ref BLE_GAP_CENTRAL_LESC_BONDING_PKE_PD_MSC}
01308  * @mmsc{@ref BLE_GAP_CENTRAL_LESC_BONDING_PKE_CD_MSC}
01309  * @mmsc{@ref BLE_GAP_CENTRAL_LESC_BONDING_OOB_MSC}
01310  * @endmscs
01311  *
01312  * @param[in] conn_handle Connection handle.
01313  * @param[in] p_sec_params Pointer to the @ref ble_gap_sec_params_t structure with the security parameters to be used during the pairing or bonding procedure.
01314  *                         In the peripheral role, only the bond, mitm, lesc and keypress fields of this structure are used.
01315  *                         In the central role, this pointer may be NULL to reject a Security Request.
01316  *
01317  * @retval ::NRF_SUCCESS Successfully initiated authentication procedure.
01318  * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
01319  * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied.
01320  * @retval ::NRF_ERROR_INVALID_STATE Invalid state to perform operation.
01321  * @retval ::NRF_ERROR_BUSY The stack is busy, process pending events and retry.
01322  * @retval ::NRF_ERROR_NO_MEM The maximum number of authentication procedures that can run in parallel for the given role is reached.
01323  * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid connection handle supplied.
01324  * @retval ::NRF_ERROR_NOT_SUPPORTED Setting of sign or link fields in @ref ble_gap_sec_kdist_t not supported.
01325  * @retval ::NRF_ERROR_TIMEOUT A SMP timeout has occurred, and further SMP operations on this link is prohibited.
01326  */
01327 SVCALL(SD_BLE_GAP_AUTHENTICATE, uint32_t, sd_ble_gap_authenticate(uint16_t conn_handle, ble_gap_sec_params_t const *p_sec_params));
01328 
01329 
01330 /**@brief Reply with GAP security parameters.
01331  *
01332  * @details This function is only used to reply to a @ref BLE_GAP_EVT_SEC_PARAMS_REQUEST, calling it at other times will result in an @ref NRF_ERROR_INVALID_STATE.
01333  * @note    If the call returns an error code, the request is still pending, and the reply call may be repeated with corrected parameters.
01334  *
01335  * @events
01336  * @event{This function is used during authentication procedures\, see the list of events in the documentation of @ref sd_ble_gap_authenticate.}
01337  * @endevents
01338  *
01339  * @mscs
01340  * @mmsc{@ref BLE_GAP_PERIPH_PAIRING_JW_MSC}
01341  * @mmsc{@ref BLE_GAP_PERIPH_BONDING_JW_MSC}
01342  * @mmsc{@ref BLE_GAP_PERIPH_BONDING_PK_PERIPH_MSC}
01343  * @mmsc{@ref BLE_GAP_PERIPH_BONDING_PK_CENTRAL_OOB_MSC}
01344  * @mmsc{@ref BLE_GAP_PERIPH_BONDING_STATIC_PK_MSC}
01345  * @mmsc{@ref BLE_GAP_PERIPH_PAIRING_CONFIRM_FAIL_MSC}
01346  * @mmsc{@ref BLE_GAP_PERIPH_LESC_PAIRING_JW_MSC}
01347  * @mmsc{@ref BLE_GAP_PERIPH_LESC_BONDING_NC_MSC}
01348  * @mmsc{@ref BLE_GAP_PERIPH_LESC_BONDING_PKE_PD_MSC}
01349  * @mmsc{@ref BLE_GAP_PERIPH_LESC_BONDING_PKE_CD_MSC}
01350  * @mmsc{@ref BLE_GAP_PERIPH_LESC_BONDING_OOB_MSC}
01351  * @mmsc{@ref BLE_GAP_PERIPH_PAIRING_KS_TOO_SMALL_MSC}
01352  * @mmsc{@ref BLE_GAP_PERIPH_PAIRING_APP_ERROR_MSC}
01353  * @mmsc{@ref BLE_GAP_PERIPH_PAIRING_REMOTE_PAIRING_FAIL_MSC}
01354  * @mmsc{@ref BLE_GAP_PERIPH_PAIRING_TIMEOUT_MSC}
01355  * @mmsc{@ref BLE_GAP_CENTRAL_PAIRING_JW_MSC}
01356  * @mmsc{@ref BLE_GAP_CENTRAL_BONDING_JW_MSC}
01357  * @mmsc{@ref BLE_GAP_CENTRAL_BONDING_PK_PERIPH_MSC}
01358  * @mmsc{@ref BLE_GAP_CENTRAL_BONDING_PK_PERIPH_OOB_MSC}
01359  * @mmsc{@ref BLE_GAP_CENTRAL_LESC_PAIRING_JW_MSC}
01360  * @mmsc{@ref BLE_GAP_CENTRAL_LESC_BONDING_NC_MSC}
01361  * @mmsc{@ref BLE_GAP_CENTRAL_LESC_BONDING_PKE_PD_MSC}
01362  * @mmsc{@ref BLE_GAP_CENTRAL_LESC_BONDING_PKE_CD_MSC}
01363  * @mmsc{@ref BLE_GAP_CENTRAL_LESC_BONDING_OOB_MSC}
01364  * @endmscs
01365  *
01366  * @param[in] conn_handle Connection handle.
01367  * @param[in] sec_status Security status, see @ref BLE_GAP_SEC_STATUS.
01368  * @param[in] p_sec_params Pointer to a @ref ble_gap_sec_params_t security parameters structure. In the central role this must be set to NULL, as the parameters have
01369  *                         already been provided during a previous call to @ref sd_ble_gap_authenticate.
01370  * @param[in,out] p_sec_keyset Pointer to a @ref ble_gap_sec_keyset_t security keyset structure. Any keys generated and/or distributed as a result of the ongoing security procedure 
01371  *                         will be stored into the memory referenced by the pointers inside this structure. The keys will be stored and available to the application 
01372  *                         upon reception of a @ref BLE_GAP_EVT_AUTH_STATUS event.
01373  *                         Note that the SoftDevice expects the application to provide memory for storing the
01374  *                         peer's keys. So it must be ensured that the relevant pointers inside this structure are not NULL. The pointers to the local key
01375  *                         can, however, be NULL, in which case, the local key data will not be available to the application upon reception of the
01376  *                         @ref BLE_GAP_EVT_AUTH_STATUS event.
01377  *
01378  * @retval ::NRF_SUCCESS Successfully accepted security parameter from the application.
01379  * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
01380  * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied.
01381  * @retval ::NRF_ERROR_INVALID_STATE Invalid state to perform operation.
01382  * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid connection handle supplied.
01383  * @retval ::NRF_ERROR_NOT_SUPPORTED Setting of sign or link fields in @ref ble_gap_sec_kdist_t not supported.
01384  */
01385 SVCALL(SD_BLE_GAP_SEC_PARAMS_REPLY, uint32_t, sd_ble_gap_sec_params_reply(uint16_t conn_handle, uint8_t sec_status, ble_gap_sec_params_t const *p_sec_params, ble_gap_sec_keyset_t const *p_sec_keyset));
01386 
01387 
01388 /**@brief Reply with an authentication key.
01389  *
01390  * @details This function is only used to reply to a @ref BLE_GAP_EVT_AUTH_KEY_REQUEST or a @ref BLE_GAP_EVT_PASSKEY_DISPLAY, calling it at other times will result in an @ref NRF_ERROR_INVALID_STATE.
01391  * @note    If the call returns an error code, the request is still pending, and the reply call may be repeated with corrected parameters.
01392  *
01393  * @events
01394  * @event{This function is used during authentication procedures\, see the list of events in the documentation of @ref sd_ble_gap_authenticate.}
01395  * @endevents
01396  *
01397  * @mscs
01398  * @mmsc{@ref BLE_GAP_PERIPH_BONDING_PK_CENTRAL_OOB_MSC}
01399  * @mmsc{@ref BLE_GAP_PERIPH_LESC_BONDING_NC_MSC}
01400  * @mmsc{@ref BLE_GAP_PERIPH_LESC_BONDING_PKE_CD_MSC}
01401  * @mmsc{@ref BLE_GAP_CENTRAL_BONDING_PK_PERIPH_OOB_MSC}
01402  * @mmsc{@ref BLE_GAP_CENTRAL_LESC_BONDING_NC_MSC}
01403  * @mmsc{@ref BLE_GAP_CENTRAL_LESC_BONDING_PKE_CD_MSC}
01404  * @endmscs
01405  *
01406  * @param[in] conn_handle Connection handle.
01407  * @param[in] key_type See @ref BLE_GAP_AUTH_KEY_TYPES.
01408  * @param[in] p_key If key type is @ref BLE_GAP_AUTH_KEY_TYPE_NONE, then NULL.
01409  *                  If key type is @ref BLE_GAP_AUTH_KEY_TYPE_PASSKEY, then a 6-byte ASCII string (digit 0..9 only, no NULL termination)
01410  *                     or NULL when confirming LE Secure Connections Numeric Comparison.
01411  *                  If key type is @ref BLE_GAP_AUTH_KEY_TYPE_OOB, then a 16-byte OOB key value in Little Endian format.
01412  *
01413  * @retval ::NRF_SUCCESS Authentication key successfully set.
01414  * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
01415  * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied.
01416  * @retval ::NRF_ERROR_INVALID_STATE Invalid state to perform operation.
01417  * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid connection handle supplied.
01418  */
01419 SVCALL(SD_BLE_GAP_AUTH_KEY_REPLY, uint32_t, sd_ble_gap_auth_key_reply(uint16_t conn_handle, uint8_t key_type, uint8_t const *p_key));
01420 
01421 /**@brief Reply with an LE Secure connections DHKey.
01422  *
01423  * @details This function is only used to reply to a @ref BLE_GAP_EVT_LESC_DHKEY_REQUEST, calling it at other times will result in an @ref NRF_ERROR_INVALID_STATE.
01424  * @note    If the call returns an error code, the request is still pending, and the reply call may be repeated with corrected parameters.
01425  *
01426  * @events
01427  * @event{This function is used during authentication procedures\, see the list of events in the documentation of @ref sd_ble_gap_authenticate.}
01428  * @endevents
01429  *
01430  * @mscs
01431  * @mmsc{@ref BLE_GAP_PERIPH_LESC_PAIRING_JW_MSC}
01432  * @mmsc{@ref BLE_GAP_PERIPH_LESC_BONDING_NC_MSC}
01433  * @mmsc{@ref BLE_GAP_PERIPH_LESC_BONDING_PKE_PD_MSC}
01434  * @mmsc{@ref BLE_GAP_PERIPH_LESC_BONDING_PKE_CD_MSC}
01435  * @mmsc{@ref BLE_GAP_PERIPH_LESC_BONDING_OOB_MSC}
01436  * @mmsc{@ref BLE_GAP_CENTRAL_LESC_PAIRING_JW_MSC}
01437  * @mmsc{@ref BLE_GAP_CENTRAL_LESC_BONDING_NC_MSC}
01438  * @mmsc{@ref BLE_GAP_CENTRAL_LESC_BONDING_PKE_PD_MSC}
01439  * @mmsc{@ref BLE_GAP_CENTRAL_LESC_BONDING_PKE_CD_MSC}
01440  * @mmsc{@ref BLE_GAP_CENTRAL_LESC_BONDING_OOB_MSC}
01441  * @endmscs
01442  *
01443  * @param[in] conn_handle Connection handle.
01444  * @param[in] p_dhkey LE Secure Connections DHKey.
01445  *
01446  * @retval ::NRF_SUCCESS DHKey successfully set.
01447  * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
01448  * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied.
01449  * @retval ::NRF_ERROR_INVALID_STATE Invalid state to perform operation.
01450  * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid connection handle supplied.
01451  */
01452 SVCALL(SD_BLE_GAP_LESC_DHKEY_REPLY, uint32_t, sd_ble_gap_lesc_dhkey_reply(uint16_t conn_handle, ble_gap_lesc_dhkey_t const *p_dhkey));
01453 
01454 /**@brief Notify the peer of a local keypress.
01455  *
01456  * @details This function can only be used when an authentication procedure using LE Secure Connection is in progress. Calling it at other times will result in an @ref NRF_ERROR_INVALID_STATE.
01457  *
01458  * @mscs
01459  * @mmsc{@ref BLE_GAP_PERIPH_LESC_BONDING_PKE_CD_MSC}
01460  * @mmsc{@ref BLE_GAP_CENTRAL_LESC_BONDING_PKE_CD_MSC}
01461  * @endmscs
01462  *
01463  * @param[in] conn_handle Connection handle.
01464  * @param[in] kp_not See @ref BLE_GAP_KP_NOT_TYPES.
01465  *
01466  * @retval ::NRF_SUCCESS Keypress notification successfully queued for transmission.
01467  * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied.
01468  * @retval ::NRF_ERROR_INVALID_STATE Invalid state to perform operation. Either not entering a passkey or keypresses have not been enabled by both peers.
01469  * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid connection handle supplied.
01470  * @retval ::NRF_ERROR_BUSY The BLE stack is busy. Retry at later time.
01471  */
01472 SVCALL(SD_BLE_GAP_KEYPRESS_NOTIFY, uint32_t, sd_ble_gap_keypress_notify(uint16_t conn_handle, uint8_t kp_not));
01473 
01474 /**@brief Generate a set of OOB data to send to a peer out of band.
01475  *
01476  * @note The @ref ble_gap_addr_t included in the OOB data returned will be the currently active one (or, if a connection has already been established,
01477  *       the one used during connection setup). The application may manually overwrite it with an updated value.
01478  *
01479  * @mscs
01480  * @mmsc{@ref BLE_GAP_PERIPH_LESC_BONDING_OOB_MSC}
01481  * @mmsc{@ref BLE_GAP_CENTRAL_LESC_BONDING_OOB_MSC}
01482  * @endmscs
01483  *
01484  * @param[in] conn_handle Connection handle. Can be BLE_CONN_HANDLE_INVALID if a BLE connection has not been established yet.
01485  * @param[in] p_pk_own LE Secure Connections local P-256 Public Key.
01486  * @param[out] p_oobd_own The OOB data to be sent out of band to a peer.
01487  *
01488  * @retval ::NRF_SUCCESS OOB data successfully generated.
01489  * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
01490  * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid connection handle supplied.
01491  */
01492 SVCALL(SD_BLE_GAP_LESC_OOB_DATA_GET, uint32_t, sd_ble_gap_lesc_oob_data_get(uint16_t conn_handle, ble_gap_lesc_p256_pk_t const *p_pk_own, ble_gap_lesc_oob_data_t *p_oobd_own));
01493 
01494 /**@brief Provide the OOB data sent/received out of band.
01495  *
01496  * @note At least one of the 2 pointers provided must be different from NULL.
01497  * @note An authentication procedure with OOB selected as an algorithm must be in progress when calling this function.
01498  * @note A @ref BLE_GAP_EVT_LESC_DHKEY_REQUEST event with the oobd_req set to 1 must have been received prior to calling this function.
01499  *
01500  * @events
01501  * @event{This function is used during authentication procedures\, see the list of events in the documentation of @ref sd_ble_gap_authenticate.}
01502  * @endevents
01503  *
01504  * @mscs
01505  * @mmsc{@ref BLE_GAP_PERIPH_LESC_BONDING_OOB_MSC}
01506  * @mmsc{@ref BLE_GAP_CENTRAL_LESC_BONDING_OOB_MSC}
01507  * @endmscs
01508  *
01509  * @param[in] conn_handle Connection handle.
01510  * @param[in] p_oobd_own The OOB data sent out of band to a peer or NULL if none sent.
01511  * @param[in] p_oobd_peer The OOB data received out of band from a peer or NULL if none received.
01512  *
01513  * @retval ::NRF_SUCCESS OOB data accepted.
01514  * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
01515  * @retval ::NRF_ERROR_INVALID_STATE Invalid state to perform operation.
01516  * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid connection handle supplied.
01517  */
01518 SVCALL(SD_BLE_GAP_LESC_OOB_DATA_SET, uint32_t, sd_ble_gap_lesc_oob_data_set(uint16_t conn_handle, ble_gap_lesc_oob_data_t const *p_oobd_own, ble_gap_lesc_oob_data_t const *p_oobd_peer));
01519 
01520 /**@brief Initiate GAP Encryption procedure.
01521  *
01522  * @details In the central role, this function will initiate the encryption procedure using the encryption information provided.
01523  *
01524  * @events
01525  * @event{@ref BLE_GAP_EVT_CONN_SEC_UPDATE, The connection security has been updated.}
01526  * @endevents
01527  *
01528  * @mscs
01529  * @mmsc{@ref BLE_GAP_CENTRAL_ENC_AUTH_MUTEX_MSC}
01530  * @mmsc{@ref BLE_GAP_CENTRAL_ENC_MSC}
01531  * @mmsc{@ref BLE_GAP_MULTILINK_CTRL_PROC_MSC}
01532  * @mmsc{@ref BLE_GAP_CENTRAL_SEC_REQ_MSC}
01533  * @endmscs
01534  *
01535  * @param[in] conn_handle Connection handle.
01536  * @param[in] p_master_id Pointer to a @ref ble_gap_master_id_t master identification structure.
01537  * @param[in] p_enc_info  Pointer to a @ref ble_gap_enc_info_t encryption information structure.
01538  *
01539  * @retval ::NRF_SUCCESS Successfully initiated authentication procedure.
01540  * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
01541  * @retval ::NRF_ERROR_INVALID_STATE Invalid state to perform operation.
01542  * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid connection handle supplied.
01543  * @retval ::BLE_ERROR_INVALID_ROLE Operation is not supported in the Peripheral role.
01544  * @retval ::NRF_ERROR_BUSY Procedure already in progress or not allowed at this time, wait for pending procedures to complete and retry.
01545  */
01546 SVCALL(SD_BLE_GAP_ENCRYPT, uint32_t, sd_ble_gap_encrypt(uint16_t conn_handle, ble_gap_master_id_t const *p_master_id, ble_gap_enc_info_t const *p_enc_info));
01547 
01548 
01549 /**@brief Reply with GAP security information.
01550  *
01551  * @details This function is only used to reply to a @ref BLE_GAP_EVT_SEC_INFO_REQUEST, calling it at other times will result in @ref NRF_ERROR_INVALID_STATE.
01552  * @note    If the call returns an error code, the request is still pending, and the reply call may be repeated with corrected parameters.
01553  * @note    Data signing is not yet supported, and p_sign_info must therefore be NULL.
01554  *
01555  * @mscs
01556  * @mmsc{@ref BLE_GAP_PERIPH_ENC_MSC}
01557  * @endmscs
01558  *
01559  * @param[in] conn_handle Connection handle.
01560  * @param[in] p_enc_info Pointer to a @ref ble_gap_enc_info_t encryption information structure. May be NULL to signal none is available.
01561  * @param[in] p_id_info Pointer to a @ref ble_gap_irk_t identity information structure. May be NULL to signal none is available.
01562  * @param[in] p_sign_info Pointer to a @ref ble_gap_sign_info_t signing information structure. May be NULL to signal none is available.
01563  *
01564  * @retval ::NRF_SUCCESS Successfully accepted security information.
01565  * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied.
01566  * @retval ::NRF_ERROR_INVALID_STATE Invalid state to perform operation.
01567  * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid connection handle supplied.
01568  */
01569 SVCALL(SD_BLE_GAP_SEC_INFO_REPLY, uint32_t, sd_ble_gap_sec_info_reply(uint16_t conn_handle, ble_gap_enc_info_t const *p_enc_info, ble_gap_irk_t const *p_id_info, ble_gap_sign_info_t const *p_sign_info));
01570 
01571 
01572 /**@brief Get the current connection security.
01573  *
01574  * @param[in]  conn_handle Connection handle.
01575  * @param[out] p_conn_sec  Pointer to a @ref ble_gap_conn_sec_t structure to be filled in.
01576  *
01577  * @retval ::NRF_SUCCESS Current connection security successfully retrieved.
01578  * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
01579  * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid connection handle supplied.
01580  */
01581 SVCALL(SD_BLE_GAP_CONN_SEC_GET, uint32_t, sd_ble_gap_conn_sec_get(uint16_t conn_handle, ble_gap_conn_sec_t *p_conn_sec));
01582 
01583 
01584 /**@brief Start reporting the received signal strength to the application.
01585  *
01586  * A new event is reported whenever the RSSI value changes, until @ref sd_ble_gap_rssi_stop is called.
01587  *
01588  * @events
01589  * @event{@ref BLE_GAP_EVT_RSSI_CHANGED, New RSSI data available. How often the event is generated is
01590                                          dependent on the settings of the <code>threshold_dbm</code>
01591                                          and <code>skip_count</code> input parameters.}
01592  * @endevents
01593  *
01594  * @mscs
01595  * @mmsc{@ref BLE_GAP_CENTRAL_RSSI_READ_MSC}
01596  * @mmsc{@ref BLE_GAP_RSSI_FILT_MSC}
01597  * @endmscs
01598  *
01599  * @param[in] conn_handle        Connection handle.
01600  * @param[in] threshold_dbm      Minimum change in dBm before triggering the @ref BLE_GAP_EVT_RSSI_CHANGED event. Events are disabled if threshold_dbm equals @ref BLE_GAP_RSSI_THRESHOLD_INVALID.
01601  * @param[in] skip_count         Number of RSSI samples with a change of threshold_dbm or more before sending a new @ref BLE_GAP_EVT_RSSI_CHANGED event.
01602  *
01603  * @retval ::NRF_SUCCESS                   Successfully activated RSSI reporting.
01604  * @retval ::NRF_ERROR_INVALID_STATE       Disconnection in progress. Invalid state to perform operation.
01605  * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid connection handle supplied.
01606  */
01607 SVCALL(SD_BLE_GAP_RSSI_START, uint32_t, sd_ble_gap_rssi_start(uint16_t conn_handle, uint8_t threshold_dbm, uint8_t skip_count));
01608 
01609 
01610 /**@brief Stop reporting the received signal strength.
01611  *
01612  * @note An RSSI change detected before the call but not yet received by the application
01613  * may be reported after @ref sd_ble_gap_rssi_stop has been called.
01614  *
01615  * @mscs
01616  * @mmsc{@ref BLE_GAP_CENTRAL_RSSI_READ_MSC}
01617  * @mmsc{@ref BLE_GAP_RSSI_FILT_MSC}
01618  * @endmscs
01619  *
01620  * @param[in] conn_handle Connection handle.
01621  *
01622  * @retval ::NRF_SUCCESS                   Successfully deactivated RSSI reporting.
01623  * @retval ::NRF_ERROR_INVALID_STATE       Invalid state to perform operation.
01624  * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid connection handle supplied.
01625  */
01626 SVCALL(SD_BLE_GAP_RSSI_STOP, uint32_t, sd_ble_gap_rssi_stop(uint16_t conn_handle));
01627 
01628 
01629 /**@brief Get the received signal strength for the last connection event.
01630  *
01631  * @ref sd_ble_gap_rssi_start must be called to start reporting RSSI before using this function. @ref NRF_ERROR_NOT_FOUND
01632  * will be returned until RSSI was sampled for the first time after calling @ref sd_ble_gap_rssi_start.
01633  *
01634  * @mscs
01635  * @mmsc{@ref BLE_GAP_CENTRAL_RSSI_READ_MSC}
01636  * @endmscs
01637  *
01638  * @param[in]  conn_handle Connection handle.
01639  * @param[out] p_rssi      Pointer to the location where the RSSI measurement shall be stored.
01640  *
01641  * @retval ::NRF_SUCCESS                   Successfully read the RSSI.
01642  * @retval ::NRF_ERROR_NOT_FOUND           No sample is available.
01643  * @retval ::NRF_ERROR_INVALID_ADDR        Invalid pointer supplied.
01644  * @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid connection handle supplied.
01645  * @retval ::NRF_ERROR_INVALID_STATE       RSSI reporting is not ongoing, or disconnection in progress.
01646  */
01647 SVCALL(SD_BLE_GAP_RSSI_GET, uint32_t, sd_ble_gap_rssi_get(uint16_t conn_handle, int8_t *p_rssi));
01648 
01649 
01650 /**@brief Start scanning (GAP Discovery procedure, Observer Procedure).
01651  *
01652  * @note To use the currently active whitelist set p_scan_params->p_whitelist to NULL.
01653  *
01654  * @events
01655  * @event{@ref BLE_GAP_EVT_ADV_REPORT, An advertising or scan response packet has been received.}
01656  * @event{@ref BLE_GAP_EVT_TIMEOUT, Scanner has timed out.}
01657  * @endevents
01658  *
01659  * @mscs
01660  * @mmsc{@ref BLE_GAP_SCAN_MSC}
01661  * @mmsc{@ref BLE_GAP_WL_SHARE_MSC}
01662  * @endmscs
01663  *
01664  * @param[in] p_scan_params Pointer to scan parameters structure.
01665  *
01666  * @retval ::NRF_SUCCESS Successfully initiated scanning procedure.
01667  * @retval ::NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
01668  * @retval ::NRF_ERROR_INVALID_STATE Invalid state to perform operation.
01669  * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied.
01670  * @retval ::NRF_ERROR_BUSY The stack is busy, process pending events and retry.
01671  * @retval ::BLE_ERROR_GAP_WHITELIST_IN_USE Unable to replace the whitelist while another operation is using it.
01672  * @retval ::NRF_ERROR_RESOURCES Not enough BLE role slots available.
01673  *                               Stop one or more currently active roles (Central, Peripheral or Broadcaster) and try again
01674  */
01675 SVCALL(SD_BLE_GAP_SCAN_START, uint32_t, sd_ble_gap_scan_start(ble_gap_scan_params_t const *p_scan_params));
01676 
01677 
01678 /**@brief Stop scanning (GAP Discovery procedure, Observer Procedure).
01679  *
01680  * @mscs
01681  * @mmsc{@ref BLE_GAP_SCAN_MSC}
01682  * @mmsc{@ref BLE_GAP_WL_SHARE_MSC}
01683  * @endmscs
01684  *
01685  * @retval ::NRF_SUCCESS Successfully stopped scanning procedure.
01686  * @retval ::NRF_ERROR_INVALID_STATE Invalid state to perform operation (most probably not in scanning state).
01687  */
01688 SVCALL(SD_BLE_GAP_SCAN_STOP, uint32_t, sd_ble_gap_scan_stop(void));
01689 
01690 
01691 /**@brief Create a connection (GAP Link Establishment).
01692  *
01693  * @note To use the currently active whitelist set p_scan_params->p_whitelist to NULL.
01694  * @note If a scanning procedure is currently in progress it will be automatically stopped when calling this function.
01695  *
01696  * @mscs
01697  * @mmsc{@ref BLE_GAP_WL_SHARE_MSC}
01698  * @mmsc{@ref BLE_GAP_CENTRAL_CONN_MSC}
01699  * @endmscs
01700  *
01701  * @param[in] p_peer_addr   Pointer to peer address. If the selective bit is set in @ref ble_gap_scan_params_t, then this must be NULL.
01702  * @param[in] p_scan_params Pointer to scan parameters structure.
01703  * @param[in] p_conn_params Pointer to desired connection parameters.
01704  *
01705  * @retval ::NRF_SUCCESS Successfully initiated connection procedure.
01706  * @retval ::NRF_ERROR_INVALID_ADDR Invalid parameter(s) pointer supplied.
01707  * @retval ::NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied.
01708  * @retval ::NRF_ERROR_INVALID_STATE Invalid state to perform operation.
01709  * @retval ::BLE_ERROR_GAP_INVALID_BLE_ADDR Invalid Peer address.
01710  * @retval ::NRF_ERROR_CONN_COUNT The limit of available connections has been reached.
01711  * @retval ::NRF_ERROR_NO_MEM The configured memory pool (see @ref ble_conn_bw_counts_t) is not large enough for the
01712  *                            bandwidth selected for this connection.
01713  * @retval ::NRF_ERROR_BUSY The stack is busy, process pending events and retry. If another connection is being established
01714  *                          wait for the corresponding @ref BLE_GAP_EVT_CONNECTED event before calling again.
01715  * @retval ::BLE_ERROR_GAP_WHITELIST_IN_USE Unable to replace the whitelist while another operation is using it.
01716  * @retval ::NRF_ERROR_RESOURCES Not enough BLE role slots available.
01717  *                               Stop one or more currently active roles (Central, Peripheral or Broadcaster) and try again
01718  */
01719 SVCALL(SD_BLE_GAP_CONNECT, uint32_t, sd_ble_gap_connect(ble_gap_addr_t const *p_peer_addr, ble_gap_scan_params_t const *p_scan_params, ble_gap_conn_params_t const *p_conn_params));
01720 
01721 
01722 /**@brief Cancel a connection establishment.
01723  *
01724  * @mscs
01725  * @mmsc{@ref BLE_GAP_CENTRAL_CONN_MSC}
01726  * @endmscs
01727  *
01728  * @retval ::NRF_SUCCESS Successfully cancelled an ongoing connection procedure.
01729  * @retval ::NRF_ERROR_INVALID_STATE Invalid state to perform operation.
01730  */
01731 SVCALL(SD_BLE_GAP_CONNECT_CANCEL, uint32_t, sd_ble_gap_connect_cancel(void));
01732 
01733 /** @} */
01734 
01735 #ifdef __cplusplus
01736 }
01737 #endif
01738 #endif // BLE_GAP_H__
01739 
01740 /**
01741   @}
01742 */
01743