# dispAddRTC

Registers a condition and corresponding action in the dispatcher's RTC database.

#### Prototype

DWORD dispAddRTC (CTAHD ctahd, RTC_CONDITION *pcondition, RTC_ACTION *paction )

Argument | Description
ctahd | Handle to a Natural Access context.
pcondition | Pointer to an RTC_CONDITION structure describing an RTC condition: 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; See the Details section for field descriptions.
paction | Pointer to an RTC_ACTION structure describing an action for the calling service to take when RTC condition pcondition is met: typedef struct _RTC_ACTION { DWORD Consumer; /* Service ID of RTC consumer */ DWORD ActionCmd; /* Special command sent to service on */ /* recognition of condition */ } RTC_ACTION; See the Details section for field descriptions.

#### Return values

Return value | Description
SUCCESS |
CTAERR_BAD_ARGUMENT | Indicates any of the following: The consumer service is not opened on the context The RTC condition EventId is for a service not attached to the context's CTA queue (see ctaCreateQueue). The Alias parameter is a zero length string, or is a pointer. The ActionCmd is not a Natural Access command value.
CTAERR_INVALID_CTAHD | The specified ctahd is invalid.
CTAERR_NOT_INITIALIZED | Natural Access was not initialized.
CTAERR_OUT_OF_MEMORY | Unable to allocate memory for RTC object.
CTAERR_SVR_COMM | Natural Access Server is not running.

#### Details

dispAddRTC adds an RTC condition/action pair to the dispatcher's database. RTC_CONDITION describes one or more events from a specific service. RTC_ACTION specifies a command for the dispatcher to send to the calling service when an event is generated that is described by RTC_CONDITION.

The following table describes the fields in RTC_CONDITION:

Field | Description
--- | ---
Attribute | Set to one of the following: RTC_NONE: Specifies that the RTC condition is met when the dispatcher receives event EventID with any reason code, or an event with alias Alias. RTC_EVT_WITH_ONE_VALUE: Specifies that the RTC condition is met when the dispatcher receives event EventID with a specific reason code. RTC_ALL_PROVIDER_EVENTS: Specifies that the RTC condition is met when the dispatcher receives any event from a specific service.
EventID | Set as follows, depending upon the Attribute setting: If Attribute is set to RTC_NONE and Alias is a zero-length string, set to the event ID of the trigger event. If Attribute is set to RTC_EVT_WITH_ONE_VALUE, set to the event ID of the trigger event and specify an event value in the EventValue field. If Attribute is set to RTC_ALL_PROVIDER_EVENTS, set to the event ID of an event from the provider service. The dispatcher infers the service name from the event. Any event from the service triggers the action. If Attribute is set to RTC_NONE and Alias is a non-zero-length string, EventID is ignored (Alias specifies the condition).
EventValue | If Attribute is set to RTC_EVT_WITH_ONE_VALUE, specifies the value to look for. Otherwise, EventValue is ignored.
Alias | Specifies an alias name. If the dispatcher detects an event registered to the alias name (using dispRegisterRTCAlias), it triggers the action. To use aliases, set Attribute to RTC_NONE.

The following table describes the fields in RTC_ACTION:

Field | Description
--- | ---
Consumer | Service ID of the service to direct to perform the action.
ActionCmd | Action command to send to the service manager, in the form of a generic DISP_COMMAND structure.

When dispAddRTC is invoked, the dispatcher calls the provider's xxxAddRTC function if the xxxAddRTC function is present in the provider's set of binding functions. The service writer defines the actions taken by the service when this function is called.

Note: If dispAddRTC is invoked with an alias, xxxAddRTC is not invoked until the alias is registered with the dispatcher (using dispRegisterRTCAlias).

dispAddRTC returns SUCCESS even if the RTC provider service is not opened at the time that dispAddRTC is invoked, or if the Alias is not yet registered with the dispatcher. Neither of these situations is an error condition.

#### See also

dispRemoveRTC