NAME
          irFAXEnd - mark the end of a list of FAX print functions

     SYNOPSIS
          #include <irapi.h>

          int irFAXEnd (channel_id cid, const char *tsi, const char
          *comments, int tag);

     DESCRIPTION
          The irFAXEnd function marks the end of a list of one or more
          FAX print [ irFAXPrint(3IRAPI)] functions for the channel
          specified by cid.

          tsi is the international telephone number of the channel
          printing the FAX or any alphabetic identification no more
	  than 20 characters.

          comments is arbitrary text to allow the FAX request to be
          traced from the application to the FAX server.

          tag is a user defined (24-bit) value which is returned with
          the subsequent IRE_FAXPRINT_DONE event.

          irFAXEnd(3IRAPI) must be called with the channel in the
          IRS_FAXPRINT_QUEUED library state.  If successful, the chan-
          nel is moved to the IRS_FAXPRINTING_PENDING state; on error
          the FAX queue is cleared.  If no FAX jobs are active, the
          channel is returned to the IRS_IDLE state, otherwise the
          channel is returned to the IRS_FAXPRINTING (as it was before
          the queuing irFAXPrint(3IRAPI) function was called).

          A FAX request may be stopped any time after returning from
          irFAXEnd(3IRAPI) by calling irStop(3IRAPI).

     EVENT
          IRE_FAXPRINT_PROG is generated when a FAX job_id is acquired.
	  The job_id is returned in the event_text element of the
	  event structure. If event_mod1 is IREM_ERROR, the job_id
	  is not valid and the subsequent IRE_FAXPRINT_DONE will
	  indicate failure.

          IRE_FAXPRINT_DONE is generated when the FAX operation com-
          pletes.  event_mod1 contains the results of the FAX print
          request. event_text contains the job_id for the FAX request.

          The IRE_FAXPRINT_DONE event is generated with the IREM_DENY
          modifier if resources could not be allocated in the time
          specified by IRP_RESOURCE_RETURNMODE and irFAXEnd(3IRAPI)
          returned IRR_PENDING.  When resources are allocated after
          IRR_PENDING is returned, the IRE_GRANT event occurs.

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

          IRR_FAIL is returned if an error occurs.

          IRR_PENDING is returned if no resources are available for
          the FAX function.

     ERROR
          irError is set as follows if an error occurs:

          IRER_INVALID if the cid is invalid

          IRER_BADSTATE if irFAXEnd is called without first calling
          one or more FAX print functions, thereby putting the channel
          into the IRS_FAXPRINT_QUEUED state

          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_RESOURCEBUSY if there are no resources available and
          IRP_RESOURCE_RETURNMODE is set to IRD_IMMEDIATE

          IRER_NORESOURCES if there are no resources in existence

          IRER_RESTRICTED if the channel is restricted from using the
          required resources

          IRER_DRIVER_ERROR if a driver call failure occurs (see
          irSysError for additional information)

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

          IRER_APIERROR if a third party API call failure occurs (see
          irSysError for additional information)

     EXAMPLES
          The following pseudo code is intended to show possible func-
          tion call sequences:

          Print a single FAX from a TIFF 6.0 file:

              irFAXPrint(cid, file);
              irFAXEnd(cid, tsi, "", 0, NULL);
              while (irWCheck(&ev) != IRR_FAIL) {
                  /* Process IRE_FAXPRINT_DONE        */
                  ...

              }

          Print a FAX from a text file and TIFF image:

              irFAXPrintText(cid, testFile);
              irFAXPrint(cid, file);
              irFAXEnd(cid, tsi, "", 0, NULL);
              while (irWCheck(&ev) != IRR_FAIL) {
                  /* Process IRE_FAXPRINT_DONE        */
                  ...
              }

          Print two separate FAX jobs on the same call:

              irFAXPrint(cid, testFile);
              irFAXEnd(cid, tsi, "", TAG1, NULL);
              while (irWCheck(&ev) != IRR_FAIL) {
                  /* Process 1 IRE_FAXPRINT_PROG event        */
                  ...
              }
              irFAXPrint(cid, testFile);
              irFAXEnd(cid, tsi, "", TAG2, NULL);
              while (irWCheck(&ev) != IRR_FAIL) {
                  /* Process IRE_FAXPRINT_PROG event and 2
                   * IRE_FAXPRINT_DONE events        */
                  ...
              }


     SEE ALSO
          irFAXPrint(3IRAPI), IrEVENTS(4IRAPI).

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