AIDA_pstReceiveEvent

The AIDA_pstReceiveEvent function fetches one event from the AIDA receive event queue.

AIDA_tstEvent *AIDA_pstReceiveEvent(
  handle hStack,
  dword dwStackLevelMask,
  dword dwEventMask,
  tstTimeVal *pstTimeout
);

Parameters

hStack

Specifies the AIDA stack where the event shall be fetched from. This is a handle to an AIDA stack created by one of the AIDA stack manipulation functions.

dwStackLevelMask

Specifies the AIDA stack levels where the event shall be fetched from. Every bit corresponds to a stack level returned by the AIDA_bAddToStack function (bit 0 -> stack level 0 ... bit 31 -> stack level 31). When dwStackLevelMask is set to AIDA_nAllStackLevels the function will receive events of any stack level.

dwEventMask

Defines which types of events have to be received. The possible values are derived from AIDA_tenEventType. There is a special value AIDA_dwAllEvents that can be used if the function shall get any type event in the queue.

pstTimeout

Specifies how long the function shall wait for any event specified by dwEventMask. The value may be an absolute or a relative timeout (look at tstTimeVal for details). There are two values with a special meaning: If *pstTimeout is AIDA_stTimeoutImmediate the function will return immediately, if *pstTimeout is AIDA_stTimeoutInfinite the function not return before an event of one of the given types in dwEventMask is generated.

Return Values

AIDA_pstReceiveEvent returns a pointer to a received event.

In case of failure the function will return NULL. The application can retrieve the error code using AIDA_iGetError.

Remarks

If dwEventMask is not set to receive all events the events of types not selected in dwEventMask remain in the queue. Either the application may prevent the generation of events of unwanted types using AIDA_boSetEventTypes or has to make sure that it removes unwanted events from the queue before a queue overflow occurs.

If an AIDA component can not process an event generated by a lower component it will pass it to the next higher AIDA component in the stack. So it may happen that the AIDA_pstReceiveEvent function returns events of lower components. An application is able to block the generation of these eventually unwanted events using the AIDA_boSetEventTypes function.

QuickInfo

  Windows NT: Requires version 3.1 or later.
  Windows: Requires Windows 95 or later.
  Linux: Requires a kernel supporting ELF binaries.
  Header: Declared in bsk_aida.h, also requires portab.h.
  Import Library (Windows): Use BSK_AIDA.lib.

See Also

AIDA Overview, AIDA Functions, AIDA_pstCreateEvent, AIDA_pstCreateEventEx, AIDA_boSetEventID, AIDA_boDeleteEvent, AIDA_pstCloneEvent, AIDA_boSendEvent, AIDA_boWaitEvent, AIDA_boSetEventTypes, AIDA_boGetEventTypes