irEnd, irEndSeq - mark the end of a list of play or say functions
#include <irapi.h>
int irEnd (channel_id cid, int flag, int tag);
int irEndSeq (channel_id cid, int flag, int tag, int seqno);
The irEnd function marks the end of a list of one or more "play" [irFPlay(3IRAPI)], or "say" [irSay(3IRAPI), irBSay(3IRAPI)or irFSay(3IRAPI)] functions.
The number of bytes played may be obtained by calling irGetVCount(3IRAPI) after receipt of the IRE_PLAY_DONE event.
If flag is set to IRF_REMEMBER, the play activity is remembered. Use IRF_REMEMBER with irPlayResume(3IRAPI) to mark resumable play requests which have been interrupted.
If flag is set to IRF_MORE, the say activities queued are started but the library allows more say requests to be queued. The library expects an irEnd to eventually be executed with flag set to 0 or the channel hangs in the IRS_SAY_QUEUED state. If applications take too long to queue text, callers may hear speech breaks.
IRF_MORE is ignored for queued play requests and IRF_REMEMBER is ignored for queued say requests.
The irEndSeq function is an alternative to irEnd that closes a small and mostly harmless race condition on talkoff with touchtone typeahead.
If an application responds to a touch tone indication by spawning new play, there is a small amount of time between the time when the talkoff is detected and when it is processed the application and the next play started. If a user tries speed up the interaction with the application by entering multiple touchtones before the prompts for each touchtone, it is possible for a small portion of the next prompt to be played before the touchtone for that prompt is recognized and talks off the prompt.
If it is important for an application to keep the touch tones and the play requests in sync with each other, the voice system keeps a sequence number for each touch tone arrival. The sequence number of the next expected play request is presented to the application in the IRE_INPUT event in event mod 3 (see IrEVENTS(4IRAPI)). Applications should pass this sequence number for the play via the irEndSeq call. If the user has managed to get ahead of the processing of touch tones, the system will talkoff the play requests at the time they are queued.
IRE_PLAY_DONE is generated when the play operation has com- pleted, and IRE_SAY_DONE is generated when the last say operation has completed.
The IRE_SAY_DONE event is generated with the IREM_DENY modifier if resources could not be allocated in the time specified by IRP_RESOURCE_RETURNMODE and irEnd returned IRR_PENDING. When resources are allocated after IRR_PENDING is returned, the IRE_GRANT event occurs.
IRR_OK is returned if the request to play or say is successfully initiated.
IRR_FAIL is returned if an error occurs.
IRR_PENDING is returned if no resources are available for the say function.
irError is set as follows if an error occurs:
IRER_INVALID if the cid is invalid
IRER_BADSTATE if irEnd is called without first calling one or more play or say functions, thereby putting the channel into the IRS_PLAY_QUEUED or IRS_SAY_QUEUED states
IRER_RTU_BUSY if the required Feature License's are all in use and IRP_RESOURCE_RETURNMODE is set to IRD_IMMEDIATE
IRER_NO_RTU if no Feature License has been purchased for this function
IRER_SYSERROR if a system call failure occurs (see irSysError for additional information)
irPlay(3IRAPI), irSay(3IRAPI), irStop(3IRAPI).
Applications are no longer sent IRE_PLAY_PROG or IRE_SAY_PROG events.
Say functions no longer return the number of bytes said.
This is version 12/10/02 of this man page.