timer.h

Go to the documentation of this file.

/*******************************************************************************
 * Copyright © 2014 The DTVKit Open Software Foundation Ltd (www.dtvkit.org)
 * Copyright © 2014 Ocean Blue Software Ltd
 *
 * This file is part of a DTVKit Software Component
 * You are permitted to copy, modify or distribute this file subject to the terms
 * of the DTVKit 1.0 Licence which can be found in licence.txt or at www.dtvkit.org
 * 
 * THIS CODE AND INFORMATION ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND,
 * EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES
 * OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR PURPOSE.
 * 
 * If you or your organisation is not a member of DTVKit then you have access
 * to this source code outside of the terms of the licence agreement
 * and you are expected to delete this and any associated files immediately.
 * Further information on DTVKit, membership and terms can be found at www.dtvkit.org
 *******************************************************************************/
/* pre-processor mechanism so multiple inclusions don't cause compilation error*/

#ifndef _TIMER_H

#define _TIMER_H

#include "hbbtv_types.h"


/*---Constant and macro definitions for public use-----------------------------*/

/*---Enumerations for public use-----------------------------------------------*/

/*---Global type defs for public use-------------------------------------------*/

typedef void *TMR_HANDLE;

/*******************************************************************************
 * NAME: F_TMR_CALLBACK
 *       Callback called either when a timer expires or an unexpired timer is
 *       destroyed.
 *
 * Returns : void
 *
 * Parameter     Flow    Description
 * ------------------------------------------------------------------------------
 * triggered     IN      True when the callback is invoked because the timer has
 *                       expired, otherwise false.
 * callerRef     IN      Caller reference which was passed when the timer was
 *                       created.
 * timerHandle   IN      Handle of the timer that caused the callback to be
 *                       invoked.
 *
 *******************************************************************************/
typedef void (*F_TMR_CALLBACK)(BOOLEAN triggered,
   void *callerRef, TMR_HANDLE timerHandle);


/*---Global Function prototypes for public use---------------------------------*/

/*******************************************************************************
 *@begin
 * NAME: HBBTV_TmrCreate
 *       Set a timer for a certain number of millseconds. When the timer expires
 *       a specified callback will be called, passing the caller reference value.
 *
 * Returns : HBBTV_OK                           - Timer has been sucessfully set
 *
 * Parameter     Flow    Description
 * ------------------------------------------------------------------------------
 * millisecs     IN      Number of milliseconds before callback will be invoked.
 * callback      IN      Pointer to callback function to invoke when timer is
 *                       triggered.
 * callerRef     IN      Caller reference which is passed to callback function
 *                       when timer is triggered
 * p_timer_handle  OUT     Pointer to handle to this timer that must be used to
 *                       destroy the timer.
 *
 * Additional information:
 *
 *@end
 *******************************************************************************/
E_HBBTV_ERR HBBTV_TmrCreate(U32BIT millisecs, F_TMR_CALLBACK callback,
   void *callerRef, TMR_HANDLE *p_timer_handle);

/*******************************************************************************
 *@begin
 * NAME: HBBTV_TmrDestroy
 *       Destroy the specified timer. A callback will not be invoked for this
 *       timer after this function returns.
 *
 * Returns : HBBTV_OK              : Timer has been sucessfully killed
 *           HBBTV_ERR_BAD_PARAMETER  : Invalid timer handle was passed
 *           HBBTV_ERR_COMP_NOT_OPEN  : Timers not initialised.
 *
 * Parameter     Flow    Description
 * ------------------------------------------------------------------------------
 * timerHandle   IN      Handle of the timer to be destroyed.
 *
 * Additional information:
 *
 *@end
 *******************************************************************************/
E_HBBTV_ERR HBBTV_TmrDestroy(TMR_HANDLE timerHandle);

/*******************************************************************************
 *@begin
 * NAME: HBBTV_TmrInit
 *       Initialise the timer component. This function must be called before
 *       any other timer functions are invoked.
 *
 * Returns : HBBTV_OK                    -  Timer component sucessfully initialised
 *           HBBTV_ERR_COMP_ALREADY_OPEN -  Timer already open.
 *
 * Parameter     Flow    Description
 * ------------------------------------------------------------------------------
 *
 * Additional information:
 *
 *@end
 *******************************************************************************/
E_HBBTV_ERR HBBTV_TmrInit(U32BIT task_priority);

/*******************************************************************************
 *@begin
 * NAME: HBBTV_TmrExit
 *       Uninitialise the timer component - all resources are freed. Other
 *       timer functions must not be called after calling this function until
 *       mhegTimerInit is called again.
 *
 * Returns : HBBTV_OK              : Timer component sucessfully initialised
 *           TIMER_ERR_SYSTEM_ERROR    : An unexpected system error ocurred.
 *
 * Parameter     Flow    Description
 * ------------------------------------------------------------------------------
 *
 * Additional information:
 *
 *@end
 *******************************************************************************/
E_HBBTV_ERR HBBTV_TmrExit(void);

#endif /* _TIMER_H */