SFXTimer

Class for dealing with the timer.

#include <SFXTimer.h.hpp>

class SFXTimer;

SFMTYPEDEFCLASS(SFXTimer)

Collaboration diagram

Description

The SFXTimer class is used to deal with a timer, that is, callback that will be called and executed after a specified time elapses.

The method to use the SFXTimer class is as follows:

Set the timer information(callback function and data passed to the callback function) with the SFXTimer::Set function.
Schedule the timer with the SFXTimer::Schedule function, that is, register the callback into the AEE shell. In the argument of this function, the elapsed time until the callback is called should be specified in milliseconds.
When the time specified in the argument of the SFXTimer::Schedule function elapses, the callback will be called.
If the SFXTimer::Cancel function is called before the callback is called, the scheduled timer, the registered callback, will be canceled.

	Internal implementation
	The `SFXTimer` class is implemented by using the `SFXCallback` class. In the internal implementaion, the `BREW API ISHELL_SetTimerEx` function is used to schedule a timer, i.e., register a callback,

class MyClass {
private:
    SFXTimer _timer; 
public:
    Void Function(Void);
    XALLBACK_DECLARE_SFXTIMER(TimerCallback)
};

Void MyClass::Function(Void)
{

    ...
    
    // set information necessary to schedule the timer
    // * set the TimerCallback function and data passed to the TimerCallback function
    _timer.Set(XALLBACK_INTERNAL(TimerCallback));

    // schedule the timer
    // * the TimerCallback function will be called after the 4000 milliseconds elapses
    _timer.Schedule(4000);
}

/// callback function called by BREW environment after the specified time elapses
XALLBACK_IMPLEMENT_SFXTIMER(MyClass, TimerCallback) {

    ...
}

Reference

BREW API ISHELL_SetTimerEx | SFXCallback | SFXTask

Member

Constructor/Destructor
SFXTimer( `Void` ) Constructor of the SFXTimer class.
~SFXTimer( `Void` ) Destructor of the SFXTimer class.

Public Functions
`Void`	Cancel( `Void` ) Cancel the scheduled timer.
static `SFXTimerConstRef`	EmptyInstance( `Void` ) Get the empty timer.
`SFXCallback::CallbackSPP`	GetProcedure( `Void` ) Get the callback function set to this timer.
`VoidPtr`	GetReference( `Void` ) Get the data passed to the callback function set to this timer.
`Bool`	IsValid( `Void` ) Check whether or not the timer is scheduled.
`SFCError`	Schedule( `UInt32` msec ) Schedule the timer.
`Void`	Set( `SFXCallback::CallbackSPP` spp , `VoidPtr` reference ) Set information necessary to schedule the timer.

SFXTimer::SFXTimer

Constructor of the SFXTimer class.

[ public, explicit ]
SFXTimer(Void);

Description

This constructor does nothing.

SFXTimer::~SFXTimer

Destructor of the SFXTimer class.

[ public ]
~SFXTimer(Void);

Description

This destructor cancels to schedule the timer by calling the SFXTimer::Cancel function internally.

Reference

SFXTimer::Cancel | SFXTimer::Schedule

SFXTimer::Cancel

Cancel the scheduled timer.

[ public ]
Void Cancel(Void);

Description

This function cancels the scheduled timer, i.e., the registered callback.

The timer scheduled with the SFXTimer::Schedule function will be canceled. If no timer is scheduled, nothing will happen.

	Tip
	When an application suspends, it is recommended to cancel the scheduled timer with this function.

	Note
	This function is called in the `SFXTimer::~SFXTimer` destructor.

	Note
	Internally, this function calls the `SFXCallback::Cancel` function.

Reference

SFXTimer::Schedule | SFXTimer::~SFXTimer | SFXCallback::Cancel

SFXTimer::EmptyInstance

Get the empty timer.

[ public, static ]
SFXTimerConstRef EmptyInstance(Void);

Return value

Empty SFXTimer instance

Description

This function gets the instance that represents an empty timer.

Reference

SFXTimer::SFXTimer

SFXTimer::GetProcedure

Get the callback function set to this timer.

[ public, const ]
SFXCallback::CallbackSPP GetProcedure(Void);

Return value

Return the callback function set to this timer.

Description

This function gets the callback function set to this timer with the SFXTimer::Set function.

Note

	Note
Internally, this function calls the `SFXCallback::GetProcedure` function. Concretely, the value of the pfnNotify member of the `BREW API AEECallback` structure internally contained by this timer will be returned.

Internally, this function calls the SFXCallback::GetProcedure function.

Concretely, the value of the pfnNotify member of the BREW API AEECallback structure internally contained by this timer will be returned.

Reference

SFXTimer::Set | SFXTimer::GetReference | SFXCallback::GetProcedure | BREW API AEECallback

SFXTimer::GetReference

Get the data passed to the callback function set to this timer.

[ public, const ]
VoidPtr GetReference(Void);

Return value

Data passed to the callback function set to this timer

Description

This function gets the data passed to the callback function set to this timer with the SFXTimer::Set function.

Note

	Note
Internally, this function calls the `SFXCallback::GetReference` function. Concretely, the value of the pNotifyData member of the `BREW API AEECallback` structure internally contained by this timer will be returned.

Internally, this function calls the SFXCallback::GetReference function.

Concretely, the value of the pNotifyData member of the BREW API AEECallback structure internally contained by this timer will be returned.

Reference

SFXTimer::Set | SFXTimer::GetProcedure | SFXCallback::GetReference | BREW API AEECallback

SFXTimer::IsValid

Check whether or not the timer is scheduled.

[ public, const ]
Bool IsValid(Void);

Return value

If scheduled: true
Otherwise: false

Description

This function whether or not the timer is schedule with the SFXTimer::Schedule function.

	Note
	Internally, this function calls the `SFXCallback::IsQueued` function.

Reference

SFXTimer::Schedule | SFXCallback::IsQueued

SFXTimer::Schedule

Schedule the timer.

[ public ]
SFCError Schedule(
    UInt32 msec   // time until the callback function is called ( milli-second )
);

Return value

If succeeds: SFERR_NO_ERROR
If the msec argument is greater than SINT32_MAXIMUM or necessary information is not set with the SFXTimer::Set function: SFERR_INVALID_PARAM
If failed to create the SFBShell instance internally: SFERR_FAILED
If insufficient memory: SFERR_NO_MEMORY

Description

This function schedules the timer, i.e., registers the callback into the AEE shell.

If the timer has already been scheduled, it will be canceled and scheduled again.

If this function is executed, the callback function set with the SFXTimer::Set function will be called when the time set in the msec argument of this function elapses.

	Note
	Internally, after the timer is canceled with the `SFXTimer::Cancel` function, it will be scheduled again with the `SFBShell::SetTimerEx` function.

	Prerequisite
	Before this function is called, it is necessary to set the timer with the `SFXTimer::Set` function.

Reference

SFXTimer::Set | SFXTimer::Cancel | SFXTimer::IsValid | SFBShell | BREW API ISHELL_SetTimerEx

SFXTimer::Set

Set information necessary to schedule the timer.

[ public ]
Void Set(
    SFXCallback::CallbackSPP spp   // callback function that is set to the timer
    VoidPtr reference              // data passed to the callback function
);

Description

This function sets information(callback function and data passed to it) necessary to schedule the timer.

Internally, since the SFXTimer::Cancel function is called first, the timer that has been already scheduled before this function is called will be canceled.

	Note
	After this function is executed, schedule the timer with the `SFXTimer::Schedule` function (register the callback).

	Note
	This function internally calls the `SFXCallback::Set` function to set the callback function and the data passed to it specified in the arguments to the pfnNotify member and the pNotifyData member of the `BREW API AEECallback` structure internally contained by this timer.

Reference