handover.h

Go to the documentation of this file.

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

 @file  handover.h

 @brief This file contains handover APIs.

 Group: WCS, BTS
 $Target Device: DEVICES $

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

#ifndef HANDOVER_H
#define HANDOVER_H

/*******************************************************************************
 * INCLUDES
 */
#include "ti/ble/controller/ll/ll.h"
#include "ti/ble/stack_util/comdef.h"

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

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

/*******************************************************************************
 * TYPEDEFS
 */
// Invalid connection handle, used for no connection handle
#define HANDOVER_CONNHANDLE_INVALID             LL_CONNHANDLE_INVALID

// Handover Data Size defines
#define HANDOVER_HOST_DATA_SIZE                 0
#define HANDOVER_INVALID_DATA_SIZE              0xFFFFFFFF

#define HANDOVER_DEFAULT_MAX_FAILED_CONN_EVENTS 6

#define HANDOVER_CONN_ESTABLISH_WITH_HANDOVER   LL_STATUS_ESTABLISH_WITH_HANDOVER

#define HANDOVER_TX_BURST_RATIO_DEFAULT_VAL     30
// Defines for serving node modes
#define HANDOVER_SN_MODE_DISCONNECT_IMMED       0
#define HANDOVER_SN_MODE_WAIT_CN_STATUS         1

/************************************
 *          Serving Node            *
 ************************************/

/*
* @brief Host Handover Start SN Callback
*
* @note
* This callback will trigger with a success status once it will finish filling
* the handover data. Otherwise, this callback will be called with an error code
*
* @param status - the stack status (SUCCESS, bleInvalidRange, bleNotConnected)
*
* @return None
*/
typedef void(*pfnHandoverStartSNCB_t)(uint16_t connHandle, uint32_t status);

typedef struct
{
  pfnHandoverStartSNCB_t pfnHandoverStartSNCB;
} handoverSNCBs_t;

typedef struct
{
  uint16_t connHandle;          
  uint32_t handoverDataSize;    
  uint8_t *pHandoverData;       
  uint32_t rfu;                 
  uint8_t  handoverSnMode;      
  uint16_t minGattHandle;       
  uint16_t maxGattHandle;       
} handoverSNParams_t;

/************************************
 *        Candidate Node            *
 ************************************/

/*
* @brief Host Handover Start CN Callback
*
* @note
* This callback will trigger with a success sta tus if the candidate was able
* to follow the new connection. Otherwise, a failure status will be returned
*
* @param status - the stack status (SUCCESS, FAILURE)
*
* @return None
*/
typedef void(*pfnHandoverStartCNCB_t)(uint16_t connHandle, uint32_t status);

typedef struct
{
  pfnHandoverStartCNCB_t pfnHandoverStartCNCB;
} handoverCNCBs_t;

typedef struct
{
  uint8_t *pHandoverData;       
  uint8_t  appTaskId;           
  uint32_t timeDeltaInUs;       
  uint32_t timeDeltaMaxErrInUs; 
  uint16_t rfu;                 
  uint32_t maxFailedConnEvents; 
  uint8_t  txBurstRatio;        
} handoverCNParams_t;

/*******************************************************************************
 * LOCAL VARIABLES
 */

/*******************************************************************************
 * GLOBAL VARIABLES
 */

/*******************************************************************************
 * FUNCTIONS
 */

/************************************
 *        Serving Node APIs         *
 ************************************/

uint8_t Handover_InitSNParams(handoverSNParams_t *pParams);

uint8_t Handover_RegisterSNCBs(const handoverSNCBs_t *pCBs);


uint32_t Handover_GetSNDataSize(handoverSNParams_t *pParams);

uint8_t Handover_StartSN(handoverSNParams_t *pParams);

uint8_t Handover_CloseSN( handoverSNParams_t *pParams, uint16_t handoverStatus );

/************************************
 *       Candidate Node APIs        *
 ************************************/

uint8_t Handover_RegisterCNCBs(const handoverCNCBs_t *pCBs);

uint8_t Handover_InitCNParams(handoverCNParams_t *pParams);

uint8_t Handover_StartCN( handoverCNParams_t *pParams );

/*******************************************************************************
 * @fn          Handover_ApplyCnData
 *
 * @brief       This function is used to trigger all the handover modules
 *              upon receiving connection establish event
 *
 * @param       connHandle - Connection handle
 *
 * @return      None
 */
void Handover_ApplyCnData(uint16_t connHandle);

#endif /* HANDOVER_H */