You are here: CSP API Reference > 1 EXS & SwitchKit API Messages > 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);
};