gatt.h

Go to the documentation of this file.

/******************************************************************************

 Group: WCS, BTS
 $Target Device: DEVICES $

 ******************************************************************************
 $License: TI_TEXT 2009 $
 ******************************************************************************
 $Release Name: PACKAGE NAME $
 $Release Date: PACKAGE RELEASE DATE $
 *****************************************************************************/

#ifndef GATT_H
#define GATT_H

#ifdef __cplusplus
extern "C"
{
#endif

/*********************************************************************
 * INCLUDES
 */
#include "ti/ble/stack_util/bcomdef.h"
#include "ti/ble/stack_util/osal/osal.h"
#include "ti/ble/host/att/att.h"

/*********************************************************************
 * CONSTANTS
 */

#define GATT_PERMIT_READ                0x01   
#define GATT_PERMIT_WRITE               0x02   
#define GATT_PERMIT_AUTHEN_READ         0x04   
#define GATT_PERMIT_AUTHEN_WRITE        0x08   
#define GATT_PERMIT_AUTHOR_READ         0x10   
#define GATT_PERMIT_AUTHOR_WRITE        0x20   
#define GATT_PERMIT_ENCRYPT_READ        0x40   
#define GATT_PERMIT_ENCRYPT_WRITE       0x80   

#if !defined( GATT_MAX_NUM_PREPARE_WRITES )
  #define GATT_MAX_NUM_PREPARE_WRITES   5 
#endif

#define GATT_MIN_ENCRYPT_KEY_SIZE       7  
#define GATT_MAX_ENCRYPT_KEY_SIZE       16 

#define GATT_MAX_ATTR_SIZE              512 

#define GATT_BASE_METHOD                0x40  

#define GATT_INVALID_HANDLE             0x0000 
#define GATT_MIN_HANDLE                 0x0001 
#define GATT_MAX_HANDLE                 0xFFFF 

#define GATT_ATTR_HANDLE_SIZE           0x02 

#define GATT_MAX_MTU                    0xFFFF 
 // end of ATT_GATT_Constants

#define GATT_SERVER_NOT_FOUND            0xFF

/*********************************************************************
 * VARIABLES
 */

/*********************************************************************
 * MACROS
 */


// Attribute Access Permissions
#define gattPermitRead( a )              ( (a) & GATT_PERMIT_READ )
#define gattPermitWrite( a )             ( (a) & GATT_PERMIT_WRITE )
#define gattPermitEncryptRead( a )       ( (a) & GATT_PERMIT_ENCRYPT_READ )
#define gattPermitEncryptWrite( a )      ( (a) & GATT_PERMIT_ENCRYPT_WRITE )
#define gattPermitAuthorRead( a )        ( (a) & GATT_PERMIT_AUTHOR_READ )
#define gattPermitAuthorWrite( a )       ( (a) & GATT_PERMIT_AUTHOR_WRITE )
#define gattPermitAuthenRead( a )        ( (a) & GATT_PERMIT_AUTHEN_READ )
#define gattPermitAuthenWrite( a )       ( (a) & GATT_PERMIT_AUTHEN_WRITE )

// Check for different UUID types
#define gattPrimaryServiceType( t )      ( MAP_ATT_CompareUUID( primaryServiceUUID, ATT_BT_UUID_SIZE, \
                                                                (t).uuid, (t).len ) )
#define gattSecondaryServiceType( t )    ( MAP_ATT_CompareUUID( secondaryServiceUUID, ATT_BT_UUID_SIZE, \
                                                                (t).uuid, (t).len ) )
#define gattCharacterType( t )           ( MAP_ATT_CompareUUID( characterUUID, ATT_BT_UUID_SIZE, \
                                                                (t).uuid, (t).len ) )
#define gattIncludeType( t )             ( MAP_ATT_CompareUUID( includeUUID, ATT_BT_UUID_SIZE, \
                                                                (t).uuid, (t).len ) )
#define gattServiceType( t )             ( gattPrimaryServiceType( (t) ) || \
                                           gattSecondaryServiceType( (t) ) )


/*********************************************************************
 * TYPEDEFS
 */
 // end of ATT_GATT

typedef struct
{
  uint16 startHandle;  
  uint16 endHandle;    
  attAttrType_t value; 
} gattFindByTypeValueReq_t;

typedef struct
{
  uint8 discCharsByUUID;  
  attReadByTypeReq_t req; 
} gattReadByTypeReq_t;

typedef struct
{
  uint8 reliable;           
  attPrepareWriteReq_t req; 
  uint16 lastOffset;        
} gattWriteLongReq_t;

typedef struct
{
  uint8 reliable;              
  attPrepareWriteReq_t *pReqs; 
  uint8 numReqs;               
  uint8 index;                 
  uint8 flags;                 
} gattReliableWritesReq_t;

typedef union
{
  // Request messages
  attExchangeMTUReq_t exchangeMTUReq;              
  attFindInfoReq_t findInfoReq;                    
  attFindByTypeValueReq_t findByTypeValueReq;      
  attReadByTypeReq_t readByTypeReq;                
  attReadReq_t readReq;                            
  attReadBlobReq_t readBlobReq;                    
  attReadMultiReq_t readMultiReq;                  
  attReadByGrpTypeReq_t readByGrpTypeReq;          
  attWriteReq_t writeReq;                          
  attPrepareWriteReq_t prepareWriteReq;            
  attExecuteWriteReq_t executeWriteReq;            
  gattFindByTypeValueReq_t gattFindByTypeValueReq; 
  gattReadByTypeReq_t gattReadByTypeReq;           
  gattWriteLongReq_t gattWriteLongReq;             
  gattReliableWritesReq_t gattReliableWritesReq;   

  // Response messages
  attErrorRsp_t errorRsp;                          
  attExchangeMTURsp_t exchangeMTURsp;              
  attFindInfoRsp_t findInfoRsp;                    
  attFindByTypeValueRsp_t findByTypeValueRsp;      
  attReadByTypeRsp_t readByTypeRsp;                
  attReadRsp_t readRsp;                            
  attReadBlobRsp_t readBlobRsp;                    
  attReadMultiRsp_t readMultiRsp;                  
  attReadByGrpTypeRsp_t readByGrpTypeRsp;          
  attPrepareWriteRsp_t prepareWriteRsp;            

  // Indication and Notification messages
  attHandleValueNoti_t handleValueNoti;            
  attHandleValueInd_t handleValueInd;              

  // Locally-generated event messages
  attFlowCtrlViolatedEvt_t flowCtrlEvt;            
  attMtuUpdatedEvt_t mtuEvt;                       
} gattMsg_t;

typedef struct
{
  osal_event_hdr_t hdr; 
  uint16 connHandle;    
  uint8 method;         
  gattMsg_t msg;        
} gattMsgEvent_t;
 // end of ATT_GATT_events

typedef struct
{
  uint8 len;         
  const uint8 *uuid; 
} gattAttrType_t;

typedef struct attAttribute_t
{
  gattAttrType_t type; 
  uint8 permissions;    
  uint16 handle;       
  uint8* const pValue; 
} gattAttribute_t;

typedef struct
{
  uint16 numAttrs; 
  uint8 encKeySize;
  gattAttribute_t *attrs; 
} gattService_t;

/*
* @brief GATT security Callbacks
*
* @note
* This callback it used to return the security level required based on a
* the security flags saved in the previous bond
* IMPORTANT: This is called from the stack. Do not call to a stack APIs from
* this function
*
* @param connHandle - Connection Handle
* @param pMitmReq - Pointer that will store TRUE if authentication (MITM protection)
*                   is required
* @param pKeySize - Pointer that will store the key size required
*
* @return SUCCESS - A bond was found and data restored correctly
*/
typedef bStatus_t (*pfnGATTBondInfoCB_t)(uint16_t connHandle, uint8_t *pMitmReq, uint8_t *pKeySize);

/*
* @brief GATT security Callbacks
*
* @note
* This callback will trigger an encryption process with a bonded device
* IMPORTANT: This is called from the stack. Do not call to a stack APIs from
* this function
*
* @param connHandle - Connection Handle
*
* @return SUCCESS - A bond was found and the encryption process started
*/
typedef bStatus_t (*pfnGATTStartEncCB_t)(uint16_t connHandle);

typedef struct
{
  pfnGATTBondInfoCB_t pfnBondInfoCB;      
  pfnGATTStartEncCB_t pfnStartEncCB;      
} gattClientSecCBs_t;

typedef struct
{
    uint16_t handle;  
    uint8_t  value;   
} cccValues_t;
 // end of ATT_GATT_Structs

/*********************************************************************
 * VARIABLES
 */

extern uint8 gattNumConns;

/*********************************************************************
 * API FUNCTIONS
 */

/*-------------------------------------------------------------------
 * GATT Client Public APIs
 */

extern bStatus_t GATT_InitClient( void );

extern void GATT_RegisterForInd( uint8 taskId );

/******************************************************************************
 * @fn      GATT_RegisterClientSecurityCBs
 *
 * @brief   Saves the Security related callbacks
 *
 * @param   pClientCbs - Pointer to two functions needed for checking the security
 *                       flags for a bonded device and to a function that starts
 *                       encryption
 *
 * @return  void
 */
extern void GATT_RegisterClientSecurityCBs( gattClientSecCBs_t *pClientCallbacks );

extern bStatus_t GATT_PrepareWriteReq( uint16 connHandle, attPrepareWriteReq_t *pReq, uint8 taskId );

extern bStatus_t GATT_ExecuteWriteReq( uint16 connHandle, attExecuteWriteReq_t *pReq, uint8 taskId );

/*-------------------------------------------------------------------
 * GATT Server Public APIs
 */

extern bStatus_t GATT_InitServer( void );

extern bStatus_t GATT_RegisterService( gattService_t *pService );

extern bStatus_t GATT_DeregisterService( uint16 handle, gattService_t *pService );

extern void GATT_RegisterForReq( uint8 taskId );

extern bStatus_t GATT_VerifyReadPermissions( uint16 connHandle, gattAttribute_t *pAttr,
                                             uint16 service);

extern bStatus_t GATT_VerifyWritePermissions( uint16 connHandle, gattAttribute_t *pAttr,
                                              uint16 service, attWriteReq_t *pReq );

extern uint8 GATT_ServiceChangedInd( uint16 connHandle, uint8 taskId );

extern gattAttribute_t *GATT_FindHandleUUID( uint16 startHandle, uint16 endHandle, const uint8 *pUUID,
                                             uint16 len, uint16 *pHandle );
extern gattAttribute_t *GATT_FindHandle( uint16 handle, uint16 *pHandle );

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

extern uint16 GATT_ServiceNumAttrs( uint16 handle );

extern uint8 GATT_ServiceEncKeySize( uint16 handle );

extern bStatus_t GATT_SendRsp( uint16 connHandle, uint8 method, gattMsg_t *pRsp );

/*-------------------------------------------------------------------
 * GATT Server Sub-Procedure APIs
 */

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

extern bStatus_t GATT_Notification( uint16 connHandle, attHandleValueNoti_t *pNoti,
                                    uint8 authenticated );

/*-------------------------------------------------------------------
 * GATT Client Sub-Procedure APIs
 */

extern bStatus_t GATT_ExchangeMTU( uint16 connHandle, attExchangeMTUReq_t *pReq, uint8 taskId );

extern bStatus_t GATT_DiscAllPrimaryServices( uint16 connHandle, uint8 taskId );

extern bStatus_t GATT_DiscPrimaryServiceByUUID( uint16 connHandle, uint8 *pUUID,
                                                uint8 len, uint8 taskId );
extern bStatus_t GATT_FindIncludedServices( uint16 connHandle, uint16 startHandle,
                                            uint16 endHandle, uint8 taskId );
extern bStatus_t GATT_DiscAllChars( uint16 connHandle, uint16 startHandle,
                                    uint16 endHandle, uint8 taskId );
extern bStatus_t GATT_DiscCharsByUUID( uint16 connHandle, attReadByTypeReq_t *pReq, uint8 taskId );

extern bStatus_t GATT_DiscAllCharDescs( uint16 connHandle, uint16 startHandle,
                                        uint16 endHandle, uint8 taskId );
extern bStatus_t GATT_ReadCharValue( uint16 connHandle, attReadReq_t *pReq, uint8 taskId );

extern bStatus_t GATT_ReadUsingCharUUID( uint16 connHandle, attReadByTypeReq_t *pReq, uint8 taskId );
extern bStatus_t GATT_ReadLongCharValue( uint16 connHandle, attReadBlobReq_t *pReq, uint8 taskId );

extern bStatus_t GATT_ReadMultiCharValues( uint16 connHandle, attReadMultiReq_t *pReq, uint8 taskId );

extern bStatus_t GATT_WriteNoRsp( uint16 connHandle, attWriteReq_t *pReq );

extern bStatus_t GATT_SignedWriteNoRsp( uint16 connHandle, attWriteReq_t *pReq );

extern bStatus_t GATT_WriteCharValue( uint16 connHandle, attWriteReq_t *pReq, uint8 taskId );

extern bStatus_t GATT_WriteLongCharValue( uint16 connHandle, attPrepareWriteReq_t *pReq, uint8 taskId );

extern bStatus_t GATT_ReliableWrites( uint16 connHandle, attPrepareWriteReq_t *pReqs,
                                      uint8 numReqs, uint8 flags, uint8 taskId );
extern bStatus_t GATT_ReadCharDesc( uint16 connHandle, attReadReq_t *pReq, uint8 taskId );

extern bStatus_t GATT_ReadLongCharDesc( uint16 connHandle, attReadBlobReq_t *pReq, uint8 taskId );

extern bStatus_t GATT_WriteCharDesc( uint16 connHandle, attWriteReq_t *pReq, uint8 taskId );

extern bStatus_t GATT_WriteLongCharDesc( uint16 connHandle, attPrepareWriteReq_t *pReq, uint8 taskId );

/******************************************************************************
 * @fn      GATT_SetNextHandle
 *
 * @brief   Set the next available attribute handle.
 *
 * @param   handle - next attribute handle.
 *
 * @return  void
 */
extern void GATT_SetNextHandle( uint16 handle );

/******************************************************************************
 * @fn      GATT_GetNumIndNotiHandles
 *
 * @brief   Return the number of attributes that has GATT_CLIENT_CHAR_CFG_UUID
 *
 * @param   None
 *
 * @return  number of attributes
 */
uint16_t GATT_GetNumIndNotiHandles(uint16_t minHandle, uint16_t maxHandle);

/*******************************************************************************
 * @fn      GATT_SetIndNotiRegData
 *
 * @brief   This function fill a given buffer with the handles and values of characteristic
 *          with GATT_CLIENT_CHAR_CFG_UUID
 *
 * @param   connHandle - Connection Handle
 * @param   minHandle  - Minimum ATT handle
 * @param   maxHandle  - Maximum ATT handle
 * @param   numAtts    - Number of attributes
 * @param   pBuf       - Pointer to the data sturcture
 *
 * @return  @ref SUCCESS
 *          @ref FAILURE
 */
uint8_t GATT_SetIndNotiRegData(uint16_t connHandle,
                                uint16_t minHandle,
                                uint16_t maxHandle,
                                uint16_t numAtts,
                                cccValues_t *pCccData);

/*******************************************************************************
 * @fn      GATT_GetServerPendingReq
 *
 * @brief   This function returns the server pending request value
 *
 * @param   connHandle - Connection Handle
 *
 * @return  If server founding it's pending request value. Else, GATT_SERVER_NOT_FOUND
 */
uint8_t GATT_GetServerPendingReq(uint16_t connHandle);

/*-------------------------------------------------------------------
 * GATT Client and Server Common APIs
 */

extern void GATT_RegisterForMsgs( uint8 taskID );

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

extern bStatus_t GATT_UpdateMTU( uint16 connHandle, uint16 mtuSize );

/*-------------------------------------------------------------------
 * GATT Buffer Management APIs
 */

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

extern void GATT_bm_free( gattMsg_t *pMsg, uint8 opcode );


/*-------------------------------------------------------------------
 * GATT Flow Control APIs
 */

extern void GATT_SetHostToAppFlowCtrl( uint16 heapSize, uint8 flowCtrlMode );

extern void GATT_AppCompletedMsg( gattMsgEvent_t *pMsg );

/*-------------------------------------------------------------------
 * Internal API - This function is only called from GATT Qualification modules.
 */
extern uint16 GATT_GetNextHandle( void );

/*-------------------------------------------------------------------
 * Internal API - This function is called by OSAL tasks.
 */

extern bStatus_t GATT_RequestNextTransaction( uint16 connHandle, uint8 taskId );

/*-------------------------------------------------------------------
 * TASK API - These functions must only be called by OSAL.
 */

extern void GATT_Init( uint8 taskId );

extern uint32 GATT_ProcessEvent( uint8 taskId, uint32 events );


/*********************************************************************
*********************************************************************/

#ifdef __cplusplus
}
#endif

#endif /* GATT_H */
 // end of ATT_GATT