TI BLE-Stack for Bluetooth 4.2 API Documentation  3.01.00.07
Modules | Files | Functions
ATT / GATT

This module implements the Attribute Protocol and Generic Attribute Protocol For a detailed usage section describing how to send these commands and receive events, see the GATT Section of the User's Guide. More...

Modules

 ATT / GATT Constants
 
 ATT / GATT Stuctures
 
 ATT API Functions
 

Files

file  att.h
 ATT layer interface.
 
file  gatt.h
 GATT layer interface.
 

Functions

void * GATT_bm_alloc (uint16 connHandle, uint8 opcode, uint16 size, uint16 *pSizeAlloc)
 GATT implementation of the allocator functionality. More...
 
void GATT_bm_free (gattMsg_t *pMsg, uint8 opcode)
 GATT implementation of the de-allocator functionality. More...
 
bStatus_t GATT_DeregisterService (uint16 handle, gattService_t *pService)
 Deregister a service attribute list with the GATT Server. More...
 
bStatus_t GATT_DiscAllCharDescs (uint16 connHandle, uint16 startHandle, uint16 endHandle, uint8 taskId)
 Discovery All Characteristic Descriptors. More...
 
bStatus_t GATT_DiscAllChars (uint16 connHandle, uint16 startHandle, uint16 endHandle, uint8 taskId)
 Discover all Characteristics. More...
 
bStatus_t GATT_DiscAllPrimaryServices (uint16 connHandle, uint8 taskId)
 Discovery All Primary Services. More...
 
bStatus_t GATT_DiscCharsByUUID (uint16 connHandle, attReadByTypeReq_t *pReq, uint8 taskId)
 Discovery Characteristics by UUID. More...
 
bStatus_t GATT_DiscPrimaryServiceByUUID (uint16 connHandle, uint8 *pUUID, uint8 len, uint8 taskId)
 Discovery Primary Service by UUID. More...
 
bStatus_t GATT_ExchangeMTU (uint16 connHandle, attExchangeMTUReq_t *pReq, uint8 taskId)
 Exchange MTU Request. More...
 
bStatus_t GATT_ExecuteWriteReq (uint16 connHandle, attExecuteWriteReq_t *pReq, uint8 taskId)
 ATT_ExecuteWriteReq More...
 
gattAttribute_tGATT_FindHandle (uint16 handle, uint16 *pHandle)
 Find the attribute record for a given handle. More...
 
gattAttribute_tGATT_FindHandleUUID (uint16 startHandle, uint16 endHandle, const uint8 *pUUID, uint16 len, uint16 *pHandle)
 Find the attribute record for a given handle and UUID. More...
 
bStatus_t GATT_FindIncludedServices (uint16 connHandle, uint16 startHandle, uint16 endHandle, uint8 taskId)
 This sub-procedure is used by a client to find include service declarations within a service definition on a server. The service specified is identified by the service handle range. More...
 
gattAttribute_tGATT_FindNextAttr (gattAttribute_t *pAttr, uint16 endHandle, uint16 service, uint16 *pLastHandle)
 Find the next attribute of the same type for a given attribute. More...
 
bStatus_t GATT_Indication (uint16 connHandle, attHandleValueInd_t *pInd, uint8 authenticated, uint8 taskId)
 Send a GATT Indication. More...
 
bStatus_t GATT_InitClient (void)
 Initialize the Generic Attribute Profile Client. More...
 
bStatus_t GATT_InitServer (void)
 Initialize the Generic Attribute Profile Server. More...
 
bStatus_t GATT_Notification (uint16 connHandle, attHandleValueNoti_t *pNoti, uint8 authenticated)
 Send a GATT Notification. More...
 
bStatus_t GATT_NotifyEvent (uint16 connHandle, uint8 status, uint8 method, gattMsg_t *pMsg)
 Send an event to upper layer application/protocol. More...
 
bStatus_t GATT_PrepareWriteReq (uint16 connHandle, attPrepareWriteReq_t *pReq, uint8 taskId)
 Request the server to prepare to write the value of an attribute. More...
 
bStatus_t GATT_ReadCharDesc (uint16 connHandle, attReadReq_t *pReq, uint8 taskId)
 Read Characteristic Descriptor. More...
 
bStatus_t GATT_ReadCharValue (uint16 connHandle, attReadReq_t *pReq, uint8 taskId)
 Read Characteristic Value. More...
 
bStatus_t GATT_ReadLongCharDesc (uint16 connHandle, attReadBlobReq_t *pReq, uint8 taskId)
 Read Long Characteristic Descriptor. More...
 
bStatus_t GATT_ReadLongCharValue (uint16 connHandle, attReadBlobReq_t *pReq, uint8 taskId)
 Read Long Characteristic Value. More...
 
bStatus_t GATT_ReadMultiCharValues (uint16 connHandle, attReadMultiReq_t *pReq, uint8 taskId)
 Read Multiple Characteristic Values. More...
 
bStatus_t GATT_ReadUsingCharUUID (uint16 connHandle, attReadByTypeReq_t *pReq, uint8 taskId)
 Read Using Characteristic UUID. More...
 
void GATT_RegisterForInd (uint8 taskId)
 Register to receive incoming ATT Indications or Notifications of attribute values. More...
 
void GATT_RegisterForMsgs (uint8 taskID)
 GATT Register for Messages. More...
 
void GATT_RegisterForReq (uint8 taskId)
 Register to receive incoming ATT Requests. More...
 
bStatus_t GATT_RegisterService (gattService_t *pService)
 Register a service attribute list with the GATT Server. More...
 
bStatus_t GATT_ReliableWrites (uint16 connHandle, attPrepareWriteReq_t *pReqs, uint8 numReqs, uint8 flags, uint8 taskId)
 Do a Reliable Write. More...
 
bStatus_t GATT_SendRsp (uint16 connHandle, uint8 method, gattMsg_t *pRsp)
 Send an ATT Response message out. More...
 
uint8 GATT_ServiceChangedInd (uint16 connHandle, uint8 taskId)
 Send out a Service Changed Indication. More...
 
uint8 GATT_ServiceEncKeySize (uint16 handle)
 Get the minimum encryption key size required by a given service. More...
 
uint16 GATT_ServiceNumAttrs (uint16 handle)
 Get the number of attributes for a given service. More...
 
bStatus_t GATT_SignedWriteNoRsp (uint16 connHandle, attWriteReq_t *pReq)
 Signed Write No Response. More...
 
void GATT_UpdateMTU (uint16 connHandle, uint16 mtuSize)
 Update ATT_MTU size for a given connection. More...
 
bStatus_t GATT_VerifyReadPermissions (uint16 connHandle, uint8 permissions, uint16 service)
 Verify the permissions of an attribute for reading. More...
 
bStatus_t GATT_VerifyWritePermissions (uint16 connHandle, uint8 permissions, uint16 service, attWriteReq_t *pReq)
 Verify the permissions of an attribute for writing. More...
 
bStatus_t GATT_WriteCharDesc (uint16 connHandle, attWriteReq_t *pReq, uint8 taskId)
 Write Characteristic Descriptor. More...
 
bStatus_t GATT_WriteCharValue (uint16 connHandle, attWriteReq_t *pReq, uint8 taskId)
 Write Characteristic Value. More...
 
bStatus_t GATT_WriteLongCharDesc (uint16 connHandle, attPrepareWriteReq_t *pReq, uint8 taskId)
 Write Long Characteristic Descriptor. More...
 
bStatus_t GATT_WriteLongCharValue (uint16 connHandle, attPrepareWriteReq_t *pReq, uint8 taskId)
 Write Long Characteristic Value. More...
 
bStatus_t GATT_WriteNoRsp (uint16 connHandle, attWriteReq_t *pReq)
 Write No Response. More...
 

Detailed Description

This module implements the Attribute Protocol and Generic Attribute Protocol For a detailed usage section describing how to send these commands and receive events, see the GATT Section of the User's Guide.

Function Documentation

§ GATT_bm_alloc()

void* GATT_bm_alloc ( uint16  connHandle,
uint8  opcode,
uint16  size,
uint16 *  pSizeAlloc 
)

GATT implementation of the allocator functionality.

Note
This function should only be called by GATT and the upper layer protocol/application.
Parameters
connHandle- connection that message is to be sent on.
opcode- opcode of message that buffer to be allocated for.
size- number of bytes to allocate from the heap.
pSizeAlloc- number of bytes allocated for the caller from the heap.
Returns
pointer to the heap allocation
NULL if error or failure.

§ GATT_bm_free()

void GATT_bm_free ( gattMsg_t pMsg,
uint8  opcode 
)

GATT implementation of the de-allocator functionality.

Parameters
pMsg- pointer to GATT message containing the memory to free.
opcode- opcode of the message

§ GATT_DeregisterService()

bStatus_t GATT_DeregisterService ( uint16  handle,
gattService_t pService 
)

Deregister a service attribute list with the GATT Server.

Warning
It's the caller's responsibility to free the service attribute list returned from this API.
Parameters
handle- handle of service to be deregistered
pService- pointer to deregistered service (to be returned)
Returns
SUCCESS : Service deregistered successfully.
FAILURE : Service not found.

§ GATT_DiscAllCharDescs()

bStatus_t GATT_DiscAllCharDescs ( uint16  connHandle,
uint16  startHandle,
uint16  endHandle,
uint8  taskId 
)

Discovery All Characteristic Descriptors.

This sub-procedure is used by a client to find all the characteristic descriptor's Attribute Handles and Attribute Types within a characteristic definition when only the characteristic handle range is known. The characteristic specified is identified by the characteristic handle range.

ATT_FindInfoReq is used with the Starting Handle set to starting handle of the specified characteristic and the Ending Handle set to the ending handle of the specified characteristic. The UUID Filter parameter is NULL (zero length).

Corresponding Events:
If the return status from this function is SUCCESS, the calling application task will receive multiple GATT_MSG_EVENT messages with method:
Note
This sub-procedure is complete when either ATT_FIND_INFO_RSP (with bleProcedureComplete or bleTimeout status) or ATT_ERROR_RSP (with SUCCESS status) is received by the calling task.
Parameters
connHandle- connection to use
startHandle- starting handle
endHandle- end handle
taskId- task to be notified of response
Returns
SUCCESS : Request was queued successfully.
INVALIDPARAMETER
MSG_BUFFER_NOT_AVAIL
bleNotConnected
blePending : A response is pending with this server.
bleMemAllocError
bleTimeout : Previous transaction timed out.

§ GATT_DiscAllChars()

bStatus_t GATT_DiscAllChars ( uint16  connHandle,
uint16  startHandle,
uint16  endHandle,
uint8  taskId 
)

Discover all Characteristics.

This sub-procedure is used by a client to find all the characteristic declarations within a service definition on a server when only the service handle range is known. The service specified is identified by the service handle range.

ATT_ReadByTypeReq is used with the Attribute Type parameter set to the UUID for "Characteristic". The Starting Handle is set to starting handle of the specified service and the Ending Handle is set to the ending handle of the specified service.

Corresponding Events:
If the return status from this function is SUCCESS, the calling application task will receive multiple GATT_MSG_EVENT messages with method:
Note
This sub-procedure is complete when either ATT_READ_BY_TYPE_RSP (with bleProcedureComplete or bleTimeout status) or ATT_ERROR_RSP (with SUCCESS status) is received by the calling task.
Parameters
connHandle- connection to use
startHandle- starting handle
endHandle- end handle
taskId- task to be notified of response
Returns
SUCCESS : Request was queued successfully.
INVALIDPARAMETER
MSG_BUFFER_NOT_AVAIL
bleNotConnected
blePending : A response is pending with this server.
bleMemAllocError
bleTimeout : Previous transaction timed out.

§ GATT_DiscAllPrimaryServices()

bStatus_t GATT_DiscAllPrimaryServices ( uint16  connHandle,
uint8  taskId 
)

Discovery All Primary Services.

This sub-procedure is used by a client to discover all the primary services on a server.

ATT_ReadByGrpTypeReq is used with the Attribute Type parameter set to the UUID for "Primary Service". The Starting Handle is set to 0x0001 and the Ending Handle is set to 0xFFFF.

Corresponding Events:
If the return status from this function is SUCCESS, the calling application task will receive multiple GATT_MSG_EVENT messages with method:
Note
This sub-procedure is complete when either ATT_READ_BY_GRP_TYPE_RSP (with bleProcedureComplete or bleTimeout status) or ATT_ERROR_RSP (with SUCCESS status) is received by the calling task
Parameters
connHandle- connection to use
taskId- task to be notified of response
Returns
SUCCESS : Request was queued successfully.
INVALIDPARAMETER
MSG_BUFFER_NOT_AVAIL
bleNotConnected
blePending : A response is pending with this server.
bleMemAllocError
bleTimeout : Previous transaction timed out.

§ GATT_DiscCharsByUUID()

bStatus_t GATT_DiscCharsByUUID ( uint16  connHandle,
attReadByTypeReq_t pReq,
uint8  taskId 
)

Discovery Characteristics by UUID.

This sub-procedure is used by a client to discover service characteristics on a server when only the service handle ranges are known and the characteristic UUID is known. The specific service may exist multiple times on a server. The characteristic being discovered is identified by the characteristic UUID.

ATT_ReadByTypeReq is used with the Attribute Type is set to the UUID for "Characteristic" and the Starting Handle and Ending Handle parameters is set to the service handle range.

Corresponding Events:
If the return status from this function is SUCCESS, the calling application task will receive multiple GATT_MSG_EVENT messages with method:
Note
This sub-procedure is complete when either ATT_READ_BY_TYPE_RSP (with bleProcedureComplete or bleTimeout status) or ATT_ERROR_RSP (with SUCCESS status) is received by the calling task.
Parameters
connHandle- connection to use
pReq- pointer to request to be sent
taskId- task to be notified of response
Returns
SUCCESS : Request was queued successfully.
INVALIDPARAMETER
MSG_BUFFER_NOT_AVAIL
bleNotConnected
blePending : A response is pending with this server.
bleMemAllocError
bleTimeout : Previous transaction timed out.

§ GATT_DiscPrimaryServiceByUUID()

bStatus_t GATT_DiscPrimaryServiceByUUID ( uint16  connHandle,
uint8 *  pUUID,
uint8  len,
uint8  taskId 
)

Discovery Primary Service by UUID.

This sub-procedure is used by a client to discover a specific primary service on a server when only the Service UUID is known. The primary specific service may exist multiple times on a server. The primary service being discovered is identified by the service UUID.

ATT_FindByTypeValueReq is used with the Attribute Type parameter set to the UUID for "Primary Service" and the Attribute Value set to the 16-bit Bluetooth UUID or 128-bit UUID for the specific primary service. The Starting Handle shall be set to 0x0001 and the Ending Handle shall be set to 0xFFFF.

Corresponding Events:
If the return status from this function is SUCCESS, the calling application task will receive multiple GATT_MSG_EVENT messages with method:
Note
This sub-procedure is complete when either ATT_FIND_BY_TYPE_VALUE_RSP (with bleProcedureComplete or bleTimeout status) or ATT_ERROR_RSP (with SUCCESS status) is received by the calling task.
Parameters
connHandle- connection to use
pUUID- pointer to service UUID to look for
len- length of value
taskId- task to be notified of response
Returns
SUCCESS : Request was queued successfully.
INVALIDPARAMETER
MSG_BUFFER_NOT_AVAIL
bleNotConnected
blePending : A response is pending with this server.
bleMemAllocError
bleTimeout : Previous transaction timed out.

§ GATT_ExchangeMTU()

bStatus_t GATT_ExchangeMTU ( uint16  connHandle,
attExchangeMTUReq_t pReq,
uint8  taskId 
)

Exchange MTU Request.

This sub-procedure is used by the client to set the ATT_MTU to the maximum possible value that can be supported by both devices when the client supports a value greater than the default ATT_MTU for the Attribute Protocol. This sub-procedure shall only be initiated once during a connection.

ATT_ExchangeMTUReq is used by this sub-procedure.

Corresponding Events:
If the return status from this function is SUCCESS, the calling application task will receive a GATT_MSG_EVENT message with method:
Parameters
connHandle- connection to use
pReq- pointer to request to be sent
taskId- task to be notified of response
Returns
SUCCESS : Request was queued successfully.
INVALIDPARAMETER
MSG_BUFFER_NOT_AVAIL
bleNotConnected
blePending : A response is pending with this server.
bleMemAllocError
bleTimeout : Previous transaction timed out.

§ GATT_ExecuteWriteReq()

bStatus_t GATT_ExecuteWriteReq ( uint16  connHandle,
attExecuteWriteReq_t pReq,
uint8  taskId 
)

ATT_ExecuteWriteReq

Request the server to write or cancel the write of all the prepared values currently held in the prepare queue from this client.

Parameters
connHandle- connection to use
pReq- pointer to request to be sent
taskId- task to be notified of response
Returns
SUCCESS : Request was queued successfully.
INVALIDPARAMETER
MSG_BUFFER_NOT_AVAIL
bleNotConnected
blePending : A response is pending with this server.
bleMemAllocError
bleTimeout : Previous transaction timed out.

§ GATT_FindHandle()

gattAttribute_t* GATT_FindHandle ( uint16  handle,
uint16 *  pHandle 
)

Find the attribute record for a given handle.

Parameters
handle- handle to look for
pHandle- handle of owner of attribute (to be returned)
Returns
Pointer to attribute record.
NULL, otherwise.

§ GATT_FindHandleUUID()

gattAttribute_t* GATT_FindHandleUUID ( uint16  startHandle,
uint16  endHandle,
const uint8 *  pUUID,
uint16  len,
uint16 *  pHandle 
)

Find the attribute record for a given handle and UUID.

Parameters
startHandle- first handle to look for
endHandle- last handle to look for
pUUID- pointer to UUID to look for
len- length of UUID
pHandle- handle of owner of attribute (to be returned)
Returns
Pointer to attribute record.
NULL, otherwise.

§ GATT_FindIncludedServices()

bStatus_t GATT_FindIncludedServices ( uint16  connHandle,
uint16  startHandle,
uint16  endHandle,
uint8  taskId 
)

This sub-procedure is used by a client to find include service declarations within a service definition on a server. The service specified is identified by the service handle range.

ATT_ReadByTypeReq is used with the Attribute Type parameter set to the UUID for "Included Service". The Starting Handle is set to starting handle of the specified service and the Ending Handle is set to the ending handle of the specified service.

Corresponding Events:
If the return status from this function is SUCCESS, the calling application task will receive multiple GATT_MSG_EVENT messages with method:
Note
This sub-procedure is complete when either ATT_READ_BY_TYPE_RSP (with bleProcedureComplete or bleTimeout status) or ATT_ERROR_RSP (with SUCCESS status) is received by the calling task.
Parameters
connHandle- connection to use
startHandle- starting handle
endHandle- end handle
taskId- task to be notified of response
Returns
SUCCESS : Request was queued successfully.
INVALIDPARAMETER
MSG_BUFFER_NOT_AVAIL
bleNotConnected
blePending : A response is pending with this server.
bleMemAllocError
bleTimeout : Previous transaction timed out.

§ GATT_FindNextAttr()

gattAttribute_t* GATT_FindNextAttr ( gattAttribute_t pAttr,
uint16  endHandle,
uint16  service,
uint16 *  pLastHandle 
)

Find the next attribute of the same type for a given attribute.

Parameters
pAttr- pointer to attribute to find a next for
endHandle- last handle to look for
service- handle of owner service
pLastHandle- handle of last attribute (to be returned)
Returns
Pointer to next attribute record
NULL, otherwise.

§ GATT_Indication()

bStatus_t GATT_Indication ( uint16  connHandle,
attHandleValueInd_t pInd,
uint8  authenticated,
uint8  taskId 
)

Send a GATT Indication.

This sub-procedure is used when a server is configured to indicate a characteristic value to a client and expects an attribute protocol layer acknowledgement that the indication was successfully received.

ATT_HandleValueInd is used in this sub-procedure.

Corresponding Events
If the return status from this function is SUCCESS and the GATT client succesfully sends an acknowledgement, the calling application task will receive a GATT_MSG_EVENT message with method: ATT_HANDLE_VALUE_CFM of type attHandleValueInd_t , with status SUCCESS or bleTimeout . At this point, the procedure is complete.
Warning
The payload must be dynamically allocated using GATT_bm_alloc
Note
The client must use GATT_RegisterForInd in order to receive Indications in the application task and use ATT_HandleValueCfm to return the acknowledgement to the server
Parameters
connHandle- connection to use
pInd- pointer to indication to be sent
authenticated- whether an authenticated link is required 0x01: LE Legacy authenticated 0x02: Secure Connections authenticated
taskId- task to be notified of response
Returns
SUCCESS : Indication was queued successfully.
INVALIDPARAMETER
MSG_BUFFER_NOT_AVAIL
bleNotConnected
blePending : A confirmation is pending with this client.
bleMemAllocError
bleInvalidMtuSize : Packet length is larger than connection's MTU size.
bleTimeout : Previous transaction timed out.

§ GATT_InitClient()

bStatus_t GATT_InitClient ( void  )

Initialize the Generic Attribute Profile Client.

Note
GATT Clients must call this from the application init function
Returns
SUCCESS : Client initialized successfully.
bleMemAllocError

§ GATT_InitServer()

bStatus_t GATT_InitServer ( void  )

Initialize the Generic Attribute Profile Server.

Note
This is called by the stack initizliation functions
Returns
SUCCESS : Server initialized successfully.
bleMemAllocError

§ GATT_Notification()

bStatus_t GATT_Notification ( uint16  connHandle,
attHandleValueNoti_t pNoti,
uint8  authenticated 
)

Send a GATT Notification.

This sub-procedure is used when a server is configured to notify a characteristic value to a client without expecting any attribute protocol layer acknowledgement that the notification was successfully received.

ATT_HandleValueNoti is used in this sub-procedure.

Note
A notification may be sent at any time. No confirmation will be sent to the calling task for this sub-procedure.
Warning
The payload must be dynamically allocated using GATT_bm_alloc
Note
The client must use GATT_RegisterForInd in order to receive Notifications in the application task
Parameters
connHandle- connection to use
pNoti- pointer to notification to be sent
authenticated- whether an authenticated link is required 0x01: LE Legacy authenticated 0x02: Secure Connections authenticated
Returns
SUCCESS : Notification was queued successfully.
INVALIDPARAMETER
MSG_BUFFER_NOT_AVAIL
bleNotConnected
bleMemAllocError
bleInvalidMtuSize : Packet length is larger than connection's MTU size.
bleTimeout : Previous transaction timed out.

§ GATT_NotifyEvent()

bStatus_t GATT_NotifyEvent ( uint16  connHandle,
uint8  status,
uint8  method,
gattMsg_t pMsg 
)

Send an event to upper layer application/protocol.

Parameters
connHandle- connection event belongs to
status- status
method- type of message
pMsg- pointer to message to be sent
Returns
SUCCESS
INVALIDPARAMETER
bleMemAllocError

§ GATT_PrepareWriteReq()

bStatus_t GATT_PrepareWriteReq ( uint16  connHandle,
attPrepareWriteReq_t pReq,
uint8  taskId 
)

Request the server to prepare to write the value of an attribute.

Parameters
connHandle- connection to use
pReq- pointer to request to be sent
taskId- task to be notified of response
Returns
SUCCESS : Request was queued successfully.
INVALIDPARAMETER
MSG_BUFFER_NOT_AVAIL
bleNotConnected
blePending : A response is pending with this server.
bleMemAllocError
bleTimeout : Previous transaction timed out.

§ GATT_ReadCharDesc()

bStatus_t GATT_ReadCharDesc ( uint16  connHandle,
attReadReq_t pReq,
uint8  taskId 
)

Read Characteristic Descriptor.

This sub-procedure is used to read a characteristic descriptor from a server when the client knows the characteristic descriptor declaration's Attribute handle.

ATT_ReadReq is used for this sub-procedure. with the Attribute Handle parameter set to the characteristic descriptor handle.

Corresponding Events:
If the return status from this function is SUCCESS, the calling application task will receive a GATT_MSG_EVENT message with method:
Note
This sub-procedure is complete when either ATT_READ_RSP (with SUCCESS or bleTimeout status) or ATT_ERROR_RSP (with SUCCESS status) is received by the calling task.
Parameters
connHandle- connection to use
pReq- pointer to request to be sent
taskId- task to be notified of response
Returns
SUCCESS : Request was queued successfully.
INVALIDPARAMETER
MSG_BUFFER_NOT_AVAIL
bleNotConnected
blePending : A response is pending with this server.
bleMemAllocError
bleTimeout : Previous transaction timed out.

§ GATT_ReadCharValue()

bStatus_t GATT_ReadCharValue ( uint16  connHandle,
attReadReq_t pReq,
uint8  taskId 
)

Read Characteristic Value.

This sub-procedure is used to read a Characteristic Value from a server when the client knows the Characteristic Value Handle.

ATT_ReadReq is used with the Attribute Handle parameter set to the Characteristic Value Handle. The Read Response returns the Characteristic Value in the Attribute Value parameter.

Note
: The Read Response only contains a Characteristic Value that is less than or equal to (ATT_MTU - 1) octets in length. If the Characteristic Value is greater than (ATT_MTU - 1) octets in length, the Read Long Characteristic Value procedure may be used if the rest of the Characteristic Value is required.
Corresponding Events:
If the return status from this function is SUCCESS, the calling application task will receive a GATT_MSG_EVENT message with method:
Note
This sub-procedure is complete when either ATT_READ_RSP (with SUCCESS or bleTimeout status) or ATT_ERROR_RSP (with SUCCESS status) is received by the calling task.
Parameters
connHandle- connection to use
pReq- pointer to request to be sent
taskId- task to be notified of response
Returns
SUCCESS : Request was queued successfully.
INVALIDPARAMETER
MSG_BUFFER_NOT_AVAIL
bleNotConnected
blePending : A response is pending with this server.
bleMemAllocError
bleTimeout : Previous transaction timed out.

§ GATT_ReadLongCharDesc()

bStatus_t GATT_ReadLongCharDesc ( uint16  connHandle,
attReadBlobReq_t pReq,
uint8  taskId 
)

Read Long Characteristic Descriptor.

This sub-procedure is used to read a characteristic descriptor from a server when the client knows the characteristic descriptor declaration's Attribute handle and the length of the characteristic descriptor declaration is longer than can be sent in a single Read Response attribute protocol message.

ATT_ReadBlobReq is used to perform this sub-procedure. The Attribute Handle parameter shall be set to the characteristic descriptor handle. The Value Offset parameter shall be the offset within the characteristic descriptor to be read.

Corresponding Events:
If the return status from this function is SUCCESS, the calling application task will receive a GATT_MSG_EVENT message with method:
Note
This sub-procedure is complete when either ATT_READ_BLOB_RSP (with bleProcedureComplete or bleTimeout status) or ATT_ERROR_RSP (with SUCCESS status) is received by the calling task.
Parameters
connHandle- connection to use
pReq- pointer to request to be sent
taskId- task to be notified of response
Returns
SUCCESS : Request was queued successfully.
INVALIDPARAMETER
MSG_BUFFER_NOT_AVAIL
bleNotConnected
blePending : A response is pending with this server.
bleMemAllocError
bleTimeout : Previous transaction timed out.

§ GATT_ReadLongCharValue()

bStatus_t GATT_ReadLongCharValue ( uint16  connHandle,
attReadBlobReq_t pReq,
uint8  taskId 
)

Read Long Characteristic Value.

This sub-procedure is used to read a Characteristic Value from a server when the client knows the Characteristic Value Handle and the length of the Characteristic Value is longer than can be sent in a single Read Response Attribute Protocol message.

ATT_ReadBlobReq is used in this sub-procedure.

Corresponding Events:
If the return status from this function is SUCCESS, the calling application task will receive multiple GATT_MSG_EVENT messages with method:
Note
This sub-procedure is complete when either ATT_READ_BLOB_RSP (with bleProcedureComplete or bleTimeout status) or ATT_ERROR_RSP (with SUCCESS status) is received by the calling task.
Parameters
connHandle- connection to use
pReq- pointer to request to be sent
taskId- task to be notified of response
Returns
SUCCESS : Request was queued successfully.
INVALIDPARAMETER
MSG_BUFFER_NOT_AVAIL
bleNotConnected
blePending : A response is pending with this server.
bleMemAllocError
bleTimeout : Previous transaction timed out.

§ GATT_ReadMultiCharValues()

bStatus_t GATT_ReadMultiCharValues ( uint16  connHandle,
attReadMultiReq_t pReq,
uint8  taskId 
)

Read Multiple Characteristic Values.

This sub-procedure is used to read multiple Characteristic Values from a server when the client knows the Characteristic Value Handles. The Attribute Protocol Read Multiple Requests is used with the Set Of Handles parameter set to the Characteristic Value Handles. The Read Multiple Response returns the Characteristic Values in the Set Of Values parameter.

ATT_ReadMultiReq is used in this sub-procedure.

Corresponding Events:
If the return status from this function is SUCCESS, the calling application task will receive a GATT_MSG_EVENT message with method:
Note
This sub-procedure is complete when either ATT_READ_MULTI_RSP (with SUCCESS or bleTimeout status) or ATT_ERROR_RSP (with SUCCESS status) is received by the calling task.
Parameters
connHandle- connection to use
pReq- pointer to request to be sent
taskId- task to be notified of response
Returns
SUCCESS : Request was queued successfully.
INVALIDPARAMETER
MSG_BUFFER_NOT_AVAIL
bleNotConnected
blePending : A response is pending with this server.
bleMemAllocError
bleTimeout : Previous transaction timed out.

§ GATT_ReadUsingCharUUID()

bStatus_t GATT_ReadUsingCharUUID ( uint16  connHandle,
attReadByTypeReq_t pReq,
uint8  taskId 
)

Read Using Characteristic UUID.

This sub-procedure is used to read a Characteristic Value from a server when the client only knows the characteristic UUID and does not know the handle of the characteristic.

ATT_ReadByTypeReq is used to perform the sub-procedure. The Attribute Type is set to the known characteristic UUID and the Starting Handle and Ending Handle parameters shall be set to the range over which this read is to be performed. This is typically the handle range for the service in which the characteristic belongs.

Corresponding Events:
If the return status from this function is SUCCESS, the calling application task will receive a GATT_MSG_EVENT messages with method:
Note
This sub-procedure is complete when either ATT_READ_BY_TYPE_RSP (with SUCCESS or bleTimeout status) or ATT_ERROR_RSP (with SUCCESS status) is received by the calling task.
Parameters
connHandle- connection to use
pReq- pointer to request to be sent
taskId- task to be notified of response
Returns
SUCCESS : Request was queued successfully.
INVALIDPARAMETER
MSG_BUFFER_NOT_AVAIL
bleNotConnected
blePending : A response is pending with this server.
bleMemAllocError
bleTimeout : Previous transaction timed out.

§ GATT_RegisterForInd()

void GATT_RegisterForInd ( uint8  taskId)

Register to receive incoming ATT Indications or Notifications of attribute values.

Note
GATT Clients must call this from the application init function
Parameters
taskId- task to forward indications or notifications to

§ GATT_RegisterForMsgs()

void GATT_RegisterForMsgs ( uint8  taskID)

GATT Register for Messages.

Register your task ID to receive GATT local events and ATT Response messages pending for transmission. When the GATT Server fails to respond to an incoming ATT Request due to lack of HCI Tx buffers, the response will be forwarded the app for retransmission.

Note: A pending ATT Response message forwarded to the app should be transmitted using GATT_SendRsp(), or its payload freed using GATT_bm_free() if not transmitted.

Parameters
taskID- Default task ID to send GATT events/pending ATT responses.

§ GATT_RegisterForReq()

void GATT_RegisterForReq ( uint8  taskId)

Register to receive incoming ATT Requests.

Parameters
taskId- task to forward requests to

§ GATT_RegisterService()

bStatus_t GATT_RegisterService ( gattService_t pService)

Register a service attribute list with the GATT Server.

A service is composed of characteristics or references to other services. Each characteristic contains a value and may contain optional information about the value. There are two types of services: primary service and secondary service.

A service definition begins with a service declaration and ends before the next service declaration or the maximum Attribute Handle.

A characteristic definition begins with a characteristic declaration and ends before the next characteristic or service declaration or maximum Attribute Handle.

The attribute server will only keep a pointer to the attribute list, so the calling application will have to maintain the code and RAM associated with this list.

Parameters
pService- pointer to service attribute list to be registered
Returns
SUCCESS : Service registered successfully.
INVALIDPARAMETER : Invalid service field.
FAILURE : Not enough attribute handles available.
bleMemAllocError
bleInvalidRange :Encryption key size's out of range.

§ GATT_ReliableWrites()

bStatus_t GATT_ReliableWrites ( uint16  connHandle,
attPrepareWriteReq_t pReqs,
uint8  numReqs,
uint8  flags,
uint8  taskId 
)

Do a Reliable Write.

This sub-procedure is used to write a Characteristic Value to a server when the client knows the Characteristic Value Handle, and assurance is required that the correct Characteristic Value is going to be written by transferring the Characteristic Value to be written in both directions before the write is performed. This sub-procedure can also be used when multiple values must be written, in order, in a single operation.

The sub-procedure has two phases, the first phase prepares the characteristic values to be written. Once this is complete, the second phase performs the execution of all of the prepared characteristic value writes on the server from this client. In the first phase, ATT_PrepareWriteReq is used. In the second phase, ATT_ExecuteWriteReq is used.

Corresponding Events:
If the return status from this function is SUCCESS, the calling application task will receive a GATT_MSG_EVENT message with method:
Note
This sub-procedure is complete when either ATT_PREPARE_WRITE_RSP (with bleTimeout status), ATT_EXECUTE_WRITE_RSP (with SUCCESS or bleTimeout status), or ATT_ERROR_RSP (with SUCCESS status) is received by the calling task.
Warning
The 'pReqs' pointer will be freed when the sub-procedure is complete.
Parameters
connHandle- connection to use
pReqs- pointer to requests to be sent (must be allocated)
numReqs- number of requests in pReq
flags- ATT_ExecuteWriteReq flags
taskId- task to be notified of response
Returns
SUCCESS : Request was queued successfully.
INVALIDPARAMETER
MSG_BUFFER_NOT_AVAIL
bleNotConnected
blePending : A response is pending with this server.
bleMemAllocError
bleTimeout : Previous transaction timed out.

§ GATT_SendRsp()

bStatus_t GATT_SendRsp ( uint16  connHandle,
uint8  method,
gattMsg_t pRsp 
)

Send an ATT Response message out.

Parameters
connHandle- connection to use
method- type of response message
pRsp- pointer to ATT response to be sent
Returns
SUCCESS : Response was sent successfully.
INVALIDPARAMETER : Invalid response field.
MSG_BUFFER_NOT_AVAIL
bleNotConnected
bleMemAllocError
blePending : In the middle of another transmit.
bleInvalidMtuSize : Packet length is larger than connection's MTU size.

§ GATT_ServiceChangedInd()

uint8 GATT_ServiceChangedInd ( uint16  connHandle,
uint8  taskId 
)

Send out a Service Changed Indication.

Parameters
connHandle- connection to use
taskId- task to be notified of confirmation
Returns
SUCCESS : Indication was sent successfully.
FAILURE : Service Changed attribute not found.
INVALIDPARAMETER
MSG_BUFFER_NOT_AVAIL
bleNotConnected
blePending : A confirmation is pending with this client.

§ GATT_ServiceEncKeySize()

uint8 GATT_ServiceEncKeySize ( uint16  handle)

Get the minimum encryption key size required by a given service.

Parameters
handle- service handle to look for
Returns
Encryption key size if service found.
Default key size, otherwise.

§ GATT_ServiceNumAttrs()

uint16 GATT_ServiceNumAttrs ( uint16  handle)

Get the number of attributes for a given service.

Parameters
handle- service handle to look for
Returns
Number of attributes if service found. 0, otherwise.

§ GATT_SignedWriteNoRsp()

bStatus_t GATT_SignedWriteNoRsp ( uint16  connHandle,
attWriteReq_t pReq 
)

Signed Write No Response.

This sub-procedure is used to write a Characteristic Value to a server when the client knows the Characteristic Value Handle and the ATT Bearer is not encrypted. This sub-procedure shall only be used if the Characteristic Properties authenticated bit is enabled and the client and server device share a bond as defined in the GAP.

This sub-procedure only writes the first (ATT_MTU - 15) octets of an Attribute Value. This sub-procedure cannot be used to write a long Attribute.

ATT_WriteReq is used for this sub-procedure. The Attribute Handle parameter shall be set to the Characteristic Value Handle. The Attribute Value parameter shall be set to the new Characteristic Value authenticated by signing the value, as defined in the Security Manager.

Note
No response will be sent to the calling task for this sub-procedure. If the authenticated Characteristic Value that is written is the wrong size, or has an invalid value as defined by the profile, or the signed value does not authenticate the client, then the write will not succeed and no error will be generated by the server.
Parameters
connHandle- connection to use
pReq- pointer to command to be sent
Returns
SUCCESS : Request was queued successfully.
INVALIDPARAMETER
MSG_BUFFER_NOT_AVAIL
bleNotConnected
bleMemAllocError
bleLinkEncrypted: Connection is already encrypted.
bleTimeout : Previous transaction timed out.

§ GATT_UpdateMTU()

void GATT_UpdateMTU ( uint16  connHandle,
uint16  mtuSize 
)

Update ATT_MTU size for a given connection.

Parameters
connHandle- connection handle.
mtuSize- new MTU size.

§ GATT_VerifyReadPermissions()

bStatus_t GATT_VerifyReadPermissions ( uint16  connHandle,
uint8  permissions,
uint16  service 
)

Verify the permissions of an attribute for reading.

Parameters
connHandle- connection to use
permissions- attribute permissions
service- service handle
Returns
SUCCESS : Attribute can be read.
ATT_ERR_INSUFFICIENT_ENCRYPT : Attribute cannot be read.
ATT_ERR_INSUFFICIENT_AUTHEN : Attribute requires authentication.
ATT_ERR_INSUFFICIENT_KEY_SIZE : Key Size used for encrypting is insufficient.
ATT_ERR_INSUFFICIENT_ENCRYPT : Attribute requires encryption.

§ GATT_VerifyWritePermissions()

bStatus_t GATT_VerifyWritePermissions ( uint16  connHandle,
uint8  permissions,
uint16  service,
attWriteReq_t pReq 
)

Verify the permissions of an attribute for writing.

Parameters
connHandle- connection to use
permissions- attribute permissions
service- service handle
pReq- pointer to write request
Returns
SUCCESS : Attribute can be written.
ATT_ERR_INSUFFICIENT_ENCRYPT : Attribute cannot be written.
ATT_ERR_INSUFFICIENT_AUTHEN : Attribute requires authentication.
ATT_ERR_INSUFFICIENT_KEY_SIZE : Key Size used for encrypting is insufficient.
ATT_ERR_INSUFFICIENT_ENCRYPT : Attribute requires encryption.

§ GATT_WriteCharDesc()

bStatus_t GATT_WriteCharDesc ( uint16  connHandle,
attWriteReq_t pReq,
uint8  taskId 
)

Write Characteristic Descriptor.

This sub-procedure is used to write a characteristic descriptor value to a server when the client knows the characteristic descriptor handle.

ATT_WriteReq is used for this sub-procedure. The Attribute Handle parameter shall be set to the characteristic descriptor handle. The Attribute Value parameter shall be set to the new characteristic descriptor value.

Corresponding Events:
If the return status from this function is SUCCESS, the calling application task will receive a GATT_MSG_EVENT message with method:
Note
This sub-procedure is complete when either ATT_WRITE_RSP (with SUCCESS or bleTimeout status) or ATT_ERROR_RSP (with SUCCESS status) is received by the calling task.
Parameters
connHandle- connection to use
pReq- pointer to request to be sent
taskId- task to be notified of response
Returns
SUCCESS : Request was queued successfully.
INVALIDPARAMETER
MSG_BUFFER_NOT_AVAIL
bleNotConnected
blePending : A response is pending with this server.
bleMemAllocError
bleTimeout : Previous transaction timed out.

§ GATT_WriteCharValue()

bStatus_t GATT_WriteCharValue ( uint16  connHandle,
attWriteReq_t pReq,
uint8  taskId 
)

Write Characteristic Value.

This sub-procedure is used to write a characteristic value to a server when the client knows the characteristic value handle. This sub-procedure only writes the first (ATT_MTU-3) octets of a characteristic value. This sub-procedure can not be used to write a long attribute; instead the Write Long Characteristic Values sub-procedure should be used.

ATT_WriteReq is used in this sub-procedure. The Attribute Handle parameter shall be set to the Characteristic Value Handle. The Attribute Value parameter shall be set to the new characteristic.

Corresponding Events:
If the return status from this function is SUCCESS, the calling application task will receive a GATT_MSG_EVENT message with method:
Note
This sub-procedure is complete when either ATT_WRITE_RSP (with SUCCESS or bleTimeout status) or ATT_ERROR_RSP (with SUCCESS status) is received by the calling task.
Parameters
connHandle- connection to use
pReq- pointer to request to be sent
taskId- task to be notified of response
Returns
SUCCESS : Request was queued successfully.
INVALIDPARAMETER
MSG_BUFFER_NOT_AVAIL
bleNotConnected
blePending : A response is pending with this server.
bleMemAllocError
bleTimeout : Previous transaction timed out.

§ GATT_WriteLongCharDesc()

bStatus_t GATT_WriteLongCharDesc ( uint16  connHandle,
attPrepareWriteReq_t pReq,
uint8  taskId 
)

Write Long Characteristic Descriptor.

This sub-procedure is used to write a Characteristic Value to a server when the client knows the Characteristic Value Handle but the length of the Characteristic Value is longer than can be sent in a single Write Request Attribute Protocol message.

ATT_PrepareWriteReq and ATT_ExecuteWriteReq are used to perform this sub-procedure.

Corresponding Events:
If the return status from this function is SUCCESS, the calling application task will receive a GATT_MSG_EVENT message with method:
Note
This sub-procedure is complete when either ATT_PREPARE_WRITE_RSP (with bleTimeout status), ATT_EXECUTE_WRITE_RSP (with SUCCESS or bleTimeout status), or ATT_ERROR_RSP (with SUCCESS status) is received by the calling task.
Warning
The 'pReq->pValue' pointer will be freed when the sub-procedure is complete.
Parameters
connHandle- connection to use
pReq- pointer to request to be sent
taskId- task to be notified of response
Returns
SUCCESS : Request was queued successfully.
INVALIDPARAMETER
MSG_BUFFER_NOT_AVAIL
bleNotConnected
blePending : A response is pending with this server.
bleMemAllocError
bleTimeout : Previous transaction timed out.

§ GATT_WriteLongCharValue()

bStatus_t GATT_WriteLongCharValue ( uint16  connHandle,
attPrepareWriteReq_t pReq,
uint8  taskId 
)

Write Long Characteristic Value.

This sub-procedure is used to write a Characteristic Value to a server when the client knows the Characteristic Value Handle but the length of the Characteristic Value is longer than can be sent in a single Write Request Attribute Protocol message.

ATT_PrepareWriteReq and ATT_ExecuteWriteReq are used to perform this sub-procedure.

Corresponding Events:
If the return status from this function is SUCCESS, the calling application task will receive a GATT_MSG_EVENT message with method:
Note
This sub-procedure is complete when either ATT_PREPARE_WRITE_RSP (with bleTimeout status), ATT_EXECUTE_WRITE_RSP (with SUCCESS or bleTimeout status), or ATT_ERROR_RSP (with SUCCESS status) is received by the calling task.
Warning
The 'pReq->pValue' pointer will be freed when the sub-procedure is complete.
Parameters
connHandle- connection to use
pReq- pointer to request to be sent
taskId- task to be notified of response
Returns
SUCCESS : Request was queued successfully.
INVALIDPARAMETER
MSG_BUFFER_NOT_AVAIL
bleNotConnected
blePending : A response is pending with this server.
bleMemAllocError
bleTimeout : Previous transaction timed out.

§ GATT_WriteNoRsp()

bStatus_t GATT_WriteNoRsp ( uint16  connHandle,
attWriteReq_t pReq 
)

Write No Response.

This sub-procedure is used to write a Characteristic Value to a server when the client knows the Characteristic Value Handle and the client does not need an acknowledgement that the write was successfully performed. This sub-procedure only writes the first (ATT_MTU - 3) octets of a Characteristic Value. This sub-procedure can not be used to write a long characteristic; instead the Write Long Characteristic Values sub-procedure should be used.

ATT_WriteReq is used for this sub-procedure. The Attribute Handle parameter shall be set to the Characteristic Value Handle. The Attribute Value parameter shall be set to the new Characteristic Value.

Note
No response will be sent to the calling task for this sub-procedure. If the Characteristic Value write request is the wrong size, or has an invalid value as defined by the profile, then the write will not succeed and no error will be generated by the server.
Parameters
connHandle- connection to use
pReq- pointer to command to be sent
Returns
SUCCESS : Request was queued successfully.
INVALIDPARAMETER
MSG_BUFFER_NOT_AVAIL
bleNotConnected
bleMemAllocError
bleTimeout : Previous transaction timed out.
Copyright 2017, Texas Instruments Incorporated