To register a condition and associated action, the service manager invokes dispAddRTC and passes pointers to the RTC_CONDITION and RTC_ACTION structures specifying the condition and action. The RTC_CONDITION and RTC_ACTION structures are defined in ctadisp.h:
typedef struct _RTC_CONDITION
{
RTC_ATTRIBUTES Attribute; /* Characteristics of RTC condition */
DWORD EventID; /* Service's event ID for condition */
DWORD EventValue; /* Specific value sent with the event */
/* - used with Attribute RTC_WITH_VALUE */
char Alias[ RTC_NAME_LEN ]; /* ASCII name of RTC condition */
} RTC_CONDITION;
typedef struct _RTC_ACTION
{
DWORD Consumer; /* Service ID of RTC consumer */
DWORD ActionCmd; /* Special command sent to service on */
/* recognition of condition */
} RTC_ACTION;
When specifying a condition using dispAddRTC, fill the fields in RTC_CONDITION as directed in the following table:
|
For the registering service to perform RTC_ACTION whenever... |
Fill the fields in RTC_CONDITION as follows: |
|---|---|
|
The dispatcher receives a specific event with any reason code |
Attribute: RTC_NONE EventID: The event ID of the trigger event EventValue: Any value (will be ignored) Alias: Zero-length string |
|
The dispatcher receives a specific event with a specific reason code |
Attribute: RTC_EVT_WITH_ ONE_VALUE EventID: The event ID of the trigger event EventValue: The value to look for Alias: Zero-length string |
|
The dispatcher receives any event from a specific service |
Attribute: RTC_ALL_ PROVIDER_EVENTS EventID: The event ID of any event from the service. (The provider service is implied from the service identifier within the event ID.) EventValue: Any value (will be ignored) Alias: Zero-length string |
|
The dispatcher receives an event associated with a specific alias |
Attribute: RTC_NONE EventID: Any value (will be ignored) EventValue: Any value (will be ignored) Alias: The alias string (for example: disconnect) By default, alias strings can be up to 12 characters in length (this value is specified by the RTC_NAME_LEN constant in ctadisp.h). Aliases are case-insensitive: the RTC logic converts all alias name strings to lowercase before storing them in the database. |
A consumer service can cancel RTC notification using the dispatcher function dispRemoveRTC. The service can cancel all RTC notifications, or unregister only for specific conditions.
A consumer service can invoke dispRemoveRTC at any time. Typically, however, if RTC notifications are set up when a service is initialized, notifications are removed when the service is closed (xxxCloseService is invoked).
With dispRemoveRTC, the service manager passes pointers to RTC_CONDITION and RTC_ACTION structures specifying the condition and action pair to remove from the database. When removing a condition using dispRemoveRTC, fill the fields in RTC_CONDITION and RTC_ACTION as directed in the following table:
|
For the registering service to STOP RTC notification for events that match these criteria: |
Fill the fields in RTC_CONDITION as follows: |
Fill the fields in RTC_ACTION as follows: |
|---|---|---|
|
A specific provider A specific event ID A specific reason code Any action command |
Attribute: RTC_EVT_WITH_ ONE_VALUE EventID: The event ID of the trigger event EventValue: The value to look for Alias: Zero-length string |
Consumer: The ID of the consumer service ActionCmd: Any value (will be ignored) |
|
A specific provider A specific event ID Any reason code Any action command |
Attribute: RTC_EVT_WITH_ ANY_VALUE EventID: The event ID of the trigger event EventValue: Any value (will be ignored) Alias: Zero-length string |
Consumer: The ID of the consumer service ActionCmd: Any value (will be ignored) |
|
A specific provider A specific event ID Any reason code A specific action command |
Attribute: RTC_NONE EventID: The event ID of the trigger event EventValue: Any value (will be ignored) Alias: Zero-length string |
Consumer: The ID of the consumer service ActionCmd: The action command |
|
A specific provider Any event ID Any reason code Any action command |
Attribute: RTC_ALL_ PROVIDER_ EVENTS EventID: The event ID of any event from the service. (The provider service is implied from the service identifier within the event ID.) EventValue: Any value (will be ignored) Alias: Zero-length string |
Consumer: The ID of the consumer service ActionCmd: Any value (will be ignored) |
|
Any provider Any event ID Any reason code Any action command |
Attribute: RTC_ALL_ CONSUMER_RTCS EventID: Any value (will be ignored) EventValue: Any value (will be ignored) Alias: Zero-length string |
Consumer: The ID of the consumer service ActionCmd: Any value (will be ignored) |
|
A specific alias |
Attribute: RTC_NONE EventID: Any value (will be ignored) EventValue: Any value (will be ignored) Alias: The alias string (for example: disconnect) |
Consumer: The ID of the consumer service ActionCmd: Any value (will be ignored) |