gatt.h

Go to the documentation of this file.

/*
 * Copyright (c) 2015-2016, Texas Instruments Incorporated
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * *  Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 * *  Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * *  Neither the name of Texas Instruments Incorporated nor the names of
 *    its contributors may be used to endorse or promote products derived
 *    from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
/*!*****************************************************************************
 *  @addtogroup ATT_GATT
 *  @{
 *  @file       gatt.h
 *  @brief      GATT layer interface
 */

#ifndef GATT_H
#define GATT_H

#ifdef __cplusplus
extern "C"
{
#endif

/*********************************************************************
 * INCLUDES
 */
#include "bcomdef.h"
#include "osal.h"

#include "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

/*********************************************************************
 * 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;
 // 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 );

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, uint8 permissions, uint16 service );

extern bStatus_t GATT_VerifyWritePermissions( uint16 connHandle, uint8 permissions,
                                              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 );

/*-------------------------------------------------------------------
 * 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 void 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 void GATT_SetNextHandle( uint16 handle );

extern uint16 GATT_GetNextHandle( void );

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

extern void GATT_Init( uint8 taskId );

extern uint16 GATT_ProcessEvent( uint8 taskId, uint16 events );


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

#ifdef __cplusplus
}
#endif

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