NAME
          irFlash - flash the switch-hook

     SYNOPSIS
          #include <irapi.h>

          int irFlash (channel_id cid, int tag);

     DESCRIPTION
          The irFlash function flashes the switch-hook for the channel
          specified as cid.

          Tag is a user-supplied number that associates an irFlash
          function call with a subsequent event.  The event is
          returned in an event structure ir_event_struct [see
          IrEVENTS(4IRAPI)] that is accessed by irCheck(3IRAPI).

          IRAPI library parameter IRP_FLASH_DURATION [see
          IrPARAMETERS(4IRAPI)] defines the duration of the switch-
          hook flash. Its existing value can be retrieved using
          irGetParam(3IRAPI) while a new value can be assigned to it
          using irSetParam(3IRAPI).  The default IRP_FLASH_DURATION
          depends on the parameters associated with switch integra-
          tion.  If a different flash duration is required, this
          parameter must be set to the desired value before invoking
          irFlash. irFlash uses the value available at the time of
          flashing the switch-hook.

          IRAPI library parameter IRP_FLASH_TYPE indicates whether to
          wait after generating the flash.  The default value
          IRD_FLASH_NO_WAIT applies to all telephony types for which
          flash is supported and indicates that the IRE_FLASH_DONE
          event is generated as soon as the flash has been generated.
          The optional value of IRD_FLASH_AND_WAIT applies only to
          Line Side T1 (LST1) and indicates that the library should
          wait briefly after generating the flash so that the switch
          can prepare to detecting DTMF digits used for dialing.
          Currently with LST1, there is no dial tone detection so this
          brief wait helps the switch to prepare to detect digits, but
          cannot ensure that the switch is ready.

          The FLASH_DONE_EVENT indicates that the flash has been gen-
          erated, but does not ensure that the switch is ready to
          accept digits for dialing.  When used with Tip/Ring (T/R)
          channels, the application may wish to also wait for an
          IRE_CALL_PROG or IRE_DISCONNECT_TONE event indicating
          whether dial tone or some other tone is detected.
          (event_mod1 is IREM_DIALTONE or IREM_STUTTER_DIALTONE when
          dialtone is detected). As mentioned above, dial tone detec-
          tion is not available with LST1 so IRD_FLASH_AND_WAIT for
          IRP_FLASH_TYPE should be used instead.

          WARNING: The parameters described above must be changed
          before calling irFlash or after receiving the IRE_FLASH_DONE
          event.  Changing them while a flash attempt is in progress
          can lead to unexpected results.

          Flashing is not supported for all telephony types (eg. PRI)
          and will only achieve the desired results if the switch sup-
          ports flash in the manner desired.

     EVENT
          An IRE_FLASH_DONE event is returned with the appropriate
          modifier to indicate the success or failure of the function.
          Applications should be prepared to deal with the the dial-
          tone event occurring either before or after the
          IRE_FLASH_DONE event.

     RETURN VALUE
          IRR_OK is returned if the request is successfully initiated.

          IRR_FAIL is returned if an error occurs.

     ERROR
          irError is set as follows if an error occurs:

          IRER_INVALID if the cid is invalid

          IRER_SERVICESTATE if the cid is not in the IRD_ACTIVE ser-
          vice state

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

          IRER_UNSUPPORTED if a flash is attempted on telephony
          hardware that does not support the feature

          IRER_BADSTATE if the cid is not in the IRS_IDLE library
          state

     SEE ALSO
          irSetParam(3IRAPI), irGetParam(3IRAPI),
          IrPARAMETERS(4IRAPI), IrEVENTS(4IRAPI)

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