dispRemoveRTC

Argument

Description

ctahd

Handle to a Natural Access context.

pcondition

Pointer to an RTC_CONDITION structure describing an RTC condition to be removed:

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;

paction

Pointer to an RTC_ACTION structure describing an action. Together with RTC_CONDITION, RTC_ACTION is used to explicitly specify the condition/action pair to be removed:

typedef struct _RTC_ACTION
{
  DWORD  Consumer;  /* Service ID of RTC consumer          */
  DWORD  ActionCmd; /* Special command sent to service on  */
                    /* recognition of condition            */
} RTC_ACTION;

Return value

Description

SUCCESS

CTAERR_BAD_ARGUMENT

Indicates any of the following:

• pcondition or paction is NULL.

• Consumer service is not opened on the context.

• RTC condition EventId is for a service not attached to the context's CTA queue (see ctaCreateQueue).

• Alias is a zero length string.

• ActionCmd is not a Natural Access command value.

CTAERR_INVALID_CTAHD

Specified ctahd is invalid.

CTAERR_NOT_FOUND

Specified condition/action pair was not found in the Natural Access dispatcher's RTC database.

CTAERR_NOT_INITIALIZED

Natural Access is not initialized.

CTAERR_SVR_COMM

Natural Access Server is not running.

Attribute

Set to one of the following to determine which condition/action pairs to remove:

• RTC_EVT_WITH_ONE_VALUE: A specific pair where the event matches the EventID field and the event value matches the EventValue field.

• RTC_EVT_WITH_ANY_VALUE: All pairs where the event matches the EventID field. The event can have any value.

• RTC_NONE: All pairs where the event matches the EventID field or the alias matches the Alias field, and the action matches the ActionCmd field (in RTC_ACTION). The event can have any value.

• RTC_ALL_PROVIDER_EVENTS: All pairs where the event is from a specific provider service. (The service is inferred from the event ID provided in the EventID field.)

• RTC_ALL_CONSUMER_RTCS: All condition/action pairs relevant to the calling 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.

• If Attribute is set to RTC_EVT_WITH_ANY_VALUE, set to the event ID.

• If Attribute is set to RTC_EVT_WITH_ONE_VALUE, set to the event ID. and specify the event value in the EventValue field.

• If Attribute is set to RTC_ALL_PROVIDER_EVENTS, set to the event ID of any event from the provider service. The dispatcher infers the service name from the event.

• If Attribute is set to RTC_ALL_CONSUMER_RTCS, EventID is ignored.

EventValue

If Attribute is set to RTC_EVT_WITH_ONE_VALUE, specifies the value to look for. Otherwise, EventValue is ignored.

Alias

Specifies a condition/action pair to remove, where the condition is an alias. To specify a pair this way, also set Attribute to RTC_NONE

Consumer

Specifies the service ID of the consumer service.

ActionCmd

If Attribute is set to RTC_NONE and you are not specifying an alias (in the Alias field in RTC_CONDITION) set to the action command of the condition/action pair to be removed. If Attribute is set any other way, this field is ignored.