NAME
          irSay, irFDSay, irFSay, irBSay - say ASCII text using text-
          to-speech from a file via file descriptor, from a file via
          file name, or from a buffer

     SYNOPSIS
          #include <irapi.h>

          int irSay (channel_id cid, int tag, int vfd, unsigned long
          count);

          int irFSay (channel_id cid, int tag, const char *text_file);

          int irBSay (channel_id cid, int tag, const char *buf,
          unsigned long count);

          int irFDSay (channel_id cid, int tag, int fd, unsigned long
          count);

     DESCRIPTION
          The text-to-speech (TTS) functions say ASCII text on a voice
          channel indicated by a channel identifier (cid).  These
          functions internally use TTS to convert ASCII text into
          speech.  The cid is obtained by calling irInit(3IRAPI).

          tag is an arbitrary value which applications may use to
          associate the IRE_SAY_PROG event with the coresponding irSay
          function.  Note that IRE_SAY_PROG is only supported with the
          IRD_SWTTS implementation of TTS.  With other implementa-
          tions, application developers requiring a tag for "say"
          instructions may use the tag argument provided with
          irEnd(3IRAPI).

          The irSay function says count bytes of ASCII text from the
          file associated with an open voice file descriptor vfd.  Vfd
          is obtained by irOpen(3IRAPI) and discarded by
          irClose(3IRAPI).  "Saying" starts from the current position
          of the file pointer.  The file pointer is initially set to 0
          when the text file is opened (open(2)). However, the file
          pointer may be repositioned by calling irLSeek(3IRAPI).
          irSay does not modify the file pointer for the file descrip-
          tor it is using.  If count is 0, then say continues until
          the end of file.

          irFSay says ASCII text from a file identified by the file
          name text_file. irFSay opens the text_file, says the entire
          file from the beginning, then automatically closes the file.

          irBSay says ASCII text from a buffer identified by the
          buffer name buf.  The data represented by buf and count may
          be reused since irBSay copies the buffer to a private area.
          NULL characters are not interpreted as string terminators by
          irBSay as exactly count bytes of data are taken as input.

          The irFDSay function says count bytes of ASCII text from the
          file associated with an open UNIX file descriptor fd.  Fd is
          obtained by open(2) and discarded by close(2).  "Saying"
          starts from the current position of the file pointer.  The
          file pointer is initially set to 0 when the text file is
          opened (open(2)). However, the file pointer may be reposi-
          tioned by calling lseek(2). irFDSay does not modify the file
          pointer for the file descriptor it is using.  If count is 0,
          then say continues until the end of file.

          TTS functions interoperate with echo cancellation and
          barge-in.

          Any TTS function must be followed by irEnd(3IRAPI).  Any TTS
          function can be terminated when an enabled or non-maskable
          interrupt occurs [see irSetEvent(3IRAPI)]. When irFSay is
          terminated the text_file is closed.

          If the library state is IRS_IDLE (not saying), calling a TTS
          function changes the library state to IRS_SAY_QUEUED.  If
          the library state is IRS_SAY_QUEUED, subsequent calls to a
          TTS function are queued and the library remains in the
          IRS_SAY_QUEUED state.  The TTS functions may be called only
          when the library is in the IRS_IDLE or IRS_SAY_QUEUED
          states.  See irIntro(3IRAPI) for a discussion of library
          states.

          Invocation of multiple TTS functions to a single cid results
          in concatenated speech to be said on that channel.  The
          speech stream, up to a "terminating" irEnd(3IRAPI), said
          seamlessly. Any of the TTS functions may be intermixed
          before the list is terminated by irEnd(3IRAPI).  Upon cal-
          ling irEnd(3IRAPI), the library enters the IRS_SAYING or
          IRS_SAY_PENDING states depending on TTS resource availabil-
          ity.

          Upon calling irEnd, IRAPI will attempt to use the implemen-
          tation of TTS specified in IRP_TTS_TTPE, see
          IrPARAMETERS(4IRAPI).

     EVENT
          An IRE_SAY_DONE event is generated after irEnd(3IRAPI) is
          called and all queued irSay requests have completed or are
          interrupted [as indicated in the modifier to IRE_SAY_DONE,
          see IrEVENTS(4IRAPI)].

          An IRE_SAY_PROG event, if enabled, is generated after each
          intermediate irSay request completes.  Note that this event
          is only supported for the IRD_SWTTS implementation.

     RETURN VALUE
          IRR_OK is returned if the say request is successfully
          queued.

          IRR_FAIL is returned if an error occurs.

     ERROR
          irError is set as follows if an error occurs:

          IRER_INVALID if the cid or the fd are not valid

          IRER_SYSERROR if a system or driver call failure occurs
          (check irSysError for additional information)

          IRER_BADSTATE if the cid is not in the IRS_SAY_QUEUED or
          IRS_IDLE state

          IRER_NO_TIMESLOT if there is no longer a "talk" timeslot
          allocated for this cid.

          Note, for irFSay, if text_file does not exist, irFSay fails.
          This differs from irFPlay(3IRAPI) where non-existence of a
          voice file is indicated through modifiers on the
          IRE_PLAY_DONE event.

     SEE ALSO
          irPlay(3IRAPI), irConvertTTS(3IRAPI),
          irFGetLanguage(3IRAPI), IrPARAMETERS(4IRAPI),
          IrEVENTS(4IRAPI)

     VERSION
          This is version 8/31/00 of this man page.