CancelUserTimer

Type:

SwitchKit API message

Description

Use this message to cancel a previously sent UserTimer message or group of UserTimer messages. This will cause the canceled timer to go off with a negative status value, SK_CANCELED. All handler functions which are installed to handle UserTimer expirations should be prepared to do nothing if the Status is not positive. If you want to cancel a UserTimer, the GroupTag should be set when the UserTimer is sent. This GroupTag should be saved for later use.

When you want to cancel that timer, you need to send a CancelUserTimer message with the appropriate GroupTag entered. All currently unexpired UserTimer messages from that application with the corresponding GroupTag are canceled, and the acknowledgment sent back will contain the number of timers that were canceled. Depending on how the UserTimer messages are set up, you can cancel a set of UserTimer messages with a single CancelUserTimer message.

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.

Sent by

Application

Arguments

The following table shows the arguments that you can modify:

Argument

Description

GroupTag

Cancellation of a timer requires that this field be set at creation of the timer and then remembered. When you want to cancel that timer, you need to send a CancelUserTimer message with the appropriate GroupTag entered. 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.

C Structure

typedef struct {

int GroupTag;

} SK_CancelUserTimer;

C Structure Response

typedef struct {

int Status;

int GroupTag;

int NumCanceled;

} SK_CancelUserTimerAck;

C++ Class

class SKC_CancelUserTimer : public SKC_ToolkitMessage {

public:

int getGroupTag() const;

void setGroupTag(int x);

};

C++ Class Response

class SKC_CancelUserTimerAck : public SKC_ToolkitAck {

public:

int getStatus() const;

void setStatus(int x);

int getGroupTag() const;

void setGroupTag(int x);

int getNumCanceled() const;

void setNumCanceled(int x);

};