1.2.11.4.17 SYS_TIME_TimerCreate Function

C

SYS_TIME_HANDLE SYS_TIME_TimerCreate (
    uint32_t count,
    uint32_t period,
    SYS_TIME_CALLBACK callback,
    uintptr_t context,
    SYS_TIME_CALLBACK_TYPE type
);

Summary

Creates and initializes a new 32-bit software timer instance.

Description

This function creates/allocates a new instance of a 32-bit software timer.

A software timer provides a counter that is separate from other timer counters and is under control of the caller. The counter can be started and stopped under caller control and its counter value and period value can be changed while the counter is either running or stopped.

Precondition

The SYS_TIME_Initialize function should have been called before calling this function.

Parameters


Param	Description
count	The initial value of the counter, after the timer has been created and before it has been started.
period	The counter interval at which the timer indicates time has elapsed.
callback	Pointer to function that will be called every time the period counts have elapsed. (Actual timing will depend on system performance and the base frequency at which the time service is configured). For single shot timers, the callback cannot be NULL. For periodic timers, if the callback pointer is given as NULL, no callback will occur, but SYS_TIME_TimerPeriodHasExpired can still be polled to determine if the period has expired for a periodic shot timer.
context	A caller-defined value that's passed (unmodified) back to the client as a parameter of callback function. It can be used to identify the client's context or passed with any value.
type	Type of callback requested. If type is SYS_TIME_SINGLE, the Callback function will be called once when the time period expires. If type is SYS_TIME_PERIODIC Callback function will be called repeatedly, every time the time period expires until the timer object is stopped or deleted.

Returns

An opaque value used to identify software timer instance if the call succeeds in allocating/creating the software timer. If the call fails SYS_TIME_HANDLE_INVALID is returned.

Example

Given an implementation of the following function prototype:

void MyCallback ( uintptr_t context);

The following example creates a software timer instance.

SYS_TIME_HANDLE handle;

//myData is the user-defined data that will be passed back in the registered callback function.
handle = SYS_TIME_TimerCreate(0, SYS_TIME_MSToCount(200), &MyCallback, (uintptr_t)&myData, SYS_TIME_SINGLE);

if (handle != SYS_TIME_HANDLE_INVALID)
{
    //timer is created successfully.
}

Remarks

None.