Timer Utility Functions

Group that contains timer utility functions. More...

Collaboration diagram for Timer Utility Functions:

Functions
void *	pvTimerGetTimerID (const TimerHandle_t xTimer) PRIVILEGED_FUNCTION
	Returns the ID assigned to the timer. More...
void	vTimerSetTimerID (TimerHandle_t xTimer, void *pvNewID) PRIVILEGED_FUNCTION
	Sets the ID assigned to the timer. More...
BaseType_t	xTimerIsTimerActive (TimerHandle_t xTimer) PRIVILEGED_FUNCTION
	Queries a timer to see if it is active or dormant. More...
TaskHandle_t	xTimerGetTimerDaemonTaskHandle (void) PRIVILEGED_FUNCTION
	Simply returns the handle of the timer service/daemon task. It it not valid to call xTimerGetTimerDaemonTaskHandle() before the scheduler has been started.
const char *	pcTimerGetName (TimerHandle_t xTimer) PRIVILEGED_FUNCTION
	Returns the name that was assigned to a timer when the timer was created. More...
TickType_t	xTimerGetPeriod (TimerHandle_t xTimer) PRIVILEGED_FUNCTION
	Returns the period of a timer. More...
TickType_t	xTimerGetExpiryTime (TimerHandle_t xTimer) PRIVILEGED_FUNCTION
	Returns the time in ticks at which the timer will expire. If this is less than the current tick count then the expiry time has overflowed from the current time. More...

Detailed Description

Group that contains timer utility functions.

Function Documentation

pcTimerGetName()

const char* pcTimerGetName

(

TimerHandle_t

xTimer

)

#include <timers.h>

Returns the name that was assigned to a timer when the timer was created.

Parameters

xTimer

The handle of the timer being queried.

Returns

The name assigned to the timer specified by the xTimer parameter.

pvTimerGetTimerID()

void* pvTimerGetTimerID

(

const TimerHandle_t

xTimer

)

#include <timers.h>

Returns the ID assigned to the timer.

IDs are assigned to timers using the pvTimerID parameter of the call to xTimerCreated() that was used to create the timer, and by calling the vTimerSetTimerID() API function.

If the same callback function is assigned to multiple timers then the timer ID can be used as time specific (timer local) storage.

Parameters

xTimer

The timer being queried.

Returns

The ID assigned to the timer being queried.

Example usage:

See the xTimerCreate() API function example usage scenario.

vTimerSetTimerID()

void vTimerSetTimerID	(	TimerHandle_t	xTimer,
		void *	pvNewID
	)

#include <timers.h>

Sets the ID assigned to the timer.

IDs are assigned to timers using the pvTimerID parameter of the call to xTimerCreated() that was used to create the timer.

If the same callback function is assigned to multiple timers then the timer ID can be used as time specific (timer local) storage.

Parameters

xTimer	The timer being updated.
pvNewID	The ID to assign to the timer.

Example usage:

See the xTimerCreate() API function example usage scenario.

xTimerGetExpiryTime()

TickType_t xTimerGetExpiryTime

(

TimerHandle_t

xTimer

)

#include <timers.h>

Returns the time in ticks at which the timer will expire. If this is less than the current tick count then the expiry time has overflowed from the current time.

Parameters

xTimer

The handle of the timer being queried.

Returns

If the timer is running then the time in ticks at which the timer will next expire is returned. If the timer is not running then the return value is undefined.

xTimerGetPeriod()

TickType_t xTimerGetPeriod

(

TimerHandle_t

xTimer

)

#include <timers.h>

Returns the period of a timer.

Parameters

xTimer

The handle of the timer being queried.

Returns

The period of the timer in ticks.

xTimerIsTimerActive()

BaseType_t xTimerIsTimerActive

(

TimerHandle_t

xTimer

)

#include <timers.h>

Queries a timer to see if it is active or dormant.

A timer will be dormant if: 1) It has been created but not started, or 2) It is an expired one-shot timer that has not been restarted.

Timers are created in the dormant state. The xTimerStart(), xTimerReset(), xTimerStartFromISR(), xTimerResetFromISR(), xTimerChangePeriod() and xTimerChangePeriodFromISR() API functions can all be used to transition a timer into the active state.

Parameters

xTimer

The timer being queried.

Returns

pdFALSE will be returned if the timer is dormant. A value other than pdFALSE will be returned if the timer is active.

Example usage:

// This function assumes xTimer has already been created.
void vAFunction( TimerHandle_t xTimer )
{
    if( xTimerIsTimerActive( xTimer ) != pdFALSE ) // or more simply and equivalently "if( xTimerIsTimerActive( xTimer ) )"
    {
        // xTimer is active, do something.
    }
    else
    {
        // xTimer is not active, do something else.
    }
}