connection_monitor.h

Go to the documentation of this file.

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

 @file  connection_monitor.h

 @brief This file contains interfaces for the Host Connection Monitor.

 Group: WCS, BTS
 $Target Device: DEVICES $

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

#ifndef CONNECTION_MONITOR_H
#define CONNECTION_MONITOR_H

/*******************************************************************************
 * INCLUDES
 */
#include "ti/ble/stack_util/connection_monitor_types.h"
#include "ti/ble/stack_util/icall/app/icall.h"

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

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

/*******************************************************************************
 * TYPEDEFS
 */

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

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

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

/************************************
 * Connecetion Monitor Serving APIs *
 ************************************/
/* How to use the Connection Monitor Serving APIs:
 * 1. Register the callback functions using CMS_RegisterCBs
 * 2. Initialize the connection data parameters using CMS_InitConnDataParams
 * 3. Get the connection data size using CMS_GetConnDataSize
 * 4. Get the connection data using CMS_GetConnData
 * 5. Send the event to the upper layer which will forward it to the CM node
 */
/*******************************************************************************
 * @fn      CMS_RegisterCBs
 *
 * @brief   Register the application callback function at the Host for the CMS
 *
 * @param   pCBs - pointer to the callback functions
 *
 * @return  CM_SUCCESS, CM_INVALID_PARAMS, CM_UNSUPPORTED @ref cmErrorCodes_e
 *
 * @note    When the callback is called it is called from the context of the BLE stack
 *          The application must release the context as fast as it can
 */
cmErrorCodes_e CMS_RegisterCBs(const cmsCBs_t *pCBs);

/*******************************************************************************
 * @fn      CMS_GetConnDataSize
 *
 * @brief   Request the controller data size and returns the sum of
 *          the controller and host data size which should be allocated by the application
 *
 * @return  The connection data size
 */
uint8_t CMS_GetConnDataSize(void);

/*******************************************************************************
 * @fn      CMS_InitConnDataParams
 *
 * @brief   Initialize the given parameter structure with default values
 *
 * @param   pParams - Pointer to the parameters structure
 *
 * @return  CM_SUCCESS, CM_UNSUPPORTED @ref cmErrorCodes_e
 *
 */
cmErrorCodes_e CMS_InitConnDataParams(cmsConnDataParams_t *pParams);

/*******************************************************************************
 * @fn      CMS_GetConnData
 *
 * @brief   Get the connection data which will be monitored. 
 *
 * @param   connHandle - the connection handle
 * @param   pData - pointer to the data buffer
 *
 * @return  CM_SUCCESS, CM_INCORRECT_MODE, CM_NOT_CONNECTED,
 *          CM_NO_RESOURCE, CM_UNSUPPORTED @ref cmErrorCodes_e
 */
cmErrorCodes_e CMS_GetConnData(uint16_t connHandle, cmsConnDataParams_t *pParams);


/************************************
 *     Connection Monitor APIs      *
 ************************************/
/* How to use the Connection Monitor APIs:
 * 1. Register the callback functions using CM_RegisterCBs
 * 2. Initialize the start monitor parameters using CM_InitStartMonitorParams
 * 3. Start monitoring a connection using CM_StartMonitor with the data received
 *    from the CM Serving node
 * 4. Stop monitoring a connection using CM_StopMonitor
 * 5. Update the monitored connection using data from CM Serving node using CM_UpdateConn
 */

/*******************************************************************************
 * @fn      CM_RegisterCBs
 *
 * @brief   Register the application callback function at the Host
 *
 * @param   pCBs - pointer to the callback functions
 *
 * @return  CM_SUCCESS, CM_INVALID_PARAMS, CM_UNSUPPORTED @ref cmErrorCodes_e
 *
 * @note    When the callback is called it is called from the context of the BLE stack
 *          The application must release the context as fast as it can
 */
cmErrorCodes_e CM_RegisterCBs(const cmCBs_t *pCBs);

/*******************************************************************************
 * @fn      CM_InitStartMonitorParams
 *
 * @brief   Initialize the given parameter structure with default values
 *
 * @param   pParams - Pointer to the parameters structure
 *
 * @return  CM_SUCCESS, CM_UNSUPPORTED @ref cmErrorCodes_e
 */
cmErrorCodes_e CM_InitStartMonitorParams(cmStartMonitorParams_t *pParams);

/*******************************************************************************
 * @fn      CM_StartMonitor
 *
 * @brief   Starts the connection monitoring process with the connection data given.
 *
 * @param   pParams - Pointer to the monitor parameters
 *
 * @return  CM_SUCCESS, CM_NOT_CONNECTED, CM_ALREADY_REQUESTED,
 *          CM_INVALID_PARAMS, CM_NO_RESOURCE,
 *          CM_CONNECTION_LIMIT_EXCEEDED, CM_UNSUPPORTED @ref cmErrorCodes_e
 * 
 * @output  This function will send a @ref CM_TRACKING_START_EVT event to the registered
 *          callback @ref pfnCmConnStatusEvtCB in case of a success monitoring start, otherwise it will send a
 *          @ref CM_TRACKING_STOP_EVT event after the end of the trying to sync up to
 *          maxSyncAttempts in the @ref cmStartMonitorParams_t.
 *
 * @note    If the return code is CM_SUCCESS if there any running advertise, it will be disabled,
 *          and an event of @ref GAP_EVT_ADV_END_AFTER_DISABLE
 *
 * @note    After a success monitoring start, the application should expect
 *          @ref cmReportEvt_t event with the RSSI by calling @ref pfnCmReportEvtCB.
 */
cmErrorCodes_e CM_StartMonitor(cmStartMonitorParams_t *pParams);

/*******************************************************************************
 * @fn      CM_StopMonitor
 *
 * @brief   Stops the connection monitoring process.
 *
 * @param   connHandle - the connection handle
 *
 * @return  CM_SUCCESS, CM_NOT_CONNECTED, CM_UNSUPPORTED @ref cmErrorCodes_e
 * 
 * @output This function will send a @ref CM_TRACKING_STOP_EVT event to the registered
 *         callback @ref pfnCmConnStatusEvtCB.
 */
cmErrorCodes_e CM_StopMonitor(uint16_t connHandle);

/*******************************************************************************
 * @fn      CM_UpdateConn
 *
 * @brief   This function used to update monitored connection given by the CMS
 *          with the given connection data
 *
 * @param   pConnUpdateEvt - pointer to the update event
 *
 * @return  CM_SUCCESS, CM_NOT_CONNECTED, CM_ALREADY_REQUESTED,
 *          CM_INVALID_PARAMS,CM_UNSUPPORTED,CM_FAILURE @ref cmErrorCodes_e
 * 
 * @output  This function will adjust the monitored connection with the update event.
 *          If the update event can't be applied with return code @ref CM_FAILURE,
 *          it will terminate the monitored connection with @ref CM_TRACKING_STOP_EVT and
 *          reason @ref CM_BAD_UPDATE_EVENT
 */
cmErrorCodes_e CM_UpdateConn(cmConnUpdateEvt_t *pConnUpdateEvt);

#endif /* CONNECTION_MONITOR_H */