OSTmrRemainGet

Description

OSTmrRemainGet() allows the user to obtain the time remaining (before timeout) of the specified timer. The value returned depends on the rate (in Hz) at which the timer task is signaled (see OS_CFG_TMR_TASK_RATE_HZ). If OS_CFG_TMR_TASK_RATE_HZ is set to 10, the value returned is the number of 1/10 of a second before the timer times out. If the timer has timed out, the value returned is 0.

Files

os.h/os_tmr.c

Prototype

OS_TICK  OSTmrRemainGet (OS_TMR  *p_tmr,
                         OS_ERR  *p_err)

Arguments

p_tmr

is a pointer to the timer the user is inquiring about.

p_err

a pointer to an error code and can be any of the following:

OS_ERR_NONE

If the function returned the time remaining for the timer.

OS_ERR_OBJ_TYPE

If OS_CFG_OBJ_TYPE_CHK_EN is set to DEF_ENABLED in os_cfg.h: ‘p_tmr” is not pointing to a timer.

OS_ERR_OS_NOT_RUNNING

If OS_CFG_INVALID_OS_CALLS_CHK_EN is set to DEF_ENABLED in os_cfg.h: if µC/OS-III is not running yet.

OS_ERR_TMR_INACTIVE

p_tmr is pointing to an inactive timer. In other words, this error will appear when pointing to a timer that has been deleted.

OS_ERR_TMR_INVALID

If OS_CFG_ARG_CHK_EN is set to DEF_ENABLED in os_cfg.h: if p_tmr is a NULL pointer.

OS_ERR_TMR_INVALID_STATE

If the timer is in an invalid state.

OS_ERR_TMR_ISR

If OS_CFG_CALLED_FROM_ISR_CHK_EN set to DEF_ENABLED in os_cfg.h: This function is called from an ISR, which is not allowed.

Returned Values

The time remaining for the timer. The value returned depends on the rate (in Hz) at which the timer task is signaled (see OS_CFG_TMR_TASK_RATE_HZ). If OS_CFG_TMR_TASK_RATE_HZ is set to 10 the value returned is the number of 1/10 of a second before the timer times out. If specifying an invalid timer, the returned value will be 0. If the timer expired, the returned value will be 0.

Required Configuration

OS_CFG_TMR_EN must be enabled in os_cfg.h. Refer to µC-OS-III Configuration Manual.

Callers

Application.

Notes/Warnings

Do not call this function from an ISR.

Example Usage

OSTmrRemainGet() example usage

          OS_TICK   TimeRemainToCloseDoor;
          OS_TMR    CloseDoorTmr;
           
           
          void Task (void *p_arg)
          {
              OS_ERR    err;
           
           
              (void)&p_arg;
              while (DEF_ON) {
                  TimeRemainToCloseDoor = OSTmrRemainGet(&CloseDoorTmr,
                                                         &err);
                  /* Check "err" */
                  :
                  :
              }
          }