Cordio Stack and Cordio Profiles  r2p3-02rel0
app_api.h File Reference

Application framework API. More...

#include "wsf_os.h"
#include "dm_api.h"
#include "att_api.h"
#include "app_db.h"
Include dependency graph for app_api.h:

Go to the source code of this file.

Data Structures

struct  appAdvCfg_t
 Configurable parameters for advertising. More...
 
struct  appExtAdvCfg_t
 Configurable parameters for extended and periodic advertising. More...
 
struct  appSlaveCfg_t
 Configurable parameters for slave. More...
 
struct  appMasterCfg_t
 Configurable parameters for master. More...
 
struct  appExtMasterCfg_t
 Configurable parameters for extended master. More...
 
struct  appSecCfg_t
 Configurable parameters for security. More...
 
struct  appUpdateCfg_t
 Configurable parameters for connection parameter update. More...
 
struct  appReqActCfg_t
 Configurable parameters for incoming request actions. More...
 
struct  appDiscCfg_t
 Configurable parameters for service and characteristic discovery. More...
 
struct  appCfg_t
 Configurable parameters for application. More...
 
struct  appDevInfo_t
 Device information data type. More...
 

Macros

#define APP_ADV_NUM_CFG   APP_ADV_STOPPED
 Number of advertising configurations.
 
#define APP_RESOLVE_ADV_RPA   0
 Resolving the advertiser's RPA (AdvA)
 
#define APP_RESOLVE_DIRECT_RPA   1
 Resolving RPA the directed advertisement is being directed to (InitA)
 
App Advertising Mode

Discoverable/connectable mode used by function AppAdvStart.

#define APP_MODE_CONNECTABLE   0
 Connectable mode.
 
#define APP_MODE_DISCOVERABLE   1
 Discoverable mode.
 
#define APP_MODE_AUTO_INIT   2
 Automatically configure mode based on bonding info.
 
#define APP_MODE_NONE   255
 For internal use only.
 
#define APP_NUM_MODES   2
 Number of Discoverable/connectable modes.
 

Typedefs

typedef void(* appDiscCback_t) (dmConnId_t connId, uint8_t status)
 Service discovery and configuration callback. More...
 

Enumerations

enum  {
  APP_ADV_STATE1,
  APP_ADV_STATE2,
  APP_ADV_STATE3,
  APP_ADV_STOPPED
}
 Advertising states. More...
 
enum  {
  APP_ADV_DATA_CONNECTABLE,
  APP_SCAN_DATA_CONNECTABLE,
  APP_ADV_DATA_DISCOVERABLE,
  APP_SCAN_DATA_DISCOVERABLE,
  APP_NUM_DATA_LOCATIONS
}
 Advertising and scan data storage locations. More...
 
enum  {
  APP_DISC_INIT,
  APP_DISC_SEC_REQUIRED,
  APP_DISC_START,
  APP_DISC_CMPL,
  APP_DISC_FAILED,
  APP_DISC_CFG_START,
  APP_DISC_CFG_CONN_START,
  APP_DISC_CFG_CMPL
}
 Service discovery and configuration client status. More...
 
enum  {
  APP_ACT_ACCEPT,
  APP_ACT_REJECT,
  APP_ACT_NONE
}
 Actions for incoming requests. More...
 

Functions

App Initialization Functions

Application role initialization.

void AppSlaveInit (void)
 Initialize the App Framework for operation as a Bluetooth LE slave. More...
 
void AppMasterInit (void)
 Initialize the App Framework for operation as a Bluetooth LE master. More...
 
App Advertising Functions

Configure and send legacy, extended and periodic advertisments.

void AppSetAdvType (uint8_t advType)
 Set advertising type. More...
 
void AppSetAdvPeerAddr (uint8_t peerAddrType, uint8_t *pPeerAddr)
 Set advertising peer address and its type. More...
 
void AppAdvSetData (uint8_t location, uint8_t len, uint8_t *pData)
 Set advertising or scan data. Separate advertising and scan data can be set for connectable and discoverable modes. The application must allocate and maintain the memory pointed to by pData while the device is advertising. More...
 
bool_t AppAdvSetAdValue (uint8_t location, uint8_t adType, uint8_t len, uint8_t *pValue)
 Set the value of an advertising data element in the advertising or scan response data. If the element already exists in the data then it is replaced with the new value. If the element does not exist in the data it is appended to it, space permitting. More...
 
void AppAdvStart (uint8_t mode)
 Start advertising using the parameters for the given mode. More...
 
void AppAdvStop (void)
 Stop advertising. The device will no longer be connectable or discoverable. More...
 
dmConnId_t AppConnAccept (uint8_t advType, uint8_t addrType, uint8_t *pAddr)
 Accept a connection to a peer device with the given address. More...
 
bool_t AppSlaveIsAdvertising (void)
 Check if the local device's currently advertising. More...
 
void AppExtSetAdvPeerAddr (uint8_t advHandle, uint8_t peerAddrType, uint8_t *pPeerAddr)
 Set advertising peer address and its type for the given advertising set. More...
 
void AppExtAdvSetData (uint8_t advHandle, uint8_t location, uint16_t len, uint8_t *pData, uint16_t bufLen)
 Set extended advertising data. More...
 
void AppExtAdvStart (uint8_t numSets, uint8_t *pAdvHandles, uint8_t mode)
 Start extended advertising using the parameters for the given mode. More...
 
void AppExtAdvStop (uint8_t numSets, uint8_t *pAdvHandles)
 Stop extended advertising. If the number of sets is set to 0 then all advertising sets are disabled. More...
 
bool_t AppExtAdvSetAdValue (uint8_t advHandle, uint8_t location, uint8_t adType, uint8_t len, uint8_t *pValue)
 Set the value of an advertising data element in the extended advertising or scan response data. If the element already exists in the data then it is replaced with the new value. If the element does not exist in the data it is appended to it, space permitting. More...
 
void AppExtSetAdvType (uint8_t advHandle, uint8_t advType)
 Set extended advertising type. More...
 
dmConnId_t AppExtConnAccept (uint8_t advHandle, uint8_t advType, uint8_t addrType, uint8_t *pAddr)
 Accept a connection to a peer device with the given address using a given advertising set. More...
 
void AppPerAdvSetData (uint8_t advHandle, uint16_t len, uint8_t *pData, uint16_t bufLen)
 Set periodic advertising data. More...
 
void AppPerAdvStart (uint8_t advHandle)
 Start periodic advertising for the given advertising handle. More...
 
void AppPerAdvStop (uint8_t advHandle)
 Stop periodic advertising for the given advertising handle. More...
 
bool_t AppPerAdvSetAdValue (uint8_t advHandle, uint8_t adType, uint8_t len, uint8_t *pValue)
 Set the value of an advertising data element in the periodic advertising data. If the element already exists in the data then it is replaced with the new value. If the element does not exist in the data it is appended to it, space permitting. More...
 
App Scan Functions

configure and enable legacy and extended scanning and periodic synch.

void AppScanStart (uint8_t mode, uint8_t scanType, uint16_t duration)
 Start scanning. A scan is performed using the given discoverability mode, scan type, and duration. More...
 
void AppScanStop (void)
 Stop scanning. More...
 
void AppMasterResolveAddr (dmEvt_t *pMsg, appDbHdl_t dbHdl, uint8_t resolveType)
 Resolve the advertiser's RPA (AdvA) or the initiator's RPA (InitA) of a directed advertisement report. If the addresses resolved then a connection will be initiated. More...
 
void AppExtScanStart (uint8_t scanPhys, uint8_t mode, const uint8_t *pScanType, uint16_t duration, uint16_t period)
 Start scanning. A scan is performed using the given scanner PHYs, discoverability mode, scan type, duration, and period. More...
 
void AppExtScanStop (void)
 Stop scanning. More...
 
appDevInfo_tAppScanGetResult (uint8_t idx)
 Get a stored scan result from the scan result list. The first result is at index zero. More...
 
uint8_t AppScanGetNumResults (void)
 Get the number of stored scan results. More...
 
dmSyncId_t AppSyncStart (uint8_t advSid, uint8_t advAddrType, const uint8_t *pAdvAddr, uint16_t skip, uint16_t syncTimeout)
 Synchronize with periodic advertising from the given advertiser, and start receiving periodic advertising packets. More...
 
void AppSyncStop (dmSyncId_t syncId)
 Stop reception of the periodic advertising identified by the given sync identifier. More...
 
App Connection Functions

Initiate and update connections

dmConnId_t AppConnOpen (uint8_t addrType, uint8_t *pAddr, appDbHdl_t dbHdl)
 Open a connection to a peer device with the given address. More...
 
void AppConnClose (dmConnId_t connId)
 Close a connection with the given connection identifier. More...
 
dmConnId_t AppExtConnOpen (uint8_t initPhys, uint8_t addrType, uint8_t *pAddr, appDbHdl_t dbHdl)
 Open a connection to a peer device with the given address. More...
 
dmConnId_t AppConnIsOpen (void)
 Check if a connection is open. More...
 
uint8_t AppConnOpenList (dmConnId_t *pConnIdList)
 Gets a list of connection identifiers of open connections. More...
 
App Security and Bonding Functions

Security and Bonding functions for configuration and interaction with Security Manager Protocol (SMP) Pairing procedures.

void AppSetBondable (bool_t bondable)
 Set the bondable mode of the device. More...
 
void AppMasterSecurityReq (dmConnId_t connId)
 Initiate security as a master device. If there is a stored encryption key for the peer device this function will initiate encryption, otherwise it will initiate pairing. More...
 
void AppSlaveSecurityReq (dmConnId_t connId)
 Initiate a request for security as a slave device. This function will send a message to the master peer device requesting security. The master device should either initiate encryption or pairing. More...
 
void AppHandlePasskey (dmSecAuthReqIndEvt_t *pAuthReq)
 Handle a passkey request during pairing. If the passkey is to be displayed, a random passkey is generated and displayed. If the passkey is to be entered the user is prompted to enter the passkey. More...
 
void AppHandleNumericComparison (dmSecCnfIndEvt_t *pCnfInd)
 Handle a numeric comparison indication during pairing. The confirmation value is displayed and the user is prompted to verify that the local and peer confirmation values match. More...
 
App Event Processing

Process received messages for which there is a general process.

void AppSlaveProcDmMsg (dmEvt_t *pMsg)
 Process connection-related DM messages for a slave. This function should be called from the application's event handler. More...
 
void AppSlaveSecProcDmMsg (dmEvt_t *pMsg)
 Process security-related DM messages for a slave. This function should be called from the application's event handler. More...
 
void AppMasterProcDmMsg (dmEvt_t *pMsg)
 Process connection-related DM messages for a master. This function should be called from the application's event handler. More...
 
void AppMasterSecProcDmMsg (dmEvt_t *pMsg)
 Process security-related DM messages for a master. This function should be called from the application's event handler. More...
 
void AppServerConnCback (dmEvt_t *pDmEvt)
 ATT connection callback for app framework. This function is used when the application is operating as an ATT server and it uses notifications or indications. This function can be called by the application's ATT connection callback or it can be installed as the ATT connection callback. More...
 
APP Service Discovery

GATT Service Discovery initialization, configuration and execution.

void AppDiscInit (void)
 Initialize app framework discovery. More...
 
void AppDiscRegister (appDiscCback_t cback)
 Register a callback function to service discovery status. More...
 
void AppDiscSetHdlList (dmConnId_t connId, uint8_t hdlListLen, uint16_t *pHdlList)
 Set the discovery cached handle list for a given connection. More...
 
void AppDiscComplete (dmConnId_t connId, uint8_t status)
 Service discovery or configuration procedure complete. More...
 
void AppDiscFindService (dmConnId_t connId, uint8_t uuidLen, uint8_t *pUuid, uint8_t listLen, attcDiscChar_t **pCharList, uint16_t *pHdlList)
 Perform service and characteristic discovery for a given service. More...
 
void AppDiscConfigure (dmConnId_t connId, uint8_t status, uint8_t cfgListLen, attcDiscCfg_t *pCfgList, uint8_t hdlListLen, uint16_t *pHdlList)
 Configure characteristics for discovered services. More...
 
void AppDiscServiceChanged (attEvt_t *pMsg)
 Perform the GATT service changed procedure. This function is called when an indication is received containing the GATT service changed characteristic. This function may initialize the discovery state and initiate service discovery and configuration. More...
 
void AppDiscProcDmMsg (dmEvt_t *pMsg)
 Process discovery-related DM messages. This function should be called from the application's event handler. More...
 
void AppDiscProcAttMsg (attEvt_t *pMsg)
 Process discovery-related ATT messages. This function should be called from the application's event handler. More...
 
App Privacy Functions

Maintain privacy information about known peer devices.

void AppAddDevToResList (dmEvt_t *pMsg, dmConnId_t connId)
 Add device to resolving list. More...
 
void AppUpdatePrivacyMode (appDbHdl_t hdl)
 Update privacy mode for a given peer device. More...
 
App Event Handling

Message passing interface to App Framework from other tasks through WSF.

void AppHandlerInit (wsfHandlerId_t handlerId)
 App framework handler init function called during system initialization. More...
 
void AppHandler (wsfEventMask_t event, wsfMsgHdr_t *pMsg)
 WSF event handler for app framework. More...
 

Variables

appAdvCfg_tpAppAdvCfg
 This is a pointer to the advertising configurable parameters used by the application. If advertising is used, the application must set this variable during system initialization.
 
appExtAdvCfg_tpAppExtAdvCfg
 This is a pointer to the extended advertising configurable parameters used by the application. If extended advertising is used, the application must set this variable during system initialization.
 
appSlaveCfg_tpAppSlaveCfg
 This is a pointer to the slave configurable parameters used by the application. If slave mode is used, the application must set this variable during system initialization.
 
appMasterCfg_tpAppMasterCfg
 This is a pointer to the master configurable parameters used by the application. If master mode is used, the application must set this variable during system initialization.
 
appExtMasterCfg_tpAppExtMasterCfg
 This is a pointer to the extended master configurable parameters used by the application. If master mode is used, the application must set this variable during system initialization.
 
appSecCfg_tpAppSecCfg
 This is a pointer to the security-related configurable parameters used by the application. The application must set this variable during system initialization.
 
appUpdateCfg_tpAppUpdateCfg
 This is a pointer to the connection parameter update parameters used by the application. The application must set this variable during system initialization.
 
appDiscCfg_tpAppDiscCfg
 This is a pointer to the discovery parameters used by the application. The application must set this variable during system initialization.
 
appCfg_tpAppCfg
 This is a pointer to the application parameters used by the application. The application must set this variable during system initialization.
 
appReqActCfg_tpAppMasterReqActCfg
 This is a pointer to the master incoming request actions used by the application. The application must set this variable during system initialization.
 
appReqActCfg_tpAppSlaveReqActCfg
 This is a pointer to the master incoming request actions used by the application. The application must set this variable during system initialization.
 

Description

Application framework API.

Copyright (c) 2011-2018 Arm Ltd. All Rights Reserved. Arm Ltd. confidential and proprietary.

IMPORTANT. Your use of this file is governed by a Software License Agreement ("Agreement") that must be accepted in order to download or otherwise receive a copy of this file. You may not use or copy this file for any purpose other than as described in the Agreement. If you do not agree to all of the terms of the Agreement do not use this file and delete all copies in your possession or control; if you do not have a copy of the Agreement, you must contact Arm Ltd. prior to any use, copying or further distribution of this software.

Definition in file app_api.h.