NAME
          irFAXPrint, irFAXPrintText, irFAXBPrintText, irFAXPrintImage
          - queue a FAX for printing

     SYNOPSIS
          #include <irapi.h>

          int irFAXPrint (channel_id cid, const char *file);

          int irFAXPrintText (channel_id cid, const char *file);

          int irFAXBPrintText (channel_id cid, const char *buf, int
          count);

          int irFAXPrintImage (channel_id cid, const ir_fax_image
          *image);

     DESCRIPTION
          The FAX print functions queue a FAX object for printing.
          The cid is the channel id for which FAX printing is
          intended.

          The function irFAXPrint queues a FAX file, specified through
          file for printing.  The FAX file is assumed to be a TIFF 6.0
          file.

          The function irFAXPrintText queues a text file, specified
          through file for printing.  The text file is automatically
          converted to a FAX image.

          The function irFAXBPrintText queues a text buffer pointed to
          by buf of length count for printing.  The text buffer is
          automatically converted to a FAX image.

          The function irFAXPrintImage queues a FAX image as described
          by the ir_fax_image structure:

              typedef struct {
                  const char *image;
                  int image_type;
                  const char *background;
              } ir_fax_image;

          Where image is a path name to the primary image file,
          image_type is either IRA_TEXT or IRA_TIFF for a text or TIFF
          file respectively, and background is a path name to a back-
          ground image file.  The background image file must be a TIFF
          file. The background image printing is currently unsupported.

          Any number and type of FAX objects may be placed on the FAX
          queue.  Once queued, the FAX(es) may be sent immediately via
          irFAXEnd(3IRAPI) or queued for printing out of the current
          call either immediately or at some future time via
          irFAXOutOfCall(3IRAPI).

          When a FAX printing function returns successfully, the
          library moves to the IRS_FAXPRINT_QUEUED state.  When
          irFAXEnd(3IRAPI) returns successfully and FAX resources are
          available, the library moves to the IRS_FAXPRINTING state;
          when resources are pending the library moves to the
          IRS_FAXPRINT_PENDING state.

          A FAX print function may be called after irFAXEnd is called
          while the library is in the IRS_FAXPRINTING state.  This
          allows an application to send multiple FAX jobs per call and
          to receive indication of completion of each individual FAX
          request.

          If irStop(3IRAPI) is called from the IRS_FAXPRINT_QUEUED
          state and no FAX job has been previously started via
          irFAXEnd, the outbound FAX queue will be cleared and the
          library will be immediately returned to the IRS_IDLE state.
          If irStop(3IRAPI) is called from the IRS_FAXPRINT_QUEUED
          state and a FAX job has been previously started via
          irFAXEnd, the outbound FAX queue will be cleared and the
          application must wait for the IRE_FAXPRINT_DONE event for
          the previously started FAX to complete the termination pro-
          cess.  If irStop(3IRAPI) is called from the IRS_FAXPRINTING
          or IRS_FAXPRINT_PENDING state, the FAX request will be ter-
          minated.  Applications must wait for IRE_FAXPRINT_DONE.

          If FAX delivery is not intended for the current call, the
          function irFAXOutOfCall(3IRAPI) queues the FAX for out of
          call delivery to a specific FAX destination at a specified
          time, etc.  The library returns immediately to the IRS_IDLE
          state.

     EVENTS
          An IRE_FAXPRINT_DONE event is generated when all FAX
          requests preceding the irFAXEnd(3IRAPI) complete or an
          interrupt occurs which causes FAXing to stop.  Event_mod1
          will contain the FAX completion status.  A separate
          IRE_FAXPRINT_DONE event will be generated for each FAX job
          started via irFAXEnd.

     RETURN VALUE
          IRR_OK is returned if the request is successful.

          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 or if buf or file is the
          NULL pointer.

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

     SEE ALSO
          irFAXEnd(3IRAPI), irFAXOutOfCall(3IRAPI),
          IrPARAMETERS(4IRAPI), IrEVENTS(4IRAPI).

     VERSION
          This is version 7/11/02 of this man page.