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