 |
Bluetooth Low Energy Host Stack
Rev. 4
API Reference Manual
|
|
|
Bluetooth Low Energy Host Stack
Rev. 4
API Reference Manual
|
|
Files | |
| file | gap_interface.h |
| file | gap_types.h |
Typedefs | |
| typedef gapAdvertisingData_t | gapScanResponseData_t |
| typedef bleResult_t | gapDisconnectionReason_t |
| typedef void(* | gapAdvertisingCallback_t) (gapAdvertisingEvent_t *pAdvertisingEvent) |
| typedef void(* | gapScanningCallback_t) (gapScanningEvent_t *pScanningEvent) |
| typedef void(* | gapConnectionCallback_t) (deviceId_t deviceId, gapConnectionEvent_t *pConnectionEvent) |
| struct gapSmpKeys_t |
Structure containing the SMP information exchanged during pairing.
| Data Fields | ||
|---|---|---|
| uint8_t | cLtkSize |
Encryption Key Size. If aLtk is NULL, this is ignored. |
| uint8_t * | aLtk |
Long Term (Encryption) Key. NULL if LTK is not distributed, else size is given by cLtkSize. |
| uint8_t * | aIrk |
Identity Resolving Key. NULL if aIrk is not distributed. |
| uint8_t * | aCsrk |
Connection Signature Resolving Key. NULL if aCsrk is not distributed. |
| uint8_t | cRandSize |
Size of RAND; usually equal to gcMaxRandSize_d. If aLtk is NULL, this is ignored. |
| uint8_t * | aRand |
RAND value used to identify the LTK. If aLtk is NULL, this is ignored. |
| uint16_t | ediv |
EDIV value used to identify the LTK. If aLtk is NULL, this is ignored. |
| bleAddressType_t | addressType |
Public or Random address. If aAddress is NULL, this is ignored. |
| uint8_t * | aAddress |
Device Address. NULL if address is not distributed. If aIrk is NULL, this is ignored. |
| struct gapSecurityRequirements_t |
Security Requirements structure for a Device, a Service or a Characteristic.
| Data Fields | ||
|---|---|---|
| gapSecurityModeAndLevel_t | securityModeLevel | Security mode and level. |
| bool_t | authorization | Authorization required. |
| uint16_t | minimumEncryptionKeySize | Minimum encryption key (LTK) size. |
| struct gapServiceSecurityRequirements_t |
Service Security Requirements.
| Data Fields | ||
|---|---|---|
| uint16_t | serviceHandle | Handle of the Service declaration in the GATT Database. |
| gapSecurityRequirements_t | requirements | Requirements for all attributes in this service. |
| struct gapDeviceSecurityRequirements_t |
Device Security - Master Security Requirements + Service Security Requirements.
| Data Fields | ||
|---|---|---|
| gapSecurityRequirements_t * | pMasterSecurityRequirements | Security requirements added to all services. |
| uint8_t | cNumServices | Number of service-specific requirements; must be less than or equal to gcMaxServiceSpecificSecurityRequirements_d. |
| gapServiceSecurityRequirements_t * | aServiceSecurityRequirements | Array of service-specific requirements. |
| struct gapHandleList_t |
List of Attribute Handles for authorization lists.
| Data Fields | ||
|---|---|---|
| uint8_t | cNumHandles | Number of handles in this list. |
| uint16_t | aHandles[gcGapMaxAuthorizationHandles_c] | List of handles. |
| struct gapConnectionSecurityInformation_t |
Connection Security Information structure.
| Data Fields | ||
|---|---|---|
| bool_t | authenticated | TRUE if pairing was performed with MITM protection. |
| gapHandleList_t | authorizedToRead | List of handles the peer has been authorized to read. |
| gapHandleList_t | authorizedToWrite | List of handles the peer has been authorized to write. |
| struct gapPairingParameters_t |
Pairing parameters structure for the Gap_Pair and Gap_AcceptPairingRequest APIs.
| Data Fields | ||
|---|---|---|
| bool_t | withBonding | TRUE if this device is able to and wants to bond after pairing, FALSE otherwise. |
| gapSecurityModeAndLevel_t | securityModeAndLevel | The desired security mode-level. |
| uint8_t | maxEncryptionKeySize | Maximum LTK size supported by the device. |
| gapIoCapabilities_t | localIoCapabilities | I/O capabilities used to determine the pairing method. |
| bool_t | oobAvailable |
TRUE if this device has Out-of-Band data that can be used for authenticated pairing. FALSE otherwise. |
| gapSmpKeyFlags_t | centralKeys | Indicates the SMP keys to be distributed by the Central. |
| gapSmpKeyFlags_t | peripheralKeys | Indicates the SMP keys to be distributed by the Peripheral. |
| bool_t | leSecureConnectionSupported | In BLE 4.2, indicates if device supports LE Secure Connections pairing. |
| bool_t | useKeypressNotifications | In BLE 4.2, indicates if device supports Keypress Notification PDUs during Passkey Entry pairing. |
| struct gapSlaveSecurityRequestParameters_t |
| struct gapAdvertisingParameters_t |
Advertising Parameters; for defaults see gGapDefaultAdvertisingParameters_d.
| Data Fields | ||
|---|---|---|
| uint16_t | minInterval |
Minimum desired advertising interval. Default: 1.28 s. |
| uint16_t | maxInterval |
Maximum desired advertising interval. Default: 1.28 s. |
| bleAdvertisingType_t | advertisingType |
Advertising type. Default: connectable undirected. |
| bleAddressType_t | ownAddressType |
Indicates whether the advertising address is the public address (BD_ADDR) or the random address (set by Gap_SetRandomAddress). Default: public address. If BLE 4.2 Controller Privacy is enabled, this parameter is irrelevant as Private Resolvable Addresses are always used. |
| bleAddressType_t | peerAddressType | Address type of the peer; only used in directed advertising and Enhanced Privacy (BLE 4.2). |
| bleDeviceAddress_t | peerAddress | Address of the peer; same as above. |
| gapAdvertisingChannelMapFlags_t | channelMap |
Bit mask indicating which of the three advertising channels are used. Default: all three. |
| gapAdvertisingFilterPolicy_t | filterPolicy |
Indicates whether the connect and scan requests are filtered using the White List. Default: does not use White List (process all). |
| struct gapScanningParameters_t |
Scanning parameters; for defaults see gGapDefaultScanningParameters_d.
| Data Fields | ||
|---|---|---|
| bleScanType_t | type |
Scanning type. Default: passive. |
| uint16_t | interval |
Scanning interval. Default: 10 ms. |
| uint16_t | window |
Scanning window. Default: 10 ms. |
| bleAddressType_t | ownAddressType |
Indicates whether the address used in scan requests is the public address (BD_ADDR) or the random address (set by Gap_SetRandomAddress). Default: public address. If BLE 4.2 Controller Privacy is enabled, this parameter is irrelevant as Private Resolvable Addresses are always used. |
| bleScanningFilterPolicy_t | filterPolicy |
Indicates whether the advertising packets are filtered using the White List. Default: does not use White List (scan all). |
| struct gapConnectionRequestParameters_t |
Connection request parameter structure to be used in the Gap_Connect function; for API-defined defaults, use gGapDefaultConnectionRequestParameters_d.
| Data Fields | ||
|---|---|---|
| uint16_t | scanInterval |
Scanning interval. Default: 10 ms. |
| uint16_t | scanWindow |
Scanning window. Default: 10 ms. |
| bleInitiatorFilterPolicy_t | filterPolicy |
Indicates whether the connection request is issued for a specific device or for all the devices in the White List. Default: specific device. |
| bleAddressType_t | ownAddressType |
Indicates whether the address used in connection requests is the public address (BD_ADDR) or the random address (set by Gap_SetRandomAddress). Default: public address. |
| bleAddressType_t | peerAddressType |
When connecting to a specific device (see filterPolicy), this indicates that device's address type. Default: public address. |
| bleDeviceAddress_t | peerAddress | When connecting to a specific device (see filterPolicy), this indicates that device's address. |
| uint16_t | connIntervalMin |
The minimum desired connection interval. Default: 100 ms. |
| uint16_t | connIntervalMax |
The maximum desired connection interval. Default: 200 ms. |
| uint16_t | connLatency |
The desired connection latency (the maximum number of consecutive connection events the Slave is allowed to ignore). Default: 0. |
| uint16_t | supervisionTimeout |
The maximum time interval between consecutive over-the-air packets; if this timer expires, the connection is dropped. Default: 10 s. |
| uint16_t | connEventLengthMin |
The minimum desired connection event length. Default: 0 ms. |
| uint16_t | connEventLengthMax |
The maximum desired connection event length. Default: maximum possible, ~41 s. (lets the Controller decide). |
| bool_t | usePeerIdentityAddress |
If Controller Privacy is enabled and this parameter is TRUE, the address defined in the peerAddressType and peerAddress is an identity address. Otherwise, it is a device address. |
| struct gapConnectionParameters_t |
Connection parameters as received in the gConnEvtConnected_c connection event.
| struct gapAdStructure_t |
Definition of an AD Structure as contained in Advertising and Scan Response packets.
An Advertising or Scan Response packet contains several AD Structures.
| Data Fields | ||
|---|---|---|
| uint8_t | length |
Total length of the [adType + aData] fields. Equal to 1 + lengthOf(aData). |
| gapAdType_t | adType | AD Type of this AD Structure. |
| uint8_t * | aData | Data contained in this AD Structure; length of this array is equal to (gapAdStructure_t.length - 1). |
| struct gapAdvertisingData_t |
Advertising Data structure : a list of several gapAdStructure_t structures.
| Data Fields | ||
|---|---|---|
| uint8_t | cNumAdStructures | Number of AD Structures. |
| gapAdStructure_t * | aAdStructures | Array of AD Structures. |
| struct gapAdvertisingEvent_t |
Advertising event structure: type + data.
| Data Fields | ||
|---|---|---|
| gapAdvertisingEventType_t | eventType | Event type. |
| union gapAdvertisingEvent_t | eventData | Event data, to be interpreted according to gapAdvertisingEvent_t.eventType. |
| union gapAdvertisingEvent_t.eventData |
| Data Fields | ||
|---|---|---|
| bleResult_t | failReason | Event data for gAdvertisingCommandFailed_c event type: reason of failure to enable or disable advertising. |
| struct gapScannedDevice_t |
Scanned device information structure, obtained from LE Advertising Reports.
| Data Fields | ||
|---|---|---|
| bleAddressType_t | addressType | Device's advertising address type. |
| bleDeviceAddress_t | aAddress | Device's advertising address. |
| int8_t | rssi | RSSI on the advertising channel; may be compared to the TX power contained in the AD Structure of type gAdTxPowerLevel_c to estimate distance from the advertiser. |
| uint8_t | dataLength | Length of the advertising or scan response data. |
| uint8_t * | data | Advertising or scan response data. |
| bleAdvertisingReportEventType_t | advEventType | Advertising report type, indicating what type of event generated this data (advertising, scan response). |
| bool_t | directRpaUsed | TRUE if directed advertising with Resolvable Private Address as Direct Address was detected while Enhanced Privacy is enabled. |
| bleDeviceAddress_t | directRpa |
Resolvable Private Address set as Direct Address for directed advertising. Valid only when directRpaUsed is TRUE. |
| bool_t | advertisingAddressResolved |
If this is TRUE, the address contained in the addressType and aAddress fields is the identity address of a resolved RPA from the Advertising Address field. Otherwise, the adress from the respective fields is the public or random device address contained in the Advertising Address field. |
| struct gapScanningEvent_t |
Scanning event structure: type + data.
| Data Fields | ||
|---|---|---|
| gapScanningEventType_t | eventType | Event type. |
| union gapScanningEvent_t | eventData | Event data, to be interpreted according to gapScanningEvent_t.eventType. |
| union gapScanningEvent_t.eventData |
| Data Fields | ||
|---|---|---|
| bleResult_t | failReason | Event data for gScanCommandFailed_c event type: reason of failure to enable or disable scanning. |
| gapScannedDevice_t | scannedDevice | Event data for gGapScanEventDeviceScanned_c event type: scanned device information. |
| struct gapConnectedEvent_t |
Event data structure for the gConnEvtConnected_c event.
| Data Fields | ||
|---|---|---|
| gapConnectionParameters_t | connParameters | Connection parameters established by the Controller. |
| bleAddressType_t | peerAddressType | Connected device's address type. |
| bleDeviceAddress_t | peerAddress | Connected device's address. |
| bool_t | peerRpaResolved |
If this is TRUE, the address defined by peerAddressType and peerAddress is the identity address of the peer, and the peer used an RPA that was resolved by the Controller and is contained in the peerRpa field. Otherwise, it is a device address. This parameter is irrelevant if BLE 4.2 Controller Privacy is not enabled. |
| bleDeviceAddress_t | peerRpa | Peer Resolvable Private Address if Controller Privacy is active and peerRpaResolved is TRUE. |
| bool_t | localRpaUsed |
If this is TRUE, the Controller has used an RPA contained in the localRpa field. This parameter is irrelevant if BLE 4.2 Controller Privacy is not enabled. |
| bleDeviceAddress_t | localRpa | Local Resolvable Private Address if Controller Privacy is active and localRpaUsed is TRUE. |
| struct gapKeyExchangeRequestEvent_t |
Event data structure for the gConnEvtKeyExchangeRequest_c event.
| Data Fields | ||
|---|---|---|
| gapSmpKeyFlags_t | requestedKeys | Mask identifying the keys being requested. |
| uint8_t | requestedLtkSize | Requested size of the encryption key. |
| struct gapKeysReceivedEvent_t |
Event data structure for the gConnEvtKeysReceived_c event.
| Data Fields | ||
|---|---|---|
| gapSmpKeys_t * | pKeys | The SMP keys distributed by the peer. |
| struct gapAuthenticationRejectedEvent_t |
Event data structure for the gConnEvtAuthenticationRejected_c event.
| Data Fields | ||
|---|---|---|
| gapAuthenticationRejectReason_t | rejectReason | Slave's reason for rejecting the authentication. |
| struct gapPairingCompleteEvent_t |
Event data structure for the gConnEvtPairingComplete_c event.
| Data Fields | ||
|---|---|---|
| bool_t | pairingSuccessful | TRUE if pairing succeeded, FALSE otherwise. |
| union gapPairingCompleteEvent_t | pairingCompleteData | Information of completion, selected upon the value of gapPairingCompleteEvent_t.pairingSuccessful. |
| union gapPairingCompleteEvent_t.pairingCompleteData |
| Data Fields | ||
|---|---|---|
| bool_t | withBonding | If pairingSuccessful is TRUE, this indicates whether the devices bonded. |
| bleResult_t | failReason | If pairingSuccessful is FALSE, this contains the reason of failure. |
| struct gapLongTermKeyRequestEvent_t |
Event data structure for the gConnEvtLongTermKeyRequest_c event.
| Data Fields | ||
|---|---|---|
| uint16_t | ediv | The Encryption Diversifier, as defined by the SMP. |
| uint8_t | aRand[gcSmpMaxRandSize_c] | The Random number, as defined by the SMP. |
| uint8_t | randSize | Usually equal to gcMaxRandSize_d. |
| struct gapEncryptionChangedEvent_t |
| struct gapDisconnectedEvent_t |
Event data structure for the gConnEvtDisconnected_c event.
| Data Fields | ||
|---|---|---|
| gapDisconnectionReason_t | reason | Reason for disconnection. |
| struct gapConnParamsUpdateReq_t |
Event data structure for the gConnEvtParameterUpdateRequest_c event.
| struct gapConnParamsUpdateComplete_t |
Event data structure for the gConnEvtParameterUpdateComplete_c event.
| Data Fields | ||
|---|---|---|
| bleResult_t | status | |
| uint16_t | connInterval | Interval between connection events. |
| uint16_t | connLatency | Number of consecutive connection events the Slave may ignore. |
| uint16_t | supervisionTimeout | The maximum time interval between consecutive over-the-air packets; if this timer expires, the connection is dropped. |
| struct gapConnLeDataLengthChanged_t |
Event data structure for the gConnEvtLeDataLengthChanged_c event.
| struct gapConnectionEvent_t |
Connection event structure: type + data.
| Data Fields | ||
|---|---|---|
| gapConnectionEventType_t | eventType | Event type. |
| union gapConnectionEvent_t | eventData | Event data, to be interpreted according to gapConnectionEvent_t.eventType. |
| union gapConnectionEvent_t.eventData |
| Data Fields | ||
|---|---|---|
| gapConnectedEvent_t | connectedEvent | Data for gConnEvtConnected_c: information about the connection parameters. |
| gapPairingParameters_t | pairingEvent | Data for gConnEvtPairingRequest_c, gConnEvtPairingResponse_c: pairing parameters. |
| gapAuthenticationRejectedEvent_t | authenticationRejectedEvent | Data for gConnEvtAuthenticationRejected_c: reason for rejection. |
| gapSlaveSecurityRequestParameters_t | slaveSecurityRequestEvent | Data for gConnEvtSlaveSecurityRequest_c: Slave's security requirements. |
| gapKeyExchangeRequestEvent_t | keyExchangeRequestEvent | Data for gConnEvtKeyExchangeRequest_c: mask indicating the keys that were requested by the peer. |
| gapKeysReceivedEvent_t | keysReceivedEvent | Data for gConnEvtKeysReceived_c: the keys received from the peer. |
| gapPairingCompleteEvent_t | pairingCompleteEvent | Data for gConnEvtPairingComplete_c: fail reason or (if successful) bonding state. |
| gapLongTermKeyRequestEvent_t | longTermKeyRequestEvent | Data for gConnEvtLongTermKeyRequest_c: encryption diversifier and random number. |
| gapEncryptionChangedEvent_t | encryptionChangedEvent | Data for gConnEvtEncryptionChanged_c: new encryption state. |
| gapDisconnectedEvent_t | disconnectedEvent | Data for gConnEvtDisconnected_c: reason for disconnection. |
| int8_t | rssi_dBm | Data for gConnEvtRssiRead_c: value of the RSSI in dBm. |
| int8_t | txPowerLevel_dBm | Data for gConnEvtTxPowerLevelRead_c: value of the TX power. |
| bleResult_t | failReason | Data for gConnEvtPowerReadFailure_c: reason for power reading failure. |
| uint32_t | passkeyForDisplay | |
| gapConnParamsUpdateReq_t | connectionUpdateRequest | Data for gConnEvtParameterUpdateRequest_c: connection parameters update. |
| gapConnParamsUpdateComplete_t | connectionUpdateComplete | Data for gConnEvtParameterUpdateComplete_c: connection parameters update. |
| gapConnLeDataLengthChanged_t | leDataLengthChanged | Data for gConnEvtLeDataLengthChanged_c: new data length parameters. |
| gapKeypressNotification_t | incomingKeypressNotification | |
| uint32_t | numericValueForDisplay | |
| struct gapIdentityInformation_t |
Indentity Information structure definition.
| Data Fields | ||
|---|---|---|
| bleIdentityAddress_t | identityAddress | Identity Address - Public or Random Static. |
| uint8_t | irk[gcSmpIrkSize_c] | Identity Resolving Key. |
| struct gapAutoConnectParams_t |
Parameters for the Auto Connect Scan Mode.
| Data Fields | ||
|---|---|---|
| uint8_t | cNumAddresses | Number of device addresses to automatically connect to. |
| bool_t | writeInWhiteList | If set to TRUE, the device addresses are written in the White List before scanning is enabled. |
| gapConnectionRequestParameters_t * | aAutoConnectData | The array of connection request parameters, of size equal to cNumAddresses. |
| gapConnectionCallback_t | connectionCallback | The callback used to receive connection events if the device auto-connects. |
| #define Gap_AddSecurityModesAndLevels | ( | modeLevelA, | |
| modeLevelB | |||
| ) |
Macro used to combine two security mode-levels.
| [in] | modeLevelA,modeLevelB | The two security mode-levels. |
| #define Gap_CancelInitiatingConnection | ( | ) |
Macro used to cancel a connection initiated by Gap_Connect(...).
| #define Gap_ReadAdvertisingTxPowerLevel | ( | ) |
Macro used to read the radio transmitter power when advertising.
| #define Gap_ReadRssi | ( | deviceId | ) |
Macro used to read the RSSI of a radio connection.
| [in] | deviceId | Device ID identifying the radio connection. |
| #define Gap_ReadTxPowerLevelInConnection | ( | deviceId | ) |
Macro used to read the radio transmitting power level of a radio connection.
| [in] | deviceId | Device ID identifying the radio connection. |
| #define gCancelOngoingInitiatingConnection_d |
Use this value as a parameter to the Gap_Disconnect(deviceId) function to cancel any ongoing connection initiation, for example if the connection has timed out.
| #define gMode_2_Mask_d |
Mask to check if a Security Mode-and-Level is Mode 2.
| #define getSecurityLevel | ( | modeLevel | ) |
Extracts the security level (see gapSecurityLevel_t) from the combined security mode-level (gapSecurityModeAndLevel_t).
| #define getSecurityMode | ( | modeLevel | ) |
Extracts the security mode (see gapSecurityMode_t) from the combined security mode-level (gapSecurityModeAndLevel_t).
| #define gDefaultEncryptionKeySize_d |
The default value for the LTK size.
| #define gGapDefaultDeviceSecurity_d |
The default value for the Device Security (no requirements)
| #define gGapDefaultSecurityRequirements_d |
The default value for a Security Requirement.
| #define gGapAdvertisingIntervalRangeMinimum_c |
Minimum advertising interval (20 ms)
| #define gGapAdvertisingIntervalDefault_c |
Default advertising interval (1.28 s)
| #define gGapAdvertisingIntervalRangeMaximum_c |
Maximum advertising interval (10.24 s)
| #define gGapAdvertisingChannelMapDefault_c |
Default Advertising Channel Map - all 3 channels are enabled.
| #define gGapDefaultAdvertisingParameters_d |
Default value for Advertising Parameters struct.
| #define gGapScanIntervalMin_d |
Minimum scan interval (2.5 ms)
| #define gGapScanIntervalDefault_d |
Default scan interval (10 ms)
| #define gGapScanIntervalMax_d |
Maximum scan interval (10.24 s)
| #define gGapScanWindowMin_d |
Minimum scan window (2.5 ms)
| #define gGapScanWindowDefault_d |
Default scan window (10 ms)
| #define gGapScanWindowMax_d |
Maximum scan window (10.24 s)
| #define gGapRssiMin_d |
Minimum valid value for RSSI (dB)
| #define gGapRssiMax_d |
Maximum valid value for RSSI (dB)
| #define gGapRssiNotAvailable_d |
A special invalid value for the RSSI indicating that the measurement is not available.
| #define gGapDefaultScanningParameters_d |
Default value for Scanning Parameters struct.
| #define gGapConnIntervalMin_d |
Minimum connection interval (7.5 ms)
| #define gGapConnIntervalMax_d |
Maximum connection interval (4 s)
| #define gGapConnLatencyMin_d |
Minimum connection latency value (0 - no connection event may be ignored)
| #define gGapConnLatencyMax_d |
Maximum connection latency value (499 connection events may be ignored)
| #define gGapConnSuperTimeoutMin_d |
Minimum supervision timeout (100 ms)
| #define gGapConnSuperTimeoutMax_d |
Maximum supervision timeout (32 s)
| #define gGapConnEventLengthMin_d |
Minimum value of the connection event length (0 ms)
| #define gGapConnEventLengthMax_d |
Maximum value of the connection event length (~41 s)
| #define gGapDefaultConnectionLatency_d |
Default connection latency: 0.
| #define gGapDefaultSupervisionTimeout_d |
Default supervision timeout: 10s.
| #define gGapDefaultMinConnectionInterval_d |
Default minimum connection interval: 100ms.
| #define gGapDefaultMaxConnectionInterval_d |
Default maximum connection interval: 200ms.
| #define gGapDefaultConnectionRequestParameters_d |
The default value for the Connection Request Parameters structure.
Scan Response Data structure : a list of several gapAdStructure_t structures.
| typedef bleResult_t gapDisconnectionReason_t |
Disconnection reason alias - reasons are contained in HCI error codes.
| typedef void(* gapAdvertisingCallback_t) (gapAdvertisingEvent_t *pAdvertisingEvent) |
Advertising Callback prototype.
| typedef void(* gapScanningCallback_t) (gapScanningEvent_t *pScanningEvent) |
Scanning Callback prototype.
| typedef void(* gapConnectionCallback_t) (deviceId_t deviceId, gapConnectionEvent_t *pConnectionEvent) |
Connection Callback prototype.
| enum gapRole_t |
| enum gapIoCapabilities_t |
I/O Capabilities as defined by the SMP.
| enum gapSmpKeyFlags_t |
| enum gapSecurityMode_t |
| enum gapSecurityLevel_t |
LE Security Level.
Security Mode-and-Level definitions.
Reason for rejecting the pairing request.
These values are equal to the corresponding reasons from SMP.
| enum gapScanMode_t |
Scan Mode options; used as parameter for Gap_SetScanMode.
Advertising Filter Policy values.
| enum gapAdType_t |
AD Type values as defined by Bluetooth SIG used when defining gapAdStructure_t structures for advertising or scan response data.
| enum gapAdTypeFlags_t |
Values of the AD Flags advertising data structure.
Enumeration used by the Gap_ReadRadioPowerLevel function.
Enumeration for Controller Transmitter Test payload types.
Advertising event type enumeration, as contained in the gapAdvertisingEvent_t.
Scanning event type enumeration, as contained in the gapScanningEvent_t.
Connection event type enumeration, as contained in the gapConnectionEvent_t.
| enum gapAppearance_t |
Appearance characteristic enumeration, also used in advertising.
| bleResult_t Gap_RegisterDeviceSecurityRequirements | ( | gapDeviceSecurityRequirements_t * | pSecurity | ) |
Registers the device security requirements. This function includes a master security for all services and, optionally, additional stronger security settings for services as required by the profile and/or application.
| [in] | pSecurity | A pointer to the application-allocated gapDeviceSecurityRequirements_t structure. |
| bleResult_t Gap_SetAdvertisingParameters | ( | gapAdvertisingParameters_t * | pAdvertisingParameters | ) |
Sets up the Advertising Parameters.
| [in] | pAdvertisingParameters | Pointer to gapAdvertisingParameters_t structure. |
| bleResult_t Gap_SetAdvertisingData | ( | gapAdvertisingData_t * | pAdvertisingData, |
| gapScanResponseData_t * | pScanResponseData | ||
| ) |
Sets up the Advertising and Scan Response Data.
| [in] | pAdvertisingData | Pointer to gapAdvertisingData_t structure or NULL. |
| [in] | pScanResponseData | Pointer to gapScanResponseData_t structure or NULL. |
| bleResult_t Gap_StartAdvertising | ( | gapAdvertisingCallback_t | advertisingCallback, |
| gapConnectionCallback_t | connectionCallback | ||
| ) |
Commands the controller to start advertising.
| [in] | advertisingCallback | Callback used by the application to receive advertising events. Can be NULL. |
| [in] | connectionCallback | Callback used by the application to receive connection events. Can be NULL. |
| bleResult_t Gap_StopAdvertising | ( | void | ) |
Commands the controller to stop advertising.
| bleResult_t Gap_Authorize | ( | deviceId_t | deviceId, |
| uint16_t | handle, | ||
| gattDbAccessType_t | access | ||
| ) |
Authorizes a peer for an attribute in the database.
| [in] | deviceId | The peer being authorized. |
| [in] | handle | The attribute handle. |
| [in] | access | The type of access granted (gAccessRead_c or gAccessWrite_c). |
| bleResult_t Gap_SaveCccd | ( | deviceId_t | deviceId, |
| uint16_t | handle, | ||
| gattCccdFlags_t | cccd | ||
| ) |
Save the CCCD value for a specific Client and CCCD handle.
| [in] | deviceId | The peer GATT Client. |
| [in] | handle | The handle of the CCCD as defined in the GATT Database. |
| [in] | cccd | The bit mask representing the CCCD value to be saved. |
| bleResult_t Gap_CheckNotificationStatus | ( | deviceId_t | deviceId, |
| uint16_t | handle, | ||
| bool_t * | pOutIsActive | ||
| ) |
Retrieves the notification status for a given Client and a given CCCD handle.
| [in] | deviceId | The peer GATT Client. |
| [in] | handle | The handle of the CCCD. |
| [out] | pOutIsActive | The address to store the status into. |
| bleResult_t Gap_CheckIndicationStatus | ( | deviceId_t | deviceId, |
| uint16_t | handle, | ||
| bool_t * | pOutIsActive | ||
| ) |
Retrieves the indication status for a given Client and a given CCCD handle.
| [in] | deviceId | The peer GATT Client. |
| [in] | handle | The handle of the CCCD. |
| [out] | pOutIsActive | The address to store the status into. |
| bleResult_t Gap_GetBondedStaticAddresses | ( | bleDeviceAddress_t * | aOutDeviceAddresses, |
| uint8_t | maxDevices, | ||
| uint8_t * | pOutActualCount | ||
| ) |
Retrieves a list of the static addresses of bonded devices, if any.
| [out] | aOutDeviceAddresses | Array of addresses to be filled. |
| [in] | maxDevices | Maximum number of addresses to be obtained. |
| [out] | pOutActualCount | The actual number of addresses written. |
| bleResult_t Gap_GetBondedDevicesIdentityInformation | ( | gapIdentityInformation_t * | aOutIdentityAddresses, |
| uint8_t | maxDevices, | ||
| uint8_t * | pOutActualCount | ||
| ) |
Retrieves a list of the identity information of bonded devices, if any.
| [out] | aOutIdentityAddresses | Array of identities to be filled. |
| [in] | maxDevices | Maximum number of identities to be obtained. |
| [out] | pOutActualCount | The actual number of identities written. |
| bleResult_t Gap_Pair | ( | deviceId_t | deviceId, |
| gapPairingParameters_t * | pPairingParameters | ||
| ) |
Initiates pairing with a peer device.
| [in] | deviceId | The peer to pair with. |
| [in] | pPairingParameters | Pairing parameters as required by the SMP. |
| bleResult_t Gap_SendSlaveSecurityRequest | ( | deviceId_t | deviceId, |
| bool_t | bondAfterPairing, | ||
| gapSecurityModeAndLevel_t | securityModeLevel | ||
| ) |
Informs the peer Master about the local security requirements.
| [in] | deviceId | The GAP peer to pair with. |
| [in] | bondAfterPairing | Specifies if bonding is supported. |
| [in] | securityModeLevel | The level of security requested. |
| bleResult_t Gap_EncryptLink | ( | deviceId_t | deviceId | ) |
Encrypts the link with a bonded peer.
| [in] | deviceId | Device ID of the peer. |
| bleResult_t Gap_AcceptPairingRequest | ( | deviceId_t | deviceId, |
| gapPairingParameters_t * | pPairingParameters | ||
| ) |
Accepts the pairing request from a peer.
| [in] | deviceId | The peer requesting authentication. |
| [in] | pPairingParameters | Pairing parameters as required by the SMP. |
| bleResult_t Gap_RejectPairing | ( | deviceId_t | deviceId, |
| gapAuthenticationRejectReason_t | reason | ||
| ) |
Rejects the peer's authentication request.
| [in] | deviceId | The GAP peer who requested authentication. |
| [in] | reason | Reason why the current device rejects the authentication. |
| bleResult_t Gap_EnterPasskey | ( | deviceId_t | deviceId, |
| uint32_t | passkey | ||
| ) |
Enters the passkey requested by the peer during the pairing process.
| [in] | deviceId | The GAP peer that requested a passkey entry. |
| [in] | passkey | The peer's secret passkey. |
| bleResult_t Gap_ProvideOob | ( | deviceId_t | deviceId, |
| uint8_t * | aOob | ||
| ) |
Provides the Out-Of-Band data for the SMP Pairing process.
| [in] | deviceId | The pairing device. |
| [in] | aOob | Pointer to OOB data (array of gcSmpOobSize_d size). |
| bleResult_t Gap_RejectPasskeyRequest | ( | deviceId_t | deviceId | ) |
Rejects the passkey request from a peer.
| [in] | deviceId | The GAP peer that requested a passkey entry. |
| bleResult_t Gap_SendSmpKeys | ( | deviceId_t | deviceId, |
| gapSmpKeys_t * | pKeys | ||
| ) |
Sends the SMP keys during the SMP Key Exchange procedure.
| [in] | deviceId | The GAP peer who initiated the procedure. |
| [in] | pKeys | The SMP keys of the local device. |
| bleResult_t Gap_RejectKeyExchangeRequest | ( | deviceId_t | deviceId | ) |
Rejects the Key Exchange procedure with a paired peer.
| [in] | deviceId | The GAP peer who requested the Key Exchange procedure. |
| bleResult_t Gap_LeScRegeneratePublicKey | ( | void | ) |
Regenerates the private/public key pair used for LE Secure Connections pairing.
| bleResult_t Gap_LeScValidateNumericValue | ( | deviceId_t | deviceId, |
| bool_t | valid | ||
| ) |
Validates the numeric value during the Numeric Comparison LE Secure Connections pairing.
| deviceId | Device ID of the peer. |
| valid | TRUE if user has indicated that numeric values are matched, FALSE otherwise. |
| bleResult_t Gap_LeScGetLocalOobData | ( | void | ) |
Retrieves local OOB data used for LE Secure Connections pairing.
| bleResult_t Gap_LeScSetPeerOobData | ( | deviceId_t | deviceId, |
| gapLeScOobData_t * | pPeerOobData | ||
| ) |
Sets peer OOB data used for LE Secure Connections pairing.
| deviceId | Device ID of the peer. |
| pPeerOobData | OOB data received from the peer. |
| bleResult_t Gap_LeScSendKeypressNotification | ( | deviceId_t | deviceId, |
| gapKeypressNotification_t | keypressNotification | ||
| ) |
Sends a Keypress Notification to the peer.
| deviceId | Device ID of the peer. |
| keypressNotification | Value of the Keypress Notification. |
| bleResult_t Gap_ProvideLongTermKey | ( | deviceId_t | deviceId, |
| uint8_t * | aLtk, | ||
| uint8_t | ltkSize | ||
| ) |
Provides the Long Term Key (LTK) to the controller for encryption setup.
| [in] | deviceId | The GAP peer who requested encryption. |
| [in] | aLtk | The Long Term Key. |
| [in] | ltkSize | The Long Term Key size. |
| bleResult_t Gap_DenyLongTermKey | ( | deviceId_t | deviceId | ) |
Rejects an LTK request originating from the controller.
| [in] | deviceId | The GAP peer who requested encryption. |
| bleResult_t Gap_LoadEncryptionInformation | ( | deviceId_t | deviceId, |
| uint8_t * | aOutLtk, | ||
| uint8_t * | pOutLtkSize | ||
| ) |
Loads the encryption key for a bonded device.
| [in] | deviceId | Device ID of the peer. |
| [out] | aOutLtk | Array of size gcMaxLtkSize_d to be filled with the LTK. |
| [out] | pOutLtkSize | The LTK size. |
| bleResult_t Gap_SetLocalPasskey | ( | uint32_t | passkey | ) |
Sets the SMP passkey for this device.
| [in] | passkey | The SMP passkey. |
| bleResult_t Gap_SetScanMode | ( | gapScanMode_t | scanMode, |
| gapAutoConnectParams_t * | pAutoConnectParams | ||
| ) |
Sets internal scan filters and actions.
| [in] | scanMode | The scan mode to be activated. Default is gDefaultScan_c. |
| [in] | pAutoConnectParams | Parameters for the Auto Connect Scan Mode. |
| bleResult_t Gap_StartScanning | ( | gapScanningParameters_t * | pScanningParameters, |
| gapScanningCallback_t | scanningCallback | ||
| ) |
Optionally sets the scanning parameters and begins scanning.
| [in] | pScanningParameters | The scanning parameters; may be NULL. |
| [in] | scanningCallback | The scanning callback. |
| bleResult_t Gap_StopScanning | ( | void | ) |
Commands the controller to stop scanning.
| bleResult_t Gap_Connect | ( | gapConnectionRequestParameters_t * | pParameters, |
| gapConnectionCallback_t | connCallback | ||
| ) |
Connects to a scanned device.
| [in] | pParameters | Create Connection command parameters. |
| [in] | connCallback | Callback used to receive connection events. |
| bleResult_t Gap_Disconnect | ( | deviceId_t | deviceId | ) |
Initiates disconnection from a connected peer device.
| [in] | deviceId | The connected peer to disconnect from. |
| bleResult_t Gap_SaveCustomPeerInformation | ( | deviceId_t | deviceId, |
| void * | aInfo, | ||
| uint16_t | offset, | ||
| uint16_t | infoSize | ||
| ) |
Saves custom peer information in raw data format.
| [in] | deviceId | Device ID of the GAP peer. |
| [in] | aInfo | Pointer to the beginning of the data. |
| [in] | offset | Offset from the beginning of the reserved memory area. |
| [in] | infoSize | Data size (maximum equal to gcReservedFlashSizeForCustomInformation_d). |
| bleResult_t Gap_LoadCustomPeerInformation | ( | deviceId_t | deviceId, |
| void * | aOutInfo, | ||
| uint16_t | offset, | ||
| uint16_t | infoSize | ||
| ) |
Loads the custom peer information in raw data format.
| [in] | deviceId | Device ID of the GAP peer. |
| [out] | aOutInfo | Pointer to the beginning of the allocated memory. |
| [in] | offset | Offset from the beginning of the reserved memory area. |
| [in] | infoSize | Data size (maximum equal to gcReservedFlashSizeForCustomInformation_d). |
| bleResult_t Gap_CheckIfBonded | ( | deviceId_t | deviceId, |
| bool_t * | pOutIsBonded | ||
| ) |
Returns whether or not a connected peer device is bonded.
| [in] | deviceId | Device ID of the GAP peer. |
| [out] | pOutIsBonded | Boolean to be filled with the bonded flag. |
| bleResult_t Gap_ReadWhiteListSize | ( | void | ) |
Retrieves the size of the White List.
| bleResult_t Gap_ClearWhiteList | ( | void | ) |
Removes all addresses from the White List, if any.
| bleResult_t Gap_AddDeviceToWhiteList | ( | bleAddressType_t | addressType, |
| bleDeviceAddress_t | address | ||
| ) |
Adds a device address to the White List.
| [in] | address | The address of the white-listed device. |
| [in] | addressType | The device address type (public or random). |
| bleResult_t Gap_RemoveDeviceFromWhiteList | ( | bleAddressType_t | addressType, |
| bleDeviceAddress_t | address | ||
| ) |
Removes a device address from the White List.
| [in] | address | The address of the white-listed device. |
| [in] | addressType | The device address type (public or random). |
| bleResult_t Gap_ReadPublicDeviceAddress | ( | void | ) |
Reads the device's public address from the controller.
| bleResult_t Gap_CreateRandomDeviceAddress | ( | uint8_t * | aIrk, |
| uint8_t * | aRandomPart | ||
| ) |
Requests the controller to create a random address.
| [in] | aIrk | The Identity Resolving Key to be used for a private resolvable address or NULL for a private non-resolvable address (fully random). |
| [in] | aRandomPart | If aIrk is not NULL, this is a 3-byte array containing the Random Part of a Private Resolvable Address, in LSB to MSB order; the most significant two bits of the most significant byte (aRandomPart[3] & 0xC0) are ignored. This may be NULL, in which case the Random Part is randomly generated internally. |
| bleResult_t Gap_SaveDeviceName | ( | deviceId_t | deviceId, |
| uchar_t * | aName, | ||
| uint8_t | cNameSize | ||
| ) |
Retrieves the name of a bonded device.
| [in] | deviceId | Device ID for the active peer which name is saved. |
| [in] | aName | Array of characters holding the name. |
| [in] | cNameSize | Number of characters to be saved. |
| bleResult_t Gap_GetBondedDevicesCount | ( | uint8_t * | pOutBondedDevicesCount | ) |
Retrieves the number of bonded devices.
| [out] | pOutBondedDevicesCount | Pointer to integer to be written. |
| bleResult_t Gap_GetBondedDeviceName | ( | uint8_t | nvmIndex, |
| uchar_t * | aOutName, | ||
| uint8_t | maxNameSize | ||
| ) |
Retrieves the name of a bonded device.
| [in] | nvmIndex | Index of the device in NVM bonding area. |
| [out] | aOutName | Destination array to copy the name into. |
| [in] | maxNameSize | Maximum number of characters to be copied, including the terminating NULL character. |
| bleResult_t Gap_RemoveBond | ( | uint8_t | nvmIndex | ) |
Removes the bond with a device.
| [in] | nvmIndex | Index of the device in the NVM bonding area. |
| bleResult_t Gap_RemoveAllBonds | ( | void | ) |
Removes all bonds with other devices.
| bleResult_t Gap_ReadRadioPowerLevel | ( | gapRadioPowerLevelReadType_t | txReadType, |
| deviceId_t | deviceId | ||
| ) |
Reads the power level of the controller's radio.
| bleResult_t Gap_SetTxPowerLevel | ( | uint8_t | powerLevel, |
| bleTransmitPowerChannelType_t | channelType | ||
| ) |
Sets the Tx power level on the controller's radio.
| [in] | powerLevel | Power level as specified in the controller interface. |
| [in] | channelType | The advertising or connnection channel type. |
| bleResult_t Gap_VerifyPrivateResolvableAddress | ( | uint8_t | nvmIndex, |
| bleDeviceAddress_t | aAddress | ||
| ) |
Verifies a Private Resolvable Address with a bonded device's IRK.
| [in] | nvmIndex | Index of the device in NVM bonding area whose IRK must be checked. |
| [in] | aAddress | The Private Resolvable Address to be verified. |
| bleResult_t Gap_SetRandomAddress | ( | bleDeviceAddress_t | aAddress | ) |
Sets a random address into the Controller.
| [in] | aAddress | The Private Resolvable, Private Non-Resolvable, or Static Random Address. |
| bleResult_t Gap_SetDefaultPairingParameters | ( | gapPairingParameters_t * | pPairingParameters | ) |
Sets the default pairing parameters to be used by automatic pairing procedures.
| [in] | pPairingParameters | Pairing parameters as required by the SMP or NULL. |
| bleResult_t Gap_UpdateConnectionParameters | ( | deviceId_t | deviceId, |
| uint16_t | intervalMin, | ||
| uint16_t | intervalMax, | ||
| uint16_t | slaveLatency, | ||
| uint16_t | timeoutMultiplier, | ||
| uint16_t | minCeLength, | ||
| uint16_t | maxCeLength | ||
| ) |
Request a set of new connection parameters
| [in] | deviceId | The DeviceID for which the command is intended |
| [in] | intervalMin | The minimum value for the connection event interval |
| [in] | intervalMax | The maximum value for the connection event interval |
| [in] | slaveLatency | The slave latency parameter |
| [in] | timeoutMultiplier | The connection timeout parameter |
| [in] | minCeLength | The minimum value for the connection event length |
| [in] | maxCeLength | The maximum value for the connection event length |
| bleResult_t Gap_EnableUpdateConnectionParameters | ( | deviceId_t | deviceId, |
| bool_t | enable | ||
| ) |
Update the connection parameters
| [in] | deviceId | The DeviceID for which the command is intended |
| [in] | enable | Allow/disallow the parameters update |
| bleResult_t Gap_UpdateLeDataLength | ( | deviceId_t | deviceId, |
| uint16_t | txOctets, | ||
| uint16_t | txTime | ||
| ) |
Update the Tx Data Length
| [in] | deviceId | The DeviceID for which the command is intended |
| [in] | txOctets | Maximum transmission number of payload octets |
| [in] | txTime | Maximum transmission time |
| bleResult_t Gap_ControllerReset | ( | void | ) |
Resets the Controller.
| bleResult_t Gap_EnableHostPrivacy | ( | bool_t | enable, |
| uint8_t * | aIrk | ||
| ) |
Enables or disables Host Privacy (automatic regeneration of a Private Address).
| enable | TRUE to enable, FALSE to disable. |
| aIrk | Local IRK to be used for Resolvable Private Address generation or NULL for Non-Resolvable Private Address generation. Ignored if enable is FALSE. |
| bleResult_t Gap_EnableControllerPrivacy | ( | bool_t | enable, |
| uint8_t * | aOwnIrk, | ||
| uint8_t | peerIdCount, | ||
| gapIdentityInformation_t * | aPeerIdentities | ||
| ) |
Enables or disables Controller Privacy (Enhanced Privacy feature).
| enable | TRUE to enable, FALSE to disable. |
| aOwnIrk | Local IRK. Ignored if enable is FALSE, otherwise shall not be NULL. |
| peerIdCount | Size of aPeerIdentities array. Shall not be zero or greater than gcGapControllerResolvingListSize_c. Ignored if enable is FALSE. |
| aPeerIdentities | Array of peer identity addresses and IRKs. Ignored if enable is FALSE, otherwise shall not be NULL. |
| bleResult_t Gap_ControllerTest | ( | gapControllerTestCmd_t | testCmd, |
| uint8_t | radioChannel, | ||
| uint8_t | txDataLength, | ||
| gapControllerTestTxType_t | txPayloadType | ||
| ) |
Commands a Controller Test procedure.
| testCmd | Command type - "start TX test", "start RX test" or "end test". |
| radioChannel | Radio channel index. Valid range: 0-39. Frequency will be F[MHz] = 2402 + 2 * index. Effective range: 2402-2480 MHz. Ignored if command is "end test". |
| txDataLength | Size of packet payload for TX tests. Ignored if command is "start RX test" or "end test". |
| txPayloadType | Type of packet payload for TX tests. Ignored if command is "start RX test" or "end test". |