Prosody generic: API: smd_ev_create

Prototype Definition

int smd_ev_create(tSMEventId *eventId, tSMChannelId channelId, int eventType, int eventChannelBinding)

Parameters

eventId
The created event
channelId
The channel that this event will be associated with
eventType
The type of the event to create. One of these values: kSMEventTypeReadData, kSMEventTypeWriteData, or kSMEventTypeRecog.
eventChannelBinding
Indicator of whether the event is for 'any channel' use or a single specific channel. One of the following values: kSMChannelSpecificEvent, kSMChannelSpecificEventNonIdle, or kSMAnyChannelEvent.

Description

Creates an operating system event object suitable for use with a specific channel indicated by channelId (the parameter eventChannelBinding must be set to kSMChannelSpecificEvent in this case) or, alternatively, creates an operating system event object for collective use by all nominated channels (in which case channelId must be set to kSMNullChannelId and eventChannelBinding to kSMAnyChannelEvent).

Only on Prosody version 2 (TiNG): See the document Prosody TiNG: any channel operation for how to use 'any channel' events.

An application which waits on a channel-specific event will be woken whenever the channel is ready for servicing. This includes whenever an operation on the channel may have a status change to report, as well as whenever there is no operation in progress on the channel (because the channel is ready to start a new operation).

An application which waits on an 'any channel' event will be woken when any of the channels which have been associated with that event are ready for servicing. In this case a channel which has no operation in progress is not considered to be ready for servicing. This is because 'any channel' events are provided for backward compatibility with Prosody version 1, which had this behaviour.

Note that an application may sometimes be woken even though no status change is found. This happens in certain cases where the API library discovers when checking the status that the change is not of a type appropriate to report to the application (which may be because it related to a facility not currently in use or because it is only for internal purposes within the library).

The eventType parameter indicates which type of event should be created, see sm_channel_set_event() API call description for more details.

An identifier for the new event object is stored in the location pointed at by eventId. You can wait on the event as described in smd_ev_wait().

Returns

0 if call completed successfully, otherwise a standard error such as:

This function is part of the Prosody generic API.