ble_gap.h

00001 /* Copyright (c) 2011 Nordic Semiconductor. All Rights Reserved.
00002  *
00003  * The information contained herein is confidential property of Nordic Semiconductor. The use,
00004  * copying, transfer or disclosure of such information is prohibited except by express written
00005  * agreement with Nordic Semiconductor.
00006  *
00007  */
00008 /**
00009   @addtogroup BLE_GAP Generic Access Profile (GAP)
00010   @{
00011   @brief Definitions and prototypes for the GAP interface.
00012  */
00013 
00014 #ifndef BLE_GAP_H__
00015 #define BLE_GAP_H__
00016 
00017 #include "ble_types.h"
00018 #include "ble_ranges.h"
00019 #include "nrf_svc.h"
00020 
00021 
00022 /**@addtogroup BLE_GAP_ENUMERATIONS Enumerations 
00023  * @{ */
00024 
00025 /**@brief GAP API SVC numbers.
00026  */
00027 enum BLE_GAP_SVCS
00028 {
00029   SD_BLE_GAP_ADDRESS_SET  = BLE_GAP_SVC_BASE,  /**< Set own Bluetooth Address. */
00030   SD_BLE_GAP_ADDRESS_GET,                      /**< Get own Bluetooth Address. */
00031   SD_BLE_GAP_ADV_DATA_SET,                     /**< Set Advertisement Data. */
00032   SD_BLE_GAP_ADV_START,                        /**< Start Advertising. */
00033   SD_BLE_GAP_ADV_STOP,                         /**< Stop Advertising. */
00034   SD_BLE_GAP_CONN_PARAM_UPDATE,                /**< Connection Parameter Update. */
00035   SD_BLE_GAP_DISCONNECT,                       /**< Disconnect. */
00036   SD_BLE_GAP_TX_POWER_SET,                     /**< Set TX Power. */
00037   SD_BLE_GAP_APPEARANCE_SET,                   /**< Set Appearance. */
00038   SD_BLE_GAP_APPEARANCE_GET,                   /**< Get Appearance. */
00039   SD_BLE_GAP_PPCP_SET,                         /**< Set PPCP. */
00040   SD_BLE_GAP_PPCP_GET,                         /**< Get PPCP. */
00041   SD_BLE_GAP_DEVICE_NAME_SET,                  /**< Set Device Name. */
00042   SD_BLE_GAP_DEVICE_NAME_GET,                  /**< Get Device Name. */
00043   SD_BLE_GAP_AUTHENTICATE,                     /**< Initiate Pairing/Bonding. */
00044   SD_BLE_GAP_SEC_PARAMS_REPLY,                 /**< Reply with Security Parameters. */
00045   SD_BLE_GAP_AUTH_KEY_REPLY,                   /**< Reply with an authentication key. */
00046   SD_BLE_GAP_SEC_INFO_REPLY,                   /**< Reply with Security Information. */
00047   SD_BLE_GAP_CONN_SEC_GET,                     /**< Obtain connection security level. */
00048   SD_BLE_GAP_RSSI_START,                       /**< Start reporting of changes in RSSI. */ 
00049   SD_BLE_GAP_RSSI_STOP,                        /**< Stop reporting of changes in RSSI. */ 
00050 };
00051 /**@} */
00052 
00053 /**@addtogroup BLE_GAP_DEFINES Defines
00054  * @{ */
00055 
00056 /**@defgroup BLE_ERRORS_GAP SVC return values specific to GAP
00057  * @{ */
00058 #define BLE_ERROR_GAP_UUID_LIST_MISMATCH            (NRF_GAP_ERR_BASE + 0x000)  /**< UUID list does not contain an integral number of UUIDs. */
00059 #define BLE_ERROR_GAP_DISCOVERABLE_WITH_WHITELIST   (NRF_GAP_ERR_BASE + 0x001)  /**< Use of Whitelist not permitted with discoverable advertising. */
00060 #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. */
00061 /**@} */
00062 
00063 
00064 /**@defgroup BLE_GAP_ROLES GAP Roles
00065  * @note Not explicitly used in peripheral API, but will be relevant for central API.
00066  * @{ */
00067 #define BLE_GAP_ROLE_INVALID     0x0            /**< Invalid Role. */
00068 #define BLE_GAP_ROLE_PERIPH      0x1            /**< Peripheral Role. */
00069 #define BLE_GAP_ROLE_CENTRAL     0x2            /**< Central Role. */
00070 /**@} */
00071 
00072 
00073 /**@defgroup BLE_GAP_TIMEOUT_SOURCES GAP Timeout sources
00074  * @{ */
00075 #define BLE_GAP_TIMEOUT_SRC_ADVERTISEMENT              0x00 /**< Advertisement timeout. */
00076 #define BLE_GAP_TIMEOUT_SRC_SECURITY_REQUEST           0x01 /**< Security request timeout. */
00077 /**@} */
00078 
00079 
00080 /**@defgroup BLE_GAP_ADDR_TYPES GAP Address types
00081  * @{ */
00082 #define BLE_GAP_ADDR_TYPE_PUBLIC                        0x00 /**< Public address. */
00083 #define BLE_GAP_ADDR_TYPE_RANDOM_STATIC                 0x01 /**< Random Static address. */
00084 #define BLE_GAP_ADDR_TYPE_RANDOM_PRIVATE_RESOLVABLE     0x02 /**< Private Resolvable address. */
00085 #define BLE_GAP_ADDR_TYPE_RANDOM_PRIVATE_NON_RESOLVABLE 0x03 /**< Private Non-Resolvable address. */
00086 /**@} */
00087 
00088 /**@defgroup BLE_GAP_ADDR_CYCLE_MODES GAP Address cycle modes
00089  * @{ */
00090 #define BLE_GAP_ADDR_CYCLE_MODE_NONE      0x00 /**< Set addresses directly, no automatic address cycling. */
00091 #define BLE_GAP_ADDR_CYCLE_MODE_AUTO      0x01 /**< Automatically generate and update private addresses. */
00092 /** @} */
00093 
00094 /**@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.  */
00095 #define BLE_GAP_DEFAULT_PRIVATE_ADDR_CYCLE_INTERVAL_S (60 * 15)
00096 
00097 /** @brief BLE address length. */
00098 #define BLE_GAP_ADDR_LEN            6
00099 
00100 
00101 /**@defgroup BLE_GAP_AD_TYPE_DEFINITIONS GAP Advertising and Scan Response Data format
00102  * @note Found at https://www.bluetooth.org/Technical/AssignedNumbers/generic_access_profile.htm
00103  * @{ */
00104 #define BLE_GAP_AD_TYPE_FLAGS                               0x01 /**< Flags for discoverability. */
00105 #define BLE_GAP_AD_TYPE_16BIT_SERVICE_UUID_MORE_AVAILABLE   0x02 /**< Partial list of 16 bit service UUIDs. */
00106 #define BLE_GAP_AD_TYPE_16BIT_SERVICE_UUID_COMPLETE         0x03 /**< Complete list of 16 bit service UUIDs. */
00107 #define BLE_GAP_AD_TYPE_32BIT_SERVICE_UUID_MORE_AVAILABLE   0x04 /**< Partial list of 32 bit service UUIDs. */
00108 #define BLE_GAP_AD_TYPE_32BIT_SERVICE_UUID_COMPLETE         0x05 /**< Complete list of 32 bit service UUIDs. */
00109 #define BLE_GAP_AD_TYPE_128BIT_SERVICE_UUID_MORE_AVAILABLE  0x06 /**< Partial list of 128 bit service UUIDs. */
00110 #define BLE_GAP_AD_TYPE_128BIT_SERVICE_UUID_COMPLETE        0x07 /**< Complete list of 128 bit service UUIDs. */
00111 #define BLE_GAP_AD_TYPE_SHORT_LOCAL_NAME                    0x08 /**< Short local device name. */
00112 #define BLE_GAP_AD_TYPE_COMPLETE_LOCAL_NAME                 0x09 /**< Complete local device name. */
00113 #define BLE_GAP_AD_TYPE_TX_POWER_LEVEL                      0x0A /**< Transmit power level. */
00114 #define BLE_GAP_AD_TYPE_CLASS_OF_DEVICE                     0x0D /**< Class of device. */
00115 #define BLE_GAP_AD_TYPE_SIMPLE_PAIRING_HASH_C               0x0E /**< Simple Pairing Hash C. */
00116 #define BLE_GAP_AD_TYPE_SIMPLE_PAIRING_RANDOMIZER_R         0x0F /**< Simple Pairing Randomizer R. */
00117 #define BLE_GAP_AD_TYPE_SECURITY_MANAGER_TK_VALUE           0x10 /**< Security Manager TK Value. */
00118 #define BLE_GAP_AD_TYPE_SECURITY_MANAGER_OOB_FLAGS          0x11 /**< Security Manager Out Of Band Flags. */
00119 #define BLE_GAP_AD_TYPE_SLAVE_CONNECTION_INTERVAL_RANGE     0x12 /**< Slave Connection Interval Range. */
00120 #define BLE_GAP_AD_TYPE_SOLICITED_SERVICE_UUIDS_16BIT       0x14 /**< List of 16-bit Service Solicitation UUIDs. */
00121 #define BLE_GAP_AD_TYPE_SOLICITED_SERVICE_UUIDS_128BIT      0x15 /**< List of 128-bit Service Solicitation UUIDs. */
00122 #define BLE_GAP_AD_TYPE_SERVICE_DATA                        0x16 /**< Service Data - 16-bit UUID. */
00123 #define BLE_GAP_AD_TYPE_PUBLIC_TARGET_ADDRESS               0x17 /**< Public Target Address. */
00124 #define BLE_GAP_AD_TYPE_RANDOM_TARGET_ADDRESS               0x18 /**< Random Target Address. */
00125 #define BLE_GAP_AD_TYPE_APPEARANCE                          0x19 /**< Appearance. */
00126 #define BLE_GAP_AD_TYPE_ADVERTISING_INTERVAL                0x1A /**< Advertising Interval. */ 
00127 #define BLE_GAP_AD_TYPE_LE_BLUETOOTH_DEVICE_ADDRESS         0x1B /**< LE Bluetooth Device Address. */
00128 #define BLE_GAP_AD_TYPE_LE_ROLE                             0x1C /**< LE Role. */
00129 #define BLE_GAP_AD_TYPE_SIMPLE_PAIRING_HASH_C256            0x1D /**< Simple Pairing Hash C-256. */
00130 #define BLE_GAP_AD_TYPE_SIMPLE_PAIRING_RANDOMIZER_R256      0x1E /**< Simple Pairing Randomizer R-256. */
00131 #define BLE_GAP_AD_TYPE_SERVICE_DATA_32BIT_UUID             0x20 /**< Service Data - 32-bit UUID. */
00132 #define BLE_GAP_AD_TYPE_SERVICE_DATA_128BIT_UUID            0x21 /**< Service Data - 128-bit UUID. */
00133 #define BLE_GAP_AD_TYPE_3D_INFORMATION_DATA                 0x3D /**< 3D Information Data. */
00134 #define BLE_GAP_AD_TYPE_MANUFACTURER_SPECIFIC_DATA          0xFF /**< Manufacturer Specific Data. */
00135 /**@} */
00136 
00137 
00138 /**@defgroup BLE_GAP_ADV_FLAGS GAP Advertisement Flags
00139  * @{ */
00140 #define BLE_GAP_ADV_FLAG_LE_LIMITED_DISC_MODE         (0x01)   /**< LE Limited Discoverable Mode. */
00141 #define BLE_GAP_ADV_FLAG_LE_GENERAL_DISC_MODE         (0x02)   /**< LE General Discoverable Mode. */
00142 #define BLE_GAP_ADV_FLAG_BR_EDR_NOT_SUPPORTED         (0x04)   /**< BR/EDR not supported. */
00143 #define BLE_GAP_ADV_FLAG_LE_BR_EDR_CONTROLLER         (0x08)   /**< Simultaneous LE and BR/EDR, Controller. */
00144 #define BLE_GAP_ADV_FLAG_LE_BR_EDR_HOST               (0x10)   /**< Simultaneous LE and BR/EDR, Host. */
00145 #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. */
00146 #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. */
00147 /**@} */
00148 
00149 
00150 /**@defgroup BLE_GAP_ADV_INTERVALS GAP Advertising interval max and min
00151  * @{ */
00152 #define BLE_GAP_ADV_INTERVAL_MIN        0x0020 /**< Minimum Advertising interval in 625 us units, i.e. 20 ms. */
00153 #define BLE_GAP_ADV_NONCON_INTERVAL_MIN 0x00A0 /**< Minimum Advertising interval in 625 us units for non connectable mode, i.e. 100 ms. */
00154 #define BLE_GAP_ADV_INTERVAL_MAX        0x4000 /**< Maximum Advertising interval in 625 us units, i.e. 10.24 s. */
00155  /**@}  */
00156 
00157 
00158 /**@brief Maximum size of advertising data in octets. */
00159 #define  BLE_GAP_ADV_MAX_SIZE       31
00160 
00161 
00162 /**@defgroup BLE_GAP_ADV_TYPES GAP Advertising types
00163  * @{ */
00164 #define BLE_GAP_ADV_TYPE_ADV_IND          0x00   /**< Connectable undirected. */
00165 #define BLE_GAP_ADV_TYPE_ADV_DIRECT_IND   0x01   /**< Connectable directed. */
00166 #define BLE_GAP_ADV_TYPE_ADV_SCAN_IND     0x02   /**< Scannable undirected. */
00167 #define BLE_GAP_ADV_TYPE_ADV_NONCONN_IND  0x03   /**< Non connectable undirected. */
00168 /**@} */
00169 
00170 
00171 /**@defgroup BLE_GAP_ADV_FILTER_POLICIES GAP Advertising filter policies
00172  * @{ */
00173 #define BLE_GAP_ADV_FP_ANY                0x00   /**< Allow scan requests and connect requests from any device. */
00174 #define BLE_GAP_ADV_FP_FILTER_SCANREQ     0x01   /**< Filter scan requests with whitelist. */
00175 #define BLE_GAP_ADV_FP_FILTER_CONNREQ     0x02   /**< Filter connect requests with whitelist. */
00176 #define BLE_GAP_ADV_FP_FILTER_BOTH        0x03   /**< Filter both scan and connect requests with whitelist. */
00177 /**@} */
00178 
00179 
00180 /**@defgroup BLE_GAP_ADV_TIMEOUT_VALUES GAP Advertising timeout values
00181  * @{ */
00182 #define BLE_GAP_ADV_TIMEOUT_LIMITED_MAX      180 /**< Maximum advertising time in limited discoverable mode (TGAP(lim_adv_timeout) = 180s in spec (Addendum 2)). */
00183 #define BLE_GAP_ADV_TIMEOUT_GENERAL_UNLIMITED  0 /**< Unlimited advertising in general discoverable mode. */
00184 /**@} */
00185 
00186 
00187 /**@defgroup BLE_GAP_DISC_MODES GAP Discovery modes
00188  * @{ */
00189 #define BLE_GAP_DISC_MODE_NOT_DISCOVERABLE  0x00   /**< Not discoverable discovery Mode. */
00190 #define BLE_GAP_DISC_MODE_LIMITED           0x01   /**< Limited Discovery Mode. */
00191 #define BLE_GAP_DISC_MODE_GENERAL           0x02   /**< General Discovery Mode. */
00192 /**@} */
00193 
00194 /**@defgroup BLE_GAP_IO_CAPS GAP IO Capabilities
00195  * @{ */
00196 #define BLE_GAP_IO_CAPS_DISPLAY_ONLY      0x00   /**< Display Only. */
00197 #define BLE_GAP_IO_CAPS_DISPLAY_YESNO     0x01   /**< Display and Yes/No entry. */
00198 #define BLE_GAP_IO_CAPS_KEYBOARD_ONLY     0x02   /**< Keyboard Only. */
00199 #define BLE_GAP_IO_CAPS_NONE              0x03   /**< No I/O capabilities. */
00200 #define BLE_GAP_IO_CAPS_KEYBOARD_DISPLAY  0x04   /**< Keyboard and Display. */
00201 /**@} */
00202 
00203 
00204 /**@defgroup BLE_GAP_AUTH_KEY_TYPES GAP Authentication Key Types
00205  * @{ */
00206 #define BLE_GAP_AUTH_KEY_TYPE_NONE        0x00   /**< No key (may be used to reject). */
00207 #define BLE_GAP_AUTH_KEY_TYPE_PASSKEY     0x01   /**< 6-digit Passkey. */
00208 #define BLE_GAP_AUTH_KEY_TYPE_OOB         0x02   /**< Out Of Band data. */
00209 /**@} */
00210 
00211 /**@defgroup BLE_GAP_SEC_STATUS GAP Security status
00212  * @{ */
00213 #define BLE_GAP_SEC_STATUS_SUCCESS                0x00  /**< Successful parameters. */
00214 #define BLE_GAP_SEC_STATUS_TIMEOUT                0x01  /**< Procedure timed out. */
00215 #define BLE_GAP_SEC_STATUS_PDU_INVALID            0x02  /**< Invalid PDU received. */
00216 #define BLE_GAP_SEC_STATUS_PASSKEY_ENTRY_FAILED   0x81  /**< Passkey entry failed (user cancelled or other). */
00217 #define BLE_GAP_SEC_STATUS_OOB_NOT_AVAILABLE      0x82  /**< Out of Band Key not available. */
00218 #define BLE_GAP_SEC_STATUS_AUTH_REQ               0x83  /**< Authentication requirements not met. */
00219 #define BLE_GAP_SEC_STATUS_CONFIRM_VALUE          0x84  /**< Confirm value failed. */
00220 #define BLE_GAP_SEC_STATUS_PAIRING_NOT_SUPP       0x85  /**< Pairing not supported.  */
00221 #define BLE_GAP_SEC_STATUS_ENC_KEY_SIZE           0x86  /**< Encryption key size. */
00222 #define BLE_GAP_SEC_STATUS_SMP_CMD_UNSUPPORTED    0x87  /**< Unsupported SMP command. */
00223 #define BLE_GAP_SEC_STATUS_UNSPECIFIED            0x88  /**< Unspecified reason. */
00224 #define BLE_GAP_SEC_STATUS_REPEATED_ATTEMPTS      0x89  /**< Too little time elapsed since last attempt. */
00225 #define BLE_GAP_SEC_STATUS_INVALID_PARAMS         0x8A  /**< Invalid parameters. */
00226 /**@} */
00227 
00228 /**@defgroup BLE_GAP_SEC_STATUS_SOURCES GAP Security status sources
00229  * @{ */
00230 #define BLE_GAP_SEC_STATUS_SOURCE_LOCAL           0x00  /**< Local failure. */
00231 #define BLE_GAP_SEC_STATUS_SOURCE_REMOTE          0x01  /**< Remote failure. */
00232 /**@} */
00233 
00234 /**@defgroup BLE_GAP_CP_LIMITS GAP Connection Parameters Limits
00235  * @{ */
00236 #define BLE_GAP_CP_MIN_CONN_INTVL_NONE           0xFFFF  /**< No new minimum connction interval specified in connect parameters. */
00237 #define BLE_GAP_CP_MIN_CONN_INTVL_MIN            0x0006  /**< Lowest mimimum connection interval permitted, in units of 1.25 ms, i.e. 7.5 ms. */
00238 #define BLE_GAP_CP_MIN_CONN_INTVL_MAX            0x0C80  /**< Highest minimum connection interval permitted, in units of 1.25 ms, i.e. 4 s. */
00239 #define BLE_GAP_CP_MAX_CONN_INTVL_NONE           0xFFFF  /**< No new maximum connction interval specified in connect parameters. */
00240 #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. */
00241 #define BLE_GAP_CP_MAX_CONN_INTVL_MAX            0x0C80  /**< Highest maximum connection interval permitted, in units of 1.25 ms, i.e. 4 s. */
00242 #define BLE_GAP_CP_SLAVE_LATENCY_MAX             0x03E8  /**< Highest slave latency permitted, in connection events. */
00243 #define BLE_GAP_CP_CONN_SUP_TIMEOUT_NONE         0xFFFF  /**< No new supervision timeout specified in connect parameters. */
00244 #define BLE_GAP_CP_CONN_SUP_TIMEOUT_MIN          0x000A  /**< Lowest supervision timeout permitted, in units of 10 ms, i.e. 100 ms. */
00245 #define BLE_GAP_CP_CONN_SUP_TIMEOUT_MAX          0x0C80  /**< Highest supervision timeout permitted, in units of 10 ms, i.e. 32 s. */
00246 /**@} */
00247 
00248 
00249 /**@brief GAP device name maximum length. */
00250 #define BLE_GAP_DEVNAME_MAX_LEN           31
00251 
00252 
00253 /**@defgroup BLE_GAP_CONN_SEC_MODE_SET_MACROS GAP attribute security requirement setters
00254  *
00255  * See @ref ble_gap_conn_sec_mode_t.
00256  * @{ */
00257 /**@brief Set sec_mode pointed to by ptr to have no access rights.*/
00258 #define BLE_GAP_CONN_SEC_MODE_SET_NO_ACCESS(ptr)         do {(ptr)->sm = 0; (ptr)->lv = 0;} while(0)
00259 /**@brief Set sec_mode pointed to by ptr to require no protection, open link.*/
00260 #define BLE_GAP_CONN_SEC_MODE_SET_OPEN(ptr)              do {(ptr)->sm = 1; (ptr)->lv = 1;} while(0)
00261 /**@brief Set sec_mode pointed to by ptr to require encryption, but no MITM protection.*/
00262 #define BLE_GAP_CONN_SEC_MODE_SET_ENC_NO_MITM(ptr)       do {(ptr)->sm = 1; (ptr)->lv = 2;} while(0)
00263 /**@brief Set sec_mode pointed to by ptr to require encryption and MITM protection.*/
00264 #define BLE_GAP_CONN_SEC_MODE_SET_ENC_WITH_MITM(ptr)     do {(ptr)->sm = 1; (ptr)->lv = 3;} while(0)
00265 /**@brief Set sec_mode pointed to by ptr to require signing or encryption, no MITM protection needed.*/
00266 #define BLE_GAP_CONN_SEC_MODE_SET_SIGNED_NO_MITM(ptr)    do {(ptr)->sm = 2; (ptr)->lv = 1;} while(0)
00267 /**@brief Set sec_mode pointed to by ptr to require signing or encryption with MITM protection.*/
00268 #define BLE_GAP_CONN_SEC_MODE_SET_SIGNED_WITH_MITM(ptr)  do {(ptr)->sm = 2; (ptr)->lv = 2;} while(0)
00269 /**@} */
00270 
00271 
00272 /**@brief GAP Security Key Length. */
00273 #define BLE_GAP_SEC_KEY_LEN 16
00274 
00275 /**@brief GAP Passkey Length. */
00276 #define BLE_GAP_PASSKEY_LEN 6
00277 
00278 /**@brief Maximum amount of addresses in a whitelist. */
00279 #define BLE_GAP_WHITELIST_ADDR_MAX_COUNT (8)
00280 
00281 /**@brief Maximum amount of IRKs in a whitelist.
00282  * @note  The number of IRKs is limited to 8, even if the hardware supports more.
00283  */
00284 #define BLE_GAP_WHITELIST_IRK_MAX_COUNT (8)
00285 
00286 /**@defgroup GAP_SEC_MODES GAP Security Modes
00287  * @{ */
00288 #define BLE_GAP_SEC_MODE 0x00 /**< No key (may be used to reject). */
00289 /**@} */
00290 
00291 /**@} */
00292 
00293 /**@addtogroup BLE_GAP_STRUCTURES Structures
00294  * @{ */
00295 
00296 /**@brief Bluetooth Low Energy address. */
00297 typedef struct
00298 {
00299   uint8_t addr_type;                    /**< See @ref BLE_GAP_ADDR_TYPES. */
00300   uint8_t addr[BLE_GAP_ADDR_LEN];       /**< 48-bit address, LSB format. */
00301 } ble_gap_addr_t;
00302 
00303 
00304 /**@brief GAP connection parameters.
00305  *
00306  * @note  When ble_conn_params_t is received in an event, both min_conn_interval and
00307  *        max_conn_interval will be equal to the connection interval set by the central.
00308  */
00309 typedef struct
00310 {
00311   uint16_t min_conn_interval;         /**< Minimum Connection Interval in 1.25 ms units, see @ref BLE_GAP_CP_LIMITS.*/
00312   uint16_t max_conn_interval;         /**< Maximum Connection Interval in 1.25 ms units, see @ref BLE_GAP_CP_LIMITS.*/
00313   uint16_t slave_latency;             /**< Slave Latency in number of connection events, see @ref BLE_GAP_CP_LIMITS.*/
00314   uint16_t conn_sup_timeout;          /**< Connection Supervision Timeout in 10 ms units, see @ref BLE_GAP_CP_LIMITS.*/
00315 } ble_gap_conn_params_t;
00316 
00317 
00318 /**@brief GAP link requirements.
00319  *
00320  * See Bluetooth Core specification, Volume 3 Part C 10.2 for details.
00321  *
00322  * Security Mode 0 Level 0: No access permissions at all (this level is not defined by the Bluetooth Core specification).\n
00323  * Security Mode 1 Level 1: No security is needed (aka open link).\n
00324  * Security Mode 1 Level 2: Encrypted link required, MITM protection not necessary.\n
00325  * Security Mode 1 Level 3: MITM protected encrypted link required.\n
00326  * Security Mode 2 Level 1: Signing or encryption required, MITM protection not necessary.\n
00327  * Security Mode 2 Level 2: MITM protected signing required, unless link is MITM protected encrypted.\n
00328  */
00329 typedef struct
00330 {
00331   uint8_t sm : 4;                     /**< Security Mode (1 or 2), 0 for no permissions at all. */
00332   uint8_t lv : 4;                     /**< Level (1, 2 or 3), 0 for no permissions at all. */
00333 
00334 } ble_gap_conn_sec_mode_t;
00335 
00336 
00337 /**@brief GAP connection security status.*/
00338 typedef struct
00339 {
00340   ble_gap_conn_sec_mode_t sec_mode;           /**< Currently active security mode for this connection.*/
00341   uint8_t                 encr_key_size;      /**< Length of currently active encryption key, 7 to 16 octets (only applicable for bonding procedures). */
00342 } ble_gap_conn_sec_t;
00343 
00344 
00345 /**@brief Identity Resolving Key. */
00346 typedef struct
00347 {
00348   uint8_t irk[BLE_GAP_SEC_KEY_LEN];   /**< Array containing IRK. */
00349 } ble_gap_irk_t;
00350 
00351 
00352 /**@brief Whitelist structure. */
00353 typedef struct
00354 {
00355   ble_gap_addr_t   ** pp_addrs;        /**< Pointer to array of device address pointers, pointing to addresses to be used in whitelist. NULL if none are given. */
00356   uint8_t             addr_count;      /**< Count of device addresses in array, up to @ref BLE_GAP_WHITELIST_ADDR_MAX_COUNT. */
00357   ble_gap_irk_t    ** pp_irks;         /**< Pointer to array of Identity Resolving Key (IRK) pointers, each pointing to an IRK in the whitelist. NULL if none are given. */
00358   uint8_t             irk_count;       /**< Count of IRKs in array, up to @ref BLE_GAP_WHITELIST_IRK_MAX_COUNT. */
00359 } ble_gap_whitelist_t;
00360 
00361 
00362 /**@brief GAP advertising parameters.*/
00363 typedef struct
00364 {
00365   uint8_t               type;                 /**< See @ref BLE_GAP_ADV_TYPES. */
00366   ble_gap_addr_t*       p_peer_addr;          /**< For BLE_GAP_CONN_MODE_DIRECTED mode only, known peer address. */
00367   uint8_t               fp;                   /**< Filter Policy, see @ref BLE_GAP_ADV_FILTER_POLICIES. */
00368   ble_gap_whitelist_t * p_whitelist;          /**< Pointer to whitelist, NULL if none is given. */
00369   uint16_t              interval;             /**< Advertising interval between 0x0020 and 0x4000 in 0.625 ms units (20ms to 10.24s), see @ref BLE_GAP_ADV_INTERVALS.
00370                                                    - If type equals @ref BLE_GAP_ADV_TYPE_ADV_DIRECT_IND, this parameter must be set to 0 for high duty cycle directed advertising.
00371                                                    - 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 */
00372   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. */
00373 } ble_gap_adv_params_t;
00374 
00375 
00376 /**@brief GAP scanning parameters. */
00377 typedef struct
00378 {
00379   uint8_t    filter;                    /**< Filter based on discovery mode, see @ref BLE_GAP_DISC_MODES. */
00380   uint8_t    active    : 1;             /**< If 1, perform active scanning (scan requests). */
00381   uint8_t    selective : 1;             /**< If 1, ignore unknown devices (non whitelisted). */
00382   uint16_t   interval;                  /**< Scan interval between 0x0020 and 0x4000 in 0.625ms units (20ms to 10.24s). */
00383   uint16_t   window;                    /**< Scan window between 0x0004 and 0x4000 in 0.625ms units (2.5ms to 10.24s). */
00384   uint16_t   timeout;                   /**< Scan timeout between 0x0001 and 0x3FFF in seconds, 0x0000 disables timeout. */
00385 } ble_gap_scan_params_t;
00386 
00387 
00388 /**@brief GAP security parameters. */
00389 typedef struct
00390 {
00391   uint16_t   timeout;                   /**< Timeout for SMP transactions or Security Request in seconds, see @ref sd_ble_gap_authenticate and @ref sd_ble_gap_sec_params_reply for more information. */
00392   uint8_t    bond    : 1;               /**< Perform bonding. */
00393   uint8_t    mitm    : 1;               /**< Man In The Middle protection required. */
00394   uint8_t    io_caps : 3;               /**< IO capabilities, see @ref BLE_GAP_IO_CAPS. */
00395   uint8_t    oob     : 1;               /**< Out Of Band data available. */
00396   uint8_t    min_key_size;              /**< Minimum encryption key size in octets between 7 and 16. */
00397   uint8_t    max_key_size;              /**< Maximum encryption key size in octets between min_key_size and 16. */
00398 } ble_gap_sec_params_t;
00399 
00400 
00401 /**@brief GAP Encryption Information. */
00402 typedef struct
00403 {
00404   uint16_t  div;                        /**< Encryption Diversifier. */
00405   uint8_t   ltk[BLE_GAP_SEC_KEY_LEN];   /**< Long Term Key. */
00406   uint8_t   auth : 1;                   /**< Authenticated Key. */
00407   uint8_t   ltk_len : 7;                /**< LTK length in octets. */
00408 } ble_gap_enc_info_t;
00409 
00410 
00411 /**@brief GAP Master Identification. */
00412 typedef struct
00413 {
00414   uint16_t  ediv;                       /**< Encrypted Diversifier. */
00415   uint8_t   rand[8];                    /**< Random Number. */
00416 } ble_gap_master_id_t;
00417 
00418 
00419 /**@brief GAP Identity Information. */
00420 typedef struct
00421 {
00422   ble_gap_addr_t  addr;                       /**< Bluetooth address to which this key applies. */
00423   uint8_t         irk[BLE_GAP_SEC_KEY_LEN];   /**< Identity Resolution Key. */
00424 } ble_gap_id_info_t;
00425 
00426 
00427 /**@brief GAP Signing Information. */
00428 typedef struct
00429 {
00430   uint8_t   csrk[BLE_GAP_SEC_KEY_LEN]; /* Connection Signature Resolving Key. */
00431 } ble_gap_sign_info_t;
00432 
00433 
00434 /**@brief GAP Event IDs.
00435  * Those IDs uniquely identify an event coming from the stack to the application.
00436  */
00437 enum BLE_GAP_EVTS
00438 {
00439   BLE_GAP_EVT_CONNECTED  = BLE_GAP_EVT_BASE,    /**< Connection established. */
00440   BLE_GAP_EVT_DISCONNECTED,                     /**< Disconnected from peer. */
00441   BLE_GAP_EVT_CONN_PARAM_UPDATE,                /**< Connection Parameters updated. */
00442   BLE_GAP_EVT_SEC_PARAMS_REQUEST,               /**< Request to provide security parameters. */
00443   BLE_GAP_EVT_SEC_INFO_REQUEST,                 /**< Request to provide security information. */
00444   BLE_GAP_EVT_PASSKEY_DISPLAY,                  /**< Request to display a passkey to the user. */
00445   BLE_GAP_EVT_AUTH_KEY_REQUEST,                 /**< Request to provide an authentication key. */
00446   BLE_GAP_EVT_AUTH_STATUS,                      /**< Authentication procedure completed with status. */
00447   BLE_GAP_EVT_CONN_SEC_UPDATE,                  /**< Connection security updated. */
00448   BLE_GAP_EVT_TIMEOUT,                          /**< Timeout expired. */
00449   BLE_GAP_EVT_RSSI_CHANGED,                     /**< Signal strength measurement report. */
00450 };
00451 
00452 
00453 /**
00454  * @brief GAP Option IDs.
00455  * IDs that uniquely identify a GAP option.
00456  */
00457 enum BLE_GAP_OPTS
00458 {
00459   BLE_GAP_OPT_LOCAL_CONN_LATENCY  = BLE_GAP_OPT_BASE,    /**< Local connection latency. */
00460   BLE_GAP_OPT_PASSKEY,                                   /**< Set passkey to be used during pairing. This option can be used to make the SoftDevice use an application provided passkey instead of generating a random passkey.*/
00461   BLE_GAP_OPT_PRIVACY,                                   /**< Set or get custom IRK or custom private address cycle interval. */
00462 };
00463 /**@} */
00464 
00465 
00466 /**@brief Event data for connected event. */
00467 typedef struct
00468 {
00469   ble_gap_addr_t        peer_addr;              /**< Bluetooth address of the peer device. */
00470   uint8_t               irk_match :1;           /**< If 1, peer device's address resolved using an IRK. */
00471   uint8_t               irk_match_idx  :7;      /**< Index in IRK list where the address was matched. */
00472   ble_gap_conn_params_t conn_params;            /**< GAP Connection Parameters. */
00473 } ble_gap_evt_connected_t;
00474 
00475 
00476 /**@brief Event data for disconnected event. */
00477 typedef struct
00478 {
00479   uint8_t reason;                               /**< HCI error code. */
00480 } ble_gap_evt_disconnected_t;
00481 
00482 
00483 /**@brief Event data for connection parameter update event. */
00484 typedef struct
00485 {
00486   ble_gap_conn_params_t conn_params;            /**<  GAP Connection Parameters. */
00487 } ble_gap_evt_conn_param_update_t;
00488 
00489 
00490 /**@brief Event data for security parameters request event. */
00491 typedef struct
00492 {
00493   ble_gap_sec_params_t peer_params;             /**< Initiator Security Parameters. */
00494 } ble_gap_evt_sec_params_request_t;
00495 
00496 
00497 /**@brief Event data for security info request event. */
00498 typedef struct
00499 {
00500   ble_gap_addr_t peer_addr;                     /**< Bluetooth address of the peer device. */
00501   uint16_t       div;                           /**< Encryption diversifier for LTK lookup. */
00502   uint8_t        enc_info  : 1;                 /**< If 1, Encryption Information required. */
00503   uint8_t        id_info   : 1;                 /**< If 1, Identity Information required. */
00504   uint8_t        sign_info : 1;                 /**< If 1, Signing Information required. */
00505 } ble_gap_evt_sec_info_request_t;
00506 
00507 
00508 /**@brief Event data for passkey display event. */
00509 typedef struct
00510 {
00511   uint8_t passkey[BLE_GAP_PASSKEY_LEN];         /**< 6-digit passkey in ASCII ('0'-'9' digits only). */
00512 } ble_gap_evt_passkey_display_t;
00513 
00514 
00515 /**@brief Event data for authentication key request event. */
00516 typedef struct
00517 {
00518   uint8_t key_type;                             /**< See @ref BLE_GAP_AUTH_KEY_TYPES. */
00519 } ble_gap_evt_auth_key_request_t;
00520 
00521 
00522 /**@brief Security levels supported.
00523  * @note See Bluetooth Specification Version 4.1 Volume 3, Part C, Chapter 10.
00524 */
00525 typedef struct
00526 {
00527   uint8_t lv1 : 1;                              /**< If 1: Level 1 is supported. */
00528   uint8_t lv2 : 1;                              /**< If 1: Level 2 is supported. */
00529   uint8_t lv3 : 1;                              /**< If 1: Level 3 is supported. */
00530 } ble_gap_sec_levels_t;
00531 
00532 
00533 /**@brief Keys that have been exchanged. */
00534 typedef struct
00535 {
00536   uint8_t ltk       : 1;                        /**< Long Term Key. */
00537   uint8_t ediv_rand : 1;                        /**< Encrypted Diversifier and Random value. */
00538   uint8_t irk       : 1;                        /**< Identity Resolving Key. */
00539   uint8_t address   : 1;                        /**< Public or static random address. */
00540   uint8_t csrk      : 1;                        /**< Connection Signature Resolving Key. */
00541 } ble_gap_sec_keys_t;
00542 
00543 
00544 /**@brief Event data for authentication status event. */
00545 typedef struct
00546 {
00547   uint8_t               auth_status;            /**< Authentication status, see @ref BLE_GAP_SEC_STATUS. */
00548   uint8_t               error_src;              /**< On error, source that caused the failure, see @ref BLE_GAP_SEC_STATUS_SOURCES. */
00549   ble_gap_sec_levels_t  sm1_levels;             /**< Levels supported in Security Mode 1. */
00550   ble_gap_sec_levels_t  sm2_levels;             /**< Levels supported in Security Mode 2. */
00551   ble_gap_sec_keys_t    periph_kex;             /**< Bitmap stating which keys were exchanged (distributed) by the peripheral. */
00552   ble_gap_sec_keys_t    central_kex;            /**< Bitmap stating which keys were exchanged (distributed) by the central. */
00553   struct periph_keys_t
00554   {
00555     ble_gap_enc_info_t    enc_info;             /**< Peripheral's Encryption information. */
00556   } periph_keys;                                /**< Actual keys distributed from the Peripheral to the Central. */ 
00557   struct central_keys_t
00558   {
00559     ble_gap_irk_t         irk;                  /**< Central's IRK. */
00560     ble_gap_addr_t        id_info;              /**< Central's Identity Info. */
00561   } central_keys;                               /**< Actual keys distributed from the Central to the Peripheral. */
00562 } ble_gap_evt_auth_status_t;
00563 
00564 
00565 /**@brief Event data for connection security update event. */
00566 typedef struct
00567 {
00568   ble_gap_conn_sec_t conn_sec;                  /**< Connection security level. */
00569 } ble_gap_evt_conn_sec_update_t;
00570 
00571 
00572 /**@brief Event data for timeout event. */
00573 typedef struct
00574 {
00575   uint8_t src;                                  /**< Source of timeout event, see @ref BLE_GAP_TIMEOUT_SOURCES. */
00576 } ble_gap_evt_timeout_t;
00577 
00578 
00579 /**@brief Event data for advertisement report event. */
00580 typedef struct
00581 {
00582   int8_t  rssi;                               /**< Received Signal Strength Indication in dBm. */
00583 } ble_gap_evt_rssi_changed_t;
00584 
00585 
00586 /**@brief GAP event callback event structure. */
00587 typedef struct
00588 {
00589   uint16_t conn_handle;                                     /**< Connection Handle on which event occured. */
00590   union                                                     /**< union alternative identified by evt_id in enclosing struct. */
00591   {
00592     ble_gap_evt_connected_t          connected;             /**< Connected Event Parameters. */
00593     ble_gap_evt_disconnected_t       disconnected;          /**< Disconnected Event Parameters. */
00594     ble_gap_evt_conn_param_update_t  conn_param_update;     /**< Connection Parameter Update Parameters. */
00595     ble_gap_evt_sec_params_request_t sec_params_request;    /**< Security Parameters Request Event Parameters. */
00596     ble_gap_evt_sec_info_request_t   sec_info_request;      /**< Security Information Request Event Parameters. */
00597     ble_gap_evt_passkey_display_t    passkey_display;       /**< Passkey Display Event Parameters. */
00598     ble_gap_evt_auth_key_request_t   auth_key_request;      /**< Authentication Key Request Event Parameters. */
00599     ble_gap_evt_auth_status_t        auth_status;           /**< Authentication Status Event Parameters. */
00600     ble_gap_evt_conn_sec_update_t    conn_sec_update;       /**< Connection Security Update Event Parameters. */
00601     ble_gap_evt_timeout_t            timeout;               /**< Timeout Event Parameters. */
00602     ble_gap_evt_rssi_changed_t       rssi_changed;          /**< RSSI Event parameters. */
00603   } params;
00604 
00605 } ble_gap_evt_t;
00606 
00607 
00608 /**@brief Local connection latency option.
00609  *
00610  *         Local connection latency is a feature which enables the slave to improve
00611  *         current consumption by ignoring the slave latency set by the peer. The
00612  *         local connection latency can only be set to a multiple of the slave latency,
00613  *         and cannot be longer than half of the supervision timeout.
00614  *
00615  *         Used with @ref sd_ble_opt_set to set the local connection latency. The
00616  *         @ref sd_ble_opt_get is not supported for this option, but the actual 
00617  *         local connection latency (unless set to NULL) is set as a return parameter
00618  *         when setting the option.
00619  *
00620  *  @note  The latency set will be truncated down to the closest slave latency event
00621  *         multiple, or the nearest multiple before half of the supervision timeout.
00622  *
00623  *  @note  The local connection latency is default off, and needs to be set for new
00624  *         connections and whenever the connection is updated.
00625  *
00626  *  @retval ::NRF_SUCCESS Set successfully.
00627  *  @retval ::NRF_ERROR_NOT_SUPPORTED Get is not supported.
00628  *  @retval ::BLE_ERROR_INVALID_CONN_HANDLE Invalid connection handle parameter.
00629  */
00630 typedef struct
00631 {
00632   uint16_t   conn_handle;                       /**< Connection Handle */
00633   uint16_t   requested_latency;                 /**< Requested local connection latency. */
00634   uint16_t * p_actual_latency;                  /**< Pointer to storage for the actual local connection latency (can be set to NULL to skip return value). */
00635 } ble_gap_opt_local_conn_latency_t;
00636 
00637 
00638 /**@brief Passkey Option.
00639  *
00640  *        Structure containing the passkey to be used during pairing. This can be used with @ref
00641  *        sd_ble_opt_set to make the SoftDevice use a pre-programmed passkey for authentication
00642  *        instead of generating a random one.
00643  *
00644  * @note  @ref sd_ble_opt_get is not supported for this option.
00645  *
00646  */
00647 typedef struct
00648 {
00649   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.*/
00650 } ble_gap_opt_passkey_t;
00651 
00652 
00653 /**@brief Custom Privacy Options.
00654  *
00655  * @note The specified address cycle interval is used when the address cycle mode is
00656  * @ref BLE_GAP_ADDR_CYCLE_MODE_AUTO. If 0 is given, the address will not be refreshed at any
00657  * interval, and not at start of advertising. A new address can be generated manually by calling
00658  * @ref sd_ble_gap_address_set with the same type again. The default interval is
00659  * @ref BLE_GAP_DEFAULT_PRIVATE_ADDR_CYCLE_INTERVAL_S.
00660  *
00661  * @note If cycle mode is @ref BLE_GAP_ADDR_CYCLE_MODE_AUTO, the address will immediately be
00662  * refreshed when this option is set.
00663  */
00664 typedef struct
00665 {
00666   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. */
00667   uint16_t        interval_s;   /**< When input: Custom private address cycle interval in seconds. When output: The current private address cycle interval. */
00668 } ble_gap_opt_privacy_t;
00669 
00670 
00671 /**@brief Option structure for GAP options. */
00672 typedef union
00673 {
00674   ble_gap_opt_local_conn_latency_t local_conn_latency;  /**< Local connection latency. */
00675   ble_gap_opt_passkey_t            passkey;             /**< Passkey to be used for pairing.*/
00676   ble_gap_opt_privacy_t            privacy;             /**< Custom privacy options. */
00677 } ble_gap_opt_t;
00678 /**@} */
00679 
00680 
00681 /**@addtogroup BLE_GAP_FUNCTIONS Functions
00682  * @{ */
00683 
00684 /**@brief Set local Bluetooth address.
00685  *
00686  * If the address cycle mode is @ref BLE_GAP_ADDR_CYCLE_MODE_AUTO, the address type is required to
00687  * be @ref BLE_GAP_ADDR_TYPE_RANDOM_PRIVATE_RESOLVABLE or
00688  * @ref BLE_GAP_ADDR_TYPE_RANDOM_PRIVATE_NON_RESOLVABLE. The given address is ignored and the
00689  * SoftDevice will generate a new private address automatically every time advertising is
00690  * (re)started, and every @ref BLE_GAP_DEFAULT_PRIVATE_ADDR_CYCLE_INTERVAL_S seconds. If this API
00691  * call is used again with the same parameters while advertising, the SoftDevice will immediately
00692  * generate a new private address to replace the current address.
00693  *
00694  * If the application wishes to use a @ref BLE_GAP_ADDR_TYPE_PUBLIC or
00695  * @ref BLE_GAP_ADDR_TYPE_RANDOM_STATIC address, the cycle mode must be
00696  * @ref BLE_GAP_ADDR_CYCLE_MODE_NONE.
00697  *
00698  * If this API function is called while advertising, the softdevice will immediately update the
00699  * advertising address without the need to stop advertising in the following cases:
00700  *   - If the previously set address is of type @ref BLE_GAP_ADDR_TYPE_PUBLIC and the new address
00701  *   is also of type @ref BLE_GAP_ADDR_TYPE_PUBLIC
00702  *   - If the previously set address is not @ref BLE_GAP_ADDR_TYPE_PUBLIC and the new address is
00703  *   also not @ref BLE_GAP_ADDR_TYPE_PUBLIC.
00704  *
00705  * If the address is changed from a @ref BLE_GAP_ADDR_TYPE_PUBLIC address to another type or from
00706  * another type to a @ref BLE_GAP_ADDR_TYPE_PUBLIC address, the change will take effect the next
00707  * time advertising is started.
00708  *
00709  * @note If the address cycle mode is @ref BLE_GAP_ADDR_CYCLE_MODE_NONE and the application is
00710  *       using privacy, the application must take care to generate and set new private addresses
00711  *       periodically to comply with the Privacy specification in Bluetooth Core Spec.
00712  *
00713  * @param[in] addr_cycle_mode Address cycle mode, see @ref BLE_GAP_ADDR_CYCLE_MODES.
00714  * @param[in] p_addr          Pointer to address structure.
00715  *
00716  * @return @ref NRF_SUCCESS Address successfully set.
00717  * @return @ref NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
00718  * @return @ref NRF_ERROR_INVALID_PARAM Invalid parameters.
00719  * @return @ref BLE_ERROR_GAP_INVALID_BLE_ADDR Invalid address.
00720  * @return @ref NRF_ERROR_BUSY The stack is busy, process pending events and retry.
00721  */
00722 SVCALL(SD_BLE_GAP_ADDRESS_SET, uint32_t, sd_ble_gap_address_set(uint8_t addr_cycle_mode, ble_gap_addr_t const * const p_addr));
00723 
00724 
00725 /**@brief Get local Bluetooth address.
00726  *
00727  * @param[out] p_addr Pointer to address structure.
00728  *
00729  * @return @ref NRF_SUCCESS Address successfully retrieved.
00730  * @return @ref NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
00731  */
00732 SVCALL(SD_BLE_GAP_ADDRESS_GET, uint32_t, sd_ble_gap_address_get(ble_gap_addr_t * const p_addr));
00733 
00734 
00735 /**@brief Set, clear or update advertisement and scan response data.
00736  *
00737  * @note The format of the advertisement data will be checked by this call to ensure interoperability.
00738  *       Limitations imposed by this API call to the data provided include having a flags data type in the scan response data and
00739  *       duplicating the local name in the advertisement data and scan response data. 
00740  *
00741  * @note: To clear the advertisement data and set it to a 0-length packet, simply provide a valid pointer (p_data/p_sr_data) with its corresponding 
00742  *        length (dlen/srdlen) set to 0.
00743  *
00744  * @note: The call will fail if p_data and p_sr_data are both NULL since this would have no effect.
00745  *
00746  * @param[in] p_data    Raw data to be placed in advertisement packet. If NULL, no changes are made to the current advertisement packet data.
00747  * @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.
00748  * @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.
00749  * @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.
00750  *
00751  * @return @ref NRF_SUCCESS Advertisement data successfully updated or cleared.
00752  * @return @ref NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
00753  * @return @ref NRF_ERROR_INVALID_FLAGS Invalid combination of advertising flags supplied.
00754  * @return @ref NRF_ERROR_INVALID_DATA Invalid data type(s) supplied, check the advertising data format specification.
00755  * @return @ref NRF_ERROR_INVALID_LENGTH Invalid data length(s) supplied.
00756  * @return @ref BLE_ERROR_GAP_UUID_LIST_MISMATCH Invalid UUID list supplied.
00757  * @return @ref NRF_ERROR_BUSY The stack is busy, process pending events and retry.
00758  */
00759 SVCALL(SD_BLE_GAP_ADV_DATA_SET, uint32_t, sd_ble_gap_adv_data_set(uint8_t const * const p_data, uint8_t dlen, uint8_t const * const p_sr_data, uint8_t srdlen));
00760 
00761 
00762 /**@brief Start advertising (GAP Discoverable, Connectable modes, Broadcast Procedure).
00763  *
00764  * @param[in] p_adv_params Pointer to advertising parameters structure.
00765  *
00766  * @return @ref NRF_SUCCESS The BLE stack has started advertising.
00767  * @return @ref NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
00768  * @return @ref NRF_ERROR_INVALID_STATE Invalid state to perform operation.
00769  * @return @ref NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied, check the accepted ranges and limits.
00770  * @return @ref BLE_ERROR_GAP_INVALID_BLE_ADDR Invalid Bluetooth address supplied.
00771  * @return @ref BLE_ERROR_GAP_DISCOVERABLE_WITH_WHITELIST Discoverable mode and whitelist incompatible.
00772  */
00773 SVCALL(SD_BLE_GAP_ADV_START, uint32_t, sd_ble_gap_adv_start(ble_gap_adv_params_t const * const p_adv_params));
00774 
00775 
00776 /**@brief Stop advertising (GAP Discoverable, Connectable modes, Broadcast Procedure).
00777  *
00778  * @return @ref NRF_SUCCESS The BLE stack has stopped advertising.
00779  * @return @ref NRF_ERROR_INVALID_STATE Invalid state to perform operation (most probably not in advertising state).
00780  */
00781 SVCALL(SD_BLE_GAP_ADV_STOP, uint32_t, sd_ble_gap_adv_stop(void));
00782 
00783 
00784 /**@brief Update connection parameters.
00785  *
00786  * @details In the central role this will initiate a Link Layer connection parameter update procedure,
00787  *          otherwise in the peripheral role, this will send the corresponding L2CAP request and wait for
00788  *          the central to perform the procedure. In both cases, and regardless of success or failure, the application
00789  *          will be informed of the result with a @ref BLE_GAP_EVT_CONN_PARAM_UPDATE event.
00790  *
00791  * @note If both a connection supervision timeout and a maximum connection interval are specified, then the following constraint
00792  *       applies: (conn_sup_timeout * 8) >= (max_conn_interval * (slave_latency + 1))
00793  *
00794  * @param[in] conn_handle Connection handle.
00795  * @param[in] p_conn_params  Pointer to desired connection parameters. If NULL is provided on a peripheral role,
00796  *                           the parameters in the PPCP characteristic of the GAP service will be used instead.
00797  *
00798  * @return @ref NRF_SUCCESS The Connection Update procedure has been started successfully.
00799  * @return @ref NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
00800  * @return @ref NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied, check parameter limits and constraints.
00801  * @return @ref NRF_ERROR_BUSY Procedure already in progress or not allowed at this time, process pending events and retry.
00802  * @return @ref BLE_ERROR_INVALID_CONN_HANDLE Invalid connection handle supplied.
00803  * @return @ref NRF_ERROR_NO_MEM Not enough memory to complete operation.
00804  */
00805 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 * const p_conn_params));
00806 
00807 
00808 /**@brief Disconnect (GAP Link Termination).
00809  *
00810  * @details This call initiates the disconnection procedure, and its completion will be communicated to the application
00811  *          with a BLE_GAP_EVT_DISCONNECTED event.
00812  *
00813  * @param[in] conn_handle Connection handle.
00814  * @param[in] hci_status_code HCI status code, see @ref BLE_HCI_STATUS_CODES (accepted values are BTLE_REMOTE_USER_TERMINATED_CONNECTION and BTLE_CONN_INTERVAL_UNACCEPTABLE).
00815  *
00816  * @return @ref NRF_SUCCESS The disconnection procedure has been started successfully.
00817  * @return @ref NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied.
00818  * @return @ref BLE_ERROR_INVALID_CONN_HANDLE Invalid connection handle supplied.
00819  * @return @ref NRF_ERROR_INVALID_STATE Invalid state to perform operation (disconnection is already in progress or not connected at all).
00820  */
00821 SVCALL(SD_BLE_GAP_DISCONNECT, uint32_t, sd_ble_gap_disconnect(uint16_t conn_handle, uint8_t hci_status_code));
00822 
00823 
00824 /**@brief Set the radio's transmit power.
00825  *
00826  * @param[in] tx_power Radio transmit power in dBm (accepted values are -40, -30, -20, -16, -12, -8, -4, 0, and 4 dBm).
00827  *
00828  * @note -40 dBm will not actually give -40 dBm, but will instead be remapped to -30 dBm.
00829  *
00830  * @return @ref NRF_SUCCESS Successfully changed the transmit power.
00831  * @return @ref NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied.
00832  * @return @ref NRF_ERROR_BUSY The stack is busy, process pending events and retry.
00833  */
00834 SVCALL(SD_BLE_GAP_TX_POWER_SET, uint32_t, sd_ble_gap_tx_power_set(int8_t tx_power));
00835 
00836 
00837 /**@brief Set GAP Appearance value.
00838  *
00839  * @param[in] appearance Appearance (16-bit), see @ref BLE_APPEARANCES.
00840  *
00841  * @return @ref NRF_SUCCESS  Appearance value set successfully.
00842  * @return @ref NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied.
00843  */
00844 SVCALL(SD_BLE_GAP_APPEARANCE_SET, uint32_t, sd_ble_gap_appearance_set(uint16_t appearance));
00845 
00846 
00847 /**@brief Get GAP Appearance value.
00848  *
00849  * @param[out] p_appearance Appearance (16-bit), see @ref BLE_APPEARANCES.
00850  *
00851  * @return @ref NRF_SUCCESS Appearance value retrieved successfully.
00852  * @return @ref NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
00853  */
00854 SVCALL(SD_BLE_GAP_APPEARANCE_GET, uint32_t, sd_ble_gap_appearance_get(uint16_t * const p_appearance));
00855 
00856 
00857 /**@brief Set GAP Peripheral Preferred Connection Parameters.
00858  *
00859  * @param[in] p_conn_params Pointer to a @ref ble_gap_conn_params_t structure with the desired parameters.
00860  *
00861  * @return @ref NRF_SUCCESS Peripheral Preferred Connection Parameters set successfully.
00862  * @return @ref NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
00863  * @return @ref NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied.
00864  */
00865 SVCALL(SD_BLE_GAP_PPCP_SET, uint32_t, sd_ble_gap_ppcp_set(ble_gap_conn_params_t const * const p_conn_params));
00866 
00867 
00868 /**@brief Get GAP Peripheral Preferred Connection Parameters.
00869  *
00870  * @param[out] p_conn_params Pointer to a @ref ble_gap_conn_params_t structure where the parameters will be stored.
00871  *
00872  * @return @ref NRF_SUCCESS Peripheral Preferred Connection Parameters retrieved successfully.
00873  * @return @ref NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
00874  */
00875 SVCALL(SD_BLE_GAP_PPCP_GET, uint32_t, sd_ble_gap_ppcp_get(ble_gap_conn_params_t * const p_conn_params));
00876 
00877 
00878 /**@brief Set GAP device name.
00879  *
00880  * @param[in] p_write_perm Write permissions for the Device Name characteristic see @ref ble_gap_conn_sec_mode_t.
00881  * @param[in] p_dev_name Pointer to a UTF-8 encoded, <b>non NULL-terminated</b> string.
00882  * @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).
00883  *
00884  * @return @ref NRF_SUCCESS GAP device name and permissions set successfully.
00885  * @return @ref NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
00886  * @return @ref NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied.
00887  * @return @ref NRF_ERROR_DATA_SIZE Invalid data size(s) supplied.
00888  */
00889 SVCALL(SD_BLE_GAP_DEVICE_NAME_SET, uint32_t, sd_ble_gap_device_name_set(ble_gap_conn_sec_mode_t const * const p_write_perm, uint8_t const * const p_dev_name, uint16_t len));
00890 
00891 
00892 /**@brief Get GAP device name.
00893  *
00894  * @param[in]     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.
00895  * @param[in,out] p_len      Length of the buffer pointed by p_dev_name, complete device name length on output.
00896  *
00897  * @note          If the device name is longer than the size of the supplied buffer,
00898  *                p_len will return the complete device name length,
00899  *                and not the number of bytes actually returned in p_dev_name.
00900  *                The application may use this information to allocate a suitable buffer size.
00901  *
00902  * @return @ref NRF_SUCCESS GAP device name retrieved successfully.
00903  * @return @ref NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
00904  * @return @ref NRF_ERROR_DATA_SIZE Invalid data size(s) supplied.
00905  */
00906 SVCALL(SD_BLE_GAP_DEVICE_NAME_GET, uint32_t, sd_ble_gap_device_name_get(uint8_t * const p_dev_name, uint16_t * const p_len));
00907 
00908 
00909 /**@brief Initiate GAP Authentication procedure.
00910  *
00911  * @param[in] conn_handle Connection handle.
00912  * @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 procedure.
00913  *
00914  * @details In the central role, this function will send an SMP Pairing Request, otherwise in the peripheral role, an SMP Security Request will be sent.
00915  *          In the peripheral role, only the timeout, bond and mitm fields of @ref ble_gap_sec_params_t are used.
00916  *
00917  * @note    The GAP Authentication procedure may be triggered by the central without calling this function when accessing a secure service.
00918  * @note    Calling this function may result in the following events depending on the outcome and parameters: @ref BLE_GAP_EVT_SEC_PARAMS_REQUEST,
00919  *          @ref BLE_GAP_EVT_SEC_INFO_REQUEST, @ref BLE_GAP_EVT_AUTH_KEY_REQUEST, @ref BLE_GAP_EVT_AUTH_STATUS.
00920  * @note    The timeout parameter in @ref ble_gap_sec_params_t is interpreted here as the Security Request timeout
00921  *
00922  *
00923  * @return @ref NRF_SUCCESS Successfully initiated authentication procedure.
00924  * @return @ref NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
00925  * @return @ref NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied.
00926  * @return @ref NRF_ERROR_INVALID_STATE Invalid state to perform operation.
00927  * @return @ref BLE_ERROR_INVALID_CONN_HANDLE Invalid connection handle supplied.
00928  * @return @ref NRF_ERROR_TIMEOUT A SMP timeout has occured, and further SMP operations on this link is prohibited.
00929  */
00930 SVCALL(SD_BLE_GAP_AUTHENTICATE, uint32_t, sd_ble_gap_authenticate(uint16_t conn_handle, ble_gap_sec_params_t const * const p_sec_params));
00931 
00932 
00933 /**@brief Reply with GAP security parameters.
00934  *
00935  * @param[in] conn_handle Connection handle.
00936  * @param[in] sec_status Security status, see @ref BLE_GAP_SEC_STATUS.
00937  * @param[in] p_sec_params Pointer to a @ref ble_gap_sec_params_t security parameters structure.
00938  *
00939  * @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 NRF_ERROR_INVALID_STATE.
00940  * @note    If the call returns an error code, the request is still pending, and the reply call may be repeated with corrected parameters.
00941  * @note    The timeout parameter in @ref ble_gap_sec_params_t is interpreted here as the SMP procedure timeout, and must be 30 seconds. The function will fail
00942  *          if the application supplies a different value.
00943  *
00944  * @return @ref NRF_SUCCESS Successfully accepted security parameter from the application.
00945  * @return @ref NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
00946  * @return @ref NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied.
00947  * @return @ref NRF_ERROR_INVALID_STATE Invalid state to perform operation.
00948  * @return @ref BLE_ERROR_INVALID_CONN_HANDLE Invalid connection handle supplied.
00949  */
00950 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 * const p_sec_params));
00951 
00952 
00953 /**@brief Reply with an authentication key.
00954  *
00955  * @param[in] conn_handle Connection handle.
00956  * @param[in] key_type See @ref BLE_GAP_AUTH_KEY_TYPES.
00957  * @param[in] key If key type is BLE_GAP_AUTH_KEY_TYPE_NONE, then NULL.
00958  *                If key type is BLE_GAP_AUTH_KEY_TYPE_PASSKEY, then a 6-byte ASCII string (digit 0..9 only, no NULL termination).
00959  *                If key type is BLE_GAP_AUTH_KEY_TYPE_OOB, then a 16-byte OOB key value in Little Endian format.
00960  *
00961  * @details This function is only used to reply to a @ref BLE_GAP_EVT_AUTH_KEY_REQUEST, calling it at other times will result in an NRF_ERROR_INVALID_STATE.
00962  * @note    If the call returns an error code, the request is still pending, and the reply call may be repeated with corrected parameters.
00963  *
00964  * @return @ref NRF_SUCCESS Authentication key successfully set.
00965  * @return @ref NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
00966  * @return @ref NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied.
00967  * @return @ref NRF_ERROR_INVALID_STATE Invalid state to perform operation.
00968  * @return @ref BLE_ERROR_INVALID_CONN_HANDLE Invalid connection handle supplied.
00969  */
00970 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 * const key));
00971 
00972 
00973 /**@brief Reply with GAP security information.
00974  *
00975  * @param[in] conn_handle Connection handle.
00976  * @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.
00977  * @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.
00978  *
00979  * @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 NRF_ERROR_INVALID_STATE.
00980  * @note    If the call returns an error code, the request is still pending, and the reply call may be repeated with corrected parameters.
00981  * @note    Data signing is not implemented yet. p_sign_info must therefore be NULL.
00982  *
00983  * @return @ref NRF_SUCCESS Successfully accepted security information.
00984  * @return @ref NRF_ERROR_INVALID_PARAM Invalid parameter(s) supplied.
00985  * @return @ref NRF_ERROR_INVALID_STATE Invalid state to perform operation.
00986  * @return @ref BLE_ERROR_INVALID_CONN_HANDLE Invalid connection handle supplied.
00987  * @return @ref NRF_ERROR_BUSY The stack is busy, process pending events and retry.
00988  */
00989 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 * const p_enc_info, ble_gap_sign_info_t const * const p_sign_info));
00990 
00991 
00992 /**@brief Get the current connection security.
00993  *
00994  * @param[in]  conn_handle Connection handle.
00995  * @param[out] p_conn_sec  Pointer to a @ref ble_gap_conn_sec_t structure to be filled in.
00996  *
00997  * @return @ref NRF_SUCCESS Current connection security successfully retrieved.
00998  * @return @ref NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
00999  * @return @ref BLE_ERROR_INVALID_CONN_HANDLE Invalid connection handle supplied.
01000  */
01001 SVCALL(SD_BLE_GAP_CONN_SEC_GET, uint32_t, sd_ble_gap_conn_sec_get(uint16_t conn_handle, ble_gap_conn_sec_t * const p_conn_sec));
01002 
01003 
01004 /**@brief Start reporting the received signal strength to the application. 
01005  *
01006  * A new event is reported whenever the RSSI value changes, until @ref sd_ble_gap_rssi_stop is called.
01007  *
01008  * @param[in] conn_handle Connection handle.
01009  *
01010  * @return @ref NRF_SUCCESS Successfully activated RSSI reporting.
01011  * @return @ref NRF_ERROR_INVALID_STATE Invalid state to perform operation.
01012  * @return @ref BLE_ERROR_INVALID_CONN_HANDLE Invalid connection handle supplied.
01013  */
01014 SVCALL(SD_BLE_GAP_RSSI_START, uint32_t, sd_ble_gap_rssi_start(uint16_t conn_handle));
01015 
01016 
01017 /**@brief Stop reporting the received singnal strength. 
01018  *
01019  * An RSSI change detected before the call but not yet received by the application 
01020  * may be reported after @ref sd_ble_gap_rssi_stop has been called.
01021  *
01022  * @param[in] conn_handle Connection handle.
01023  *
01024  * @return @ref NRF_SUCCESS Successfully deactivated RSSI reporting.
01025  * @return @ref NRF_ERROR_INVALID_STATE Invalid state to perform operation.
01026  * @return @ref BLE_ERROR_INVALID_CONN_HANDLE Invalid connection handle supplied.
01027  */
01028 SVCALL(SD_BLE_GAP_RSSI_STOP, uint32_t, sd_ble_gap_rssi_stop(uint16_t conn_handle));
01029 /**@} */
01030 
01031 #endif // BLE_GAP_H__
01032 
01033 /**
01034   @}
01035 */