UserTimer

Type

SwitchKit API message

Purpose

Use the SK_UserTimer message to cause an event to arrive at a predetermined time. The message that arrives at timer expiration is a SK_UserTimerAck.

Description

The timer is tracked in the lower layers of the API, not by the LLC. It uses the socket-select mechanism for determining when the timer has expired which allows the timers to be operating system-independent, efficient, and relatively accurate. Without a real-time operating system, there is no guarantee of timing.

There are no data fields in a SK_UserTimer message because, when sent with a tag through an appropriate toolkit sending function, a tag will also be associated with the acknowledgment that arrives after the time period has elapsed.

Sent by

Application

How to Set Up a Timer in C

In C, a variable of SK_UserTimer must be declared. The message must be initialized using sk_initMsg(). Then, the arguments must be initialized. Any of the SwitchKit send routines may be used to send the message and assign a message handler to handle the acknowledgement when the timer expires.

{

...

SK_UserTimer userTimer;

sk_initMsg(&userTimer, TAG_UserTimer);

userTimer.Seconds = 5;

// Number of seconds until timer expires.

userTimer.GroupTag = 3;

// Used to identify timer upon cancellation

sk_sendMsgStruct((MsgStruct *)&userTimer, (void *)myData, timerExpiredHandler);

...

};

How to Set Up a Timer in C++

In C++, a object of class SKC_UserTimer is created. Then, the arguments must be initialized using the setSeconds() and setGroupTag() methods of the class. The send method, which is a member of a base class inherited by SKC_UserTimer, can be used to send the message.

{

...

SKC_UserTimer userTimer;

userTimer.setSeconds(5);

// Number of seconds until timer expires

userTimer.setGroupTag(3);

// Used to identify timer upon cancellation

userTimer.send((void *)myData, timerExpiredHandler);

...

};

Arguments

The following table shows the arguments you can change for UserTimer:

Argument

Description

Seconds

The delta time in seconds from when the UserTimer message is sent to when the UserTimerAck will be sent to indicate expiration of the timer.

GroupTag

Cancellation of a timer requires that GroupTag be set at creation of the timer. When you want to cancel a UserTimer, you need to send a CancelUserTimer message with the appropriate GroupTag. All currently unexpired UserTimer messages from that application with the corresponding GroupTag are canceled.It is important to realize that the GroupTag domain is unique to each application. This prevents one application from canceling another application's UserTimer. If multiple applications use the same GroupTag in a timer, and one application cancels that tag, only the timers from that application will be canceled. All other timers will still expire normally.

Return Status

The following table shows the possible return states:

Value

Description

SK_SUCCESS

Success

SK_CANCELED

Timer is cancelled (verify this)

C Structure

typedef struct {

float Seconds;

int GroupTag;

} SK_UserTimer;

C Structure Response

typedef struct {

int Status;

} SK_UserTimerAck;

C++ Class

class SKC_UserTimer : public SKC_ToolkitMessage {

public:

float getSeconds() const;

void setSeconds(float x);

int getGroupTag() const;

void setGroupTag(int x);

};

C++ Class Response

class SKC_UserTimerAck : public SKC_ToolkitAck {

public:

int getStatus() const;

void setStatus(int x);

};