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