OSTmrStop

Description

OSTmrStop() allows the user to stop a timer. The user may execute the callback function of the timer when it is stopped, and pass this callback function a different argument than was specified when the timer was started. This allows the callback function to know that the timer was stopped since the callback argument can be set to indicate this (this is application specific). If the timer is already stopped, the callback function is not called.

Files

os.h/os_tmr.c

Prototype

CPU_BOOLEAN  OSTmrStop (OS_TMR  *p_tmr,
                        OS_OPT   opt,
                        void    *p_callback_arg,
                        OS_ERR  *p_err)

Arguments

p_tmr

is a pointer to the timer control block of the desired timer.

opt

is used to specify options:

OS_OPT_TMR_NONE

No option

OS_OPT_TMR_CALLBACK

Run the callback function with the argument specified when the timer was created.

OS_OPT_TMR_CALLBACK_ARG

Run the callback function, but use the argument passed in OSTmrStop() instead of the one specified when the task was created.

p_callback_arg

is a new argument to pass the callback functions (see options above).

p_err

is a pointer to a variable that contains an error code returned by this function.

OS_ERR_NONE

If the call was successful.

OS_ERR_OBJ_TYPE

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

OS_ERR_OPT_INVALID

If OS_CFG_ARG_CHK_EN is set to DEF_ENABLED in os_cfg.h: if a valid option is not specified.

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

If the timer cannot be stopped since it is inactive.

OS_ERR_TMR_INVALID

If OS_CFG_ARG_CHK_EN is set to DEF_ENABLED in os_cfg.h: if you passed a NULL pointer for the p_tmr argument.

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: if calling this function from an ISR.

OS_ERR_TMR_NO_CALLBACK

If the timer lacks a callback function. This should have been specified when the timer was created.

OS_ERR_TMR_STOPPED

If the timer is currently stopped.

Returned Values

DEF_TRUE

If the timer was stopped (even if it was already stopped).

DEF_FALSE

If an error occurred.

Required Configuration

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

Callers

Application.

Notes/Warnings

1. Do not call this function from an ISR.
2. The callback function is not called if the timer is already stopped.

Example Usage

          OS_TMR  CloseDoorTmr;
           
           
          void Task (void *p_arg)
          {
              OS_ERR       err;
              CPU_BOOLEAN  is_stopped;
           
           
              (void)&p_arg;
              while (DEF_ON) {
                  is_stopped = OSTmrStop(&CloseDoorTmr,
                                          OS_TMR_OPT_CALLBACK,
                                         (void *)0,
                                         &err);
                  /* Check "err" */
                  :
                  :
              }
          }