GAP.docx

GAP.docx

《GAP.docx》由会员分享，可在线阅读，更多相关《GAP.docx（15页珍藏版）》请在冰豆网上搜索。

GAP

BLEProtocol

GAPAPI

FUNCTIONS

MadebyfjcGZU-tek2013-01-30

/*-------------------------------------------------------------------

*FUNCTIONS-InitializationandConfiguation

*/

/**

*@briefCalledtosetupthedevice.Calljustonceoninitialization.

*

*NOTE:

Wheninitializationiscomplete,thecallingappwillbe

*senttheGAP_DEVICE_INIT_DONE_EVENT

*

*@paramtaskID-DefaulttaskIDtosendevents.

*@paramprofileRole-GAPProfileRoles:

@refGAP_PROFILE_ROLE_DEFINES

*@parammaxScanResponses-maximumnumbertoscanresponses

*wecanreceiveduringadevicediscovery.

*@parampIRK-pointertoIdentityRootKey,NULLKEY（allzeroes）iftheapp

*wantstheGAPtogeneratethekey.

*@parampSRK-pointertoSignResolvingKey,NULLKEYiftheapp

*wantstheGAPtogeneratethekey.

*@parampSignCounter-32bitvalueusedintheSMSigning

*algorithmthatshallbeinitializedtozeroandincremented

*witheverynewsigning.Thisvariablemustalsobemaintained

*bytheapplication.

*

*@returnSUCCESS-Processing,expectGAP_DEVICE_INIT_DONE_EVENT,

*INVALIDPARAMETER-forinvalidprofileroleorrolecombination,

*bleIncorrectMode-troublecommunicatingwithHCI

*/

externbStatus_tGAP_DeviceInit（uint8taskID,

uint8profileRole,

uint8maxScanResponses,

uint8*pIRK,

uint8*pSRK,

uint32*pSignCounter）;

/**

*@briefCalledtosetupaGAPAdvertisement/ScanResponsedatatoken.

*

*NOTE:

Thedataintheseitemsarestoredaslowbytefirst（OTAformat）.

*Thepassedinstructure"token"shouldbeallocatedbythecallingapp/profile

*andnotreleaseduntilaftercallingGAP_RemoveAdvToken（）.

*

*@parampToken-Advertisement/Scanresponsetokentowrite.

*

*@returnSUCCESS-advertisementtokenaddedtotheGAPlist

*INVALIDPARAMETER-InvalidAdvertisementTypeorpAttrDataisNULL

*INVALID_MEM_SIZE-Thetokenstakeuptoomuchspaceanddon'tfitintoAdvertismentdataandScanResponseData

*bleInvalidRange-tokenIDalreadyexists.

*bleIncorrectMode-notaperipheraldevice

*bleMemAllocError-memoryallocationfailure,

*/

externbStatus_tGAP_SetAdvToken（gapAdvDataToken_t*pToken）;

/**

*@briefCalledtoreadaGAPAdvertisement/ScanResponsedatatoken.

*

*@paramadType-Advertisementtypetoget

*

*@returnpointertotheadvertisementdatatokenstructure,NULLifnotfound.

*/

externgapAdvDataToken_t*GAP_GetAdvToken（uint8adType）;

/**

*@briefCalledtoremoveaGAPAdvertisement/ScanResponsedatatoken.

*

*@paramadType-Advertisementtypetoremove

*

*@returnpointertothetokenstructureremovedfromtheGAPADTypelist

*NULLiftherequestedadTypewasn'tfound.

*/

externgapAdvDataToken_t*GAP_RemoveAdvToken（uint8adType）;

/**

*@briefCalledtorebuildandloadAdvertisementandScanResponsedatafromexisting

*GAPAdvertisementTokens.

*

*@returnSUCCESSorbleIncorrectMode

*/

externbStatus_tGAP_UpdateAdvTokens（void）;

/**

*@briefSetaGAPParametervalue.Usethisfunctiontochange

*thedefaultGAPparametervalues.

*

*@paramparamID-parameterID:

@refGAP_PARAMETER_ID_DEFINES

*@paramparamValue-newparamvalue

*

*@returnSUCCESSorINVALIDPARAMETER（invalidparamID）

*/

externbStatus_tGAP_SetParamValue（gapParamIDs_tparamID,uint16paramValue）;

/**

*@briefGetaGAPParametervalue.

*

*@paramparamID-parameterID:

@refGAP_PARAMETER_ID_DEFINES

*

*@returnGAPParametervalueor0xFFFFifinvalid

*/

externuint16GAP_GetParamValue（gapParamIDs_tparamID）;

/**

*@briefSetupthedevice'saddresstype.IfADDRTYPE_PRIVATE_RESOLVE

*isselected,theaddresswillchangeperiodically.

*

*@paramaddrType-@refGAP_ADDR_TYPE_DEFINES

*@parampStaticAddr-OnlyusedwithADDRTYPE_STATIC

*orADDRTYPE_PRIVATE_NONRESOLVEtype.

*NULLtoautogenerateotherwisetheapplication

*canspecifytheaddressvalue

*

*@returnSUCCESS:

addresstypeupdated,

*bleNotReady:

Can'tbecalleduntilGAP_DeviceInit（）iscalled

*andtheinitprocessiscompleted,

*bleIncorrectMode:

can'tchangewithanactiveconnection,

*orINVALIDPARAMETER.

*

*Ifreturnvalueisn'tSUCCESS,theaddresstyperemains

*thesameasbeforethiscall.

*/

externbStatus_tGAP_ConfigDeviceAddr（uint8addrType,uint8*pStaticAddr）;

/**

*@briefRegisteryourtaskIDtoreceiveextra（unwanted）

*HCIstatusandcompleteevents.

*

*@paramtaskID-DefaulttaskIDtosendevents.

*

*@returnnone

*/

externvoidGAP_RegisterForHCIMsgs（uint8taskID）;

/*-------------------------------------------------------------------

*FUNCTIONS-DeviceDiscovery

*/

/**

*@briefStartadevicediscoveryscan.

*

*@parampParams-DeviceDiscoveryparameters

*

*@returnSUCCESS:

scanstarted,

*bleIncorrectMode:

invalidprofilerole,

*bleAlreadyInRequestedMode:

notavailable

*/

externbStatus_tGAP_DeviceDiscoveryRequest（gapDevDiscReq_t*pParams）;

/**

*@briefCancelanexistingdevicediscoveryrequest.

*

*@paramtaskID-usedtoreturnGAP_DEVICE_DISCOVERY_EVENT

*

*@returnSUCCESS:

cancelstarted,

*bleInvalidTaskID:

Notthetaskthatstarteddiscovery,

*bleIncorrectMode:

notindiscoverymode

*/

externbStatus_tGAP_DeviceDiscoveryCancel（uint8taskID）;

/**

*@briefSetuporchangeadvertising.Alsostartsadvertising.

*

*@paramtaskID-usedtoreturnGAP_DISCOVERABLE_RESPONSE_EVENT

*@parampParams-advertisingparameters

*

*@returnSUCCESS:

advertisingstarted,

*bleIncorrectMode:

invalidprofilerole,

*bleAlreadyInRequestedMode:

notavailableatthistime,

*bleNotReady:

advertisingdataisn'tsetupyet.

*/

externbStatus_tGAP_MakeDiscoverable（uint8taskID,gapAdvertisingParams_t*pParams）;

/**

*@briefSetuporchangeadvertisingandscanresponsedata.

*

*NOTE:

ifthereturnstatusfromthisfunctionisSUCCESS,

*thetaskisn'tcompleteuntiltheGAP_ADV_DATA_UPDATE_DONE_EVENT

*issenttothecallingapplicationtask.

*

*@paramtaskID-taskIDoftheapprequestingthechange

*@paramadType-TRUE-advertisementdata,FALSE-scanresponsedata

*@paramdataLen-OctetlengthofadvertData

*@parampAdvertData-advertisingorscanresponsedata

*

*@returnSUCCESS:

dataaccepted,

*bleIncorrectMode:

invalidprofilerole,

*/

externbStatus_tGAP_UpdateAdvertisingData（uint8taskID,uint8adType,

uint8dataLen,uint8*pAdvertData）;

/**

*@briefStopsadvertising.

*

*@paramtaskID-oftaskthatcalledGAP_MakeDiscoverable

*

*@returnSUCCESS:

stoppingdiscoverablemode,

*bleIncorrectMode:

notindiscoverablemode,

*bleInvalidTaskID:

notcorrecttask

*/

externbStatus_tGAP_EndDiscoverable（uint8taskID）;

/**

*@briefResolvesaprivateaddressagainstanIRK.

*

*@parampIRK-pointertotheIRK

*@parampAddr-pointertotheResovablePrivateaddress

*

*@returnSUCCESS:

match,

*FAILURE:

don'tmatch,

*INVALIDPARAMETER:

parametersinvalid

*/

externbStatus_tGAP_ResolvePrivateAddr（uint8*pIRK,uint8*pAddr）;

/*-------------------------------------------------------------------

*FUNCTIONS-LinkEstablishment

*/

/**

*@briefEstablishalinktoaslavedevice.

*

*@parampParams-linkestablishmentparameters

*

*@returnSUCCESS:

startedestablishlinkprocess,

*bleIncorrectMode:

invalidprofilerole,

*bleNotReady:

ascanisinprogress,

*bleAlreadyInRequestedMode:

can抰processnow,

*bleNoResources:

Toomanylinks

*/

externbStatus_tGAP_EstablishLinkReq（gapEstLinkReq_t*pParams）;

/**

*@briefTerminatealinkconnection.

*

*@paramtaskID-requestingapp'staskid.

*@paramconnectionHandle-connectionhandleoflinktoterminate

*or@refGAP_CONN_HANDLE_DEFINES

*

*@returnSUCCESS:

Terminatestarted,

*bleIncorrectMode:

NoLinktoterminate,

*bleInvalidTaskID:

notappthatestablishedlink

*/

externbStatus_tGAP_TerminateLinkReq（uint8taskID,uint16connectionHandle）;

/**

*@briefReturnsthenumberofactiveconnections.

*

*@returnNumberofactiveconnections.

*/

externuint8GAP_NumActiveConnections（void）;

/*-------------------------------------------------------------------

*FUNCTIONS-Pairing

*/

/**

*@briefStarttheAuthenticationprocesswiththerequesteddevice.

*ThisfunctionisusedtoInitiate/Allowpairing.

*Calledbybothmasterandslavedevice（CentralandPeripheral）.

*

*NOTE:

Thisfunctioniscalledafterthelinkisestablished.

*

*@parampParams-Authenticationparameters

*@parampPairReq-EntertheseparametersifthePairingRequestwasalreadyreceived.

*NULL,ifwaitingforPairingRequestorifinitiating.

*

*@returnSUCCESS,

*bleIncorrectMode:

Notcorrectprofilerole,

*INVALIDPARAMETER,

*bleNotConnected,

*bleAlreadyInRequestedMode,

*FAILURE-notworkable.

*/

externbStatus_tGAP_Authenticate（gapAuthParams_t*pParams,gapPairingReq_t*pPairReq）;

/**

*@briefSendaPairingFailedmessageandendanyexistingpairing.

*

*@paramconnectionHandle-connectionhandle.

*@paramreason-PairingFailedreasoncode.

*

*@returnSUCCESS-functionwassuccessful,

*bleMemAllocError-memoryallocationerror,

*INVALIDPARAMETER-oneoftheparameterswereinvalid,

*bleInvalidRange-oneoftheparameterswerenotwithinrange.

*/

externbStatus_tGAP_TerminateAuth（uint16connectionHandle,uint8reason）;

/**

*@briefUpdatethepasskeyinstringformat.Thisfunctioniscal