Jump to main content

##

# 1.2.11.4.5 SYS_TIME_CallbackRegisterMS Function

## C

    SYS_TIME_HANDLE SYS_TIME_CallbackRegisterMS(
        SYS_TIME_CALLBACK callback,
        uintptr_t context,
        uint32_t ms,
        SYS_TIME_CALLBACK_TYPE type
    );

## Summary

Registers a function with the time system service to be called back when the requested number of milliseconds has expired (either once or repeatedly).

## Description

Creates a timer object and registers a function with it to be called back when the requested delay (specified in milliseconds) has completed. The caller must identify if the timer should call the function once or repeatedly every time the given delay period expires.

## Precondition

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

## Parameters

Param | Description
--- | ---
callback | Pointer to the function to be called. 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 timer.
context | A client-defined value that is passed to the callback function.
ms | Time period in milliseconds.
type | Type of callback requested. If type is SYS_TIME_SINGLE, the Callback function will be called once when the time period expires. After the time period expires, the timer object will be freed. 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

SYS_TIME_HANDLE - A valid timer object handle if the call succeeds.

SYS_TIME_HANDLE_INVALID if it fails.

## Example

Given a callback function implementation matching the following prototype:

    void MyCallback ( uintptr_t context);

The following example call will register it, requesting a 50 millisecond periodic callback.

    //Give a SYS_TIME_CALLBACK function "MyCallback",
    SYS_TIME_HANDLE handle = SYS_TIME_CallbackRegisterMS(MyCallback, (uintptr_t)0, 50, SYS_TIME_PERIODIC);

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

## Remarks

Will give a callback after the requested number of microseconds or longer have elapsed, depending on system performance. In tick-based mode, the requested delay will be ceiled to the next timer tick.

For example, if the timer tick is set to 700 usec and the requested delay is 2 msec, a delay of 2.1 ms will be generated.

Delay values of 0 will return SYS_TIME_ERROR.