7.1 Introduction

7.2 NaturalFax Device Class

7.3 Programming NaturalFax for TAPI

7.4 Handling Events

7.5 Working with Document Queues

7.5.1 Building a Document Queue

7.6 Transmitting and Receiving Faxes

7.6.1 Transmitting Faxes

7.6.2 Receiving Faxes

7.6.3 Polling the Called Fax Terminal

7.6.4 Answering a Poll Request

7.6.5 Resetting a Document Queue

7.6.6 Image Conversion During Fax Transmission

7.6.7 Image Conversion During Fax Reception

7.7 Monitoring Fax Session Status

7.8 Requesting Fax Session Status

7.8.1 Error Handling During a Fax Session

7.8.2 Tracing NaturalFax for TAPI Applications

7.9 Terminating and Shutting Down

7.9.1 Tearing Down a Document Queue

7.10 Example: Sending a Fax

7.11 Example: Receiving a Fax

7.1 Introduction

The NaturalFax for TAPI API enables applications to send and receive faxes using NMS hardware.

The following table describes the fax functions supported by NMS TAPI:

NaturalFax for TAPI Functions	Description
faxAnswerFaxPoll	Provides a queue of documents to send in response to a poll request from the remote sending fax terminal.
faxClose	Closes the devices and invalidates the associated handle.
faxCreateQueue	Creates a queue for either sending or receiving documents.
faxDestroyQueue	Deletes the specified document queue.
faxEnqueueDoc	Adds a document to a document queue.
faxGetDocStatus	Returns the status of a document in the specified queue.
faxGetID	Supplies a fax device ID.
faxGetMessage	Handles events using a Win32 event object.
faxGetSessionStatus	Returns status information during a fax send or receive operation.
faxOpen	Accepts a device ID, verifies the device, and creates and stores an associated handle.
faxReceiveFax	Starts negotiating as the called fax terminal and then places all received documents into the receive queue.
faxResetQueue	Resets all documents in a queue to unsent.
faxSendFax	Starts negotiating with the remote fax receiver and subsequently sends all the documents in the send queue.
faxStopSession	Stops a fax send or receive operation in progress.

Note: faxReceiveDocument and faxSendDocument are no longer supported by NMS TAPI. Use faxReceiveFax and faxSendFax instead. For more information on using faxReceiveFax and faxSendFax, see Section 7.10, Example: Sending a Fax and Section 7.11, Example: Receiving a Fax.

7.2 NaturalFax Device Class

A TAPI device class is a group of related physical devices or device drivers through which applications send and receive the information or data that makes up a Windows function. Every device class has a name that uniquely identifies the class, and provides information about the programming interface and commands that can be used to open and communicate with the devices in that class.

TAPI associates devices from one or more device classes to each line or phone device. In NMS TAPI, you access the NMS fax device by retrieving the device identifier using the lineGetID function. You supply the device class name, and the function returns the device identifier that you need to open and access the device.

NMS TAPI defines a new TAPI device class with the name nms/fax.

7.3 Programming NaturalFax for TAPI

A NaturalFax for TAPI application uses Microsoft TAPI functions to perform application initialization, tear down, and call control. It also uses NaturalFax for TAPI functions to manage fax sessions and related tasks. A fax session begins when a transmit or receive operation is initiated, and ends when the application receives the corresponding NaturalFax for TAPI DONE event.

A document queue contains a list of one or more document files (the document files must be in TIFF-F format). NaturalFax for TAPI functions can operate only on document queues, not on individual files. Unless you are using the assisted functions, you must use a document queue for any fax operation, even to transmit or receive a single document.

7.4 Handling Events

An event object must be created to receive event and error information. When you create an event object, you select either automatic or manual event handling. NaturalFax for TAPI requires automatic event handling.

7.5 Working with Document Queues

A document queue contains a list of one or more document files (the document files must be in TIFF-F format). NaturalFax for TAPI has two types of document queues: send queues and receive queues. Use send queues to transmit documents, and receive queues to receive documents.

A NaturalFax for TAPI application may have multiple send and receive queues.

7.5.1 Building a Document Queue

To create a new document queue, call faxCreateQueue. It returns a queue handle that uniquely identifies the queue. When you call faxCreateQueue, one of its arguments determines which kind of queue is created, send or receive.

After creating a send queue, use faxEnqueueDoc to add document files to the queue. Only files that already exist can be added to a send queue. The same file can be placed in multiple send queues simultaneously.

NaturalFax for TAPI sends each enqueued file as a separate message. Refer to the NaturalFax Developer's Reference Manual for detailed information about T.30 messages. For example, if you enqueue a three page file and a five page file, the remote fax machine will receive a three page message followed by a five page message. NaturalFax for TAPI will not send both files in a single eight page message.

Each document to be received must have an entry in the receive queue. When adding files using faxEnqueueDoc, the receive name cannot be NULL and the file must not yet exist.

NaturalFax for TAPI receives each multiple page message into a single file. The next document in the queue is used only if the remote fax machine sends a new message. This method of file management is specific to computer-based fax applications.

7.6 Transmitting and Receiving Faxes

Transmitting or receiving document queues constitutes an active fax session. A fax session can include the polling of a remote fax terminal or responding to a poll request from a remote fax terminal.

Once a document queue has been transmitted or received, the queue can be reset. Each page in a document in a send queue is flagged as sent when it has been successfully transmitted.

Note: You must continue processing events during an active fax session. Make sure that file I/O intensive operations, such as TIFF-F format verification, do not interfere with the handling of events and cause the fax session to time out. Events must be processed within three seconds.

7.6.1 Transmitting Faxes

Use faxSendFax to transmit all documents in a specified send queue. You can track which documents are successfully sent by monitoring events during transmission.

To end a fax session, NaturalFax for TAPI typically transmits a DCN (disconnect) frame to the remote fax terminal, and sends a FAXMSG_SESSION_DONE event to the application. The application can release the call as soon as it receives the FAXMSG_SESSION_DONE event; it does not need to wait for a response from the remote fax terminal. The application must use NMS TAPI functions to release the call after the DONE event is received.

It is also possible to transmit a procedure interrupt request (PRI) frame to the receiving fax terminal after completing a send operation. The PRI frame requests that the receiving fax terminal permit an operator action such as picking up the handset for voice. See faxSendFax for more details about sending PRI requests.

7.6.2 Receiving Faxes

An application must create a receive queue before it can call faxReceiveFax and receive a queue of documents. The receive queue cannot be empty; it must contain one or more file names of nonexistent files. The files must not exist when the receive queue is created, or at the time faxReceiveFax is invoked.

NaturalFax for TAPI will store each fax document received in a separate file, using the list of file names specified by the receive queue. If the sending fax terminal indicates that it is starting a new document and NaturalFax for TAPI has already used all available empty file names in the receive queue, faxReceiveFax ends with a FAXMSG_SESSION_DONE event with reason code FAXERR_NO_MORE_DOCUMENTS.

7.6.3 Polling the Called Fax Terminal

The fax polling operation enables the called fax terminal to send a queue of documents to the calling fax terminal. A caller can send any number of documents in a single queue and then poll the remote fax terminal. All documents in the send queue are transmitted before the called fax terminal can be polled.

To request polling, call faxReceiveFax with a non-NULL hReceiveQueue argument. Since the calling fax terminal will be receiving faxes, it must have a receive queue ready to accept the received document files.

The hReceiveQueue argument controls polling. A call to faxSendFax with a NULL hSendQueue and a non-NULL hReceiveQueue initiates a fax session that polls the called fax terminal without first transmitting any documents.

Figure 4 shows the exchanges between the application, the APIs, the hardware, and the remote fax terminal as an application transmits a fax, and then receives the fax for which it sent a poll request:

Figure 4. Polling the Remote Receiver (one page document)

7.6.4 Answering a Poll Request

To enable polling from the receiving fax terminal, make sure that pollingenabled is set to NFX_YES in FAX_RECEIVE_PARMS. The application is notified of a poll request when it receives a FAXMSG_POLLED event. Even with polling enabled, the application must decide if it will answer a poll request and prepare a send queue, or use a prepared send queue of documents.

An application uses faxAnswerFaxPoll to transmit its send queue in response to a poll request, rather than faxSendFax. faxAnswerFaxPoll must be called within three seconds of the receipt of a FAXMSG_POLLED event. If the application does not respond to the poll within three seconds, it receives FAXMSG_SESSION_DONE. Alternatively, faxStopSession may be called to refuse the poll request from the remote fax terminal.

If polling is not enabled, the FAXMSG_POLLED event is not generated (even if a poll request is made by the remote transmitter) and the fax session terminates.

Figure 5 shows NaturalFax for TAPI receiving a document and then transmitting a document in response to a poll:

Figure 5. Responding to the Remote Transmitter's Poll (one page document)

7.6.5 Resetting a Document Queue

Once a document queue has been transmitted or received, it can be reset using faxResetQueue.

Each page in a document is flagged as sent when it has been successfully transmitted. When a send queue is reset, the flags for the component documents of each page are reset to unsent.

You can choose how to use document queues. One scenario is to use one document queue per fax operation. For a fax broadcast application, you can use one send queue per broadcast session and continue to reset the queue and resend its contents multiple times.

Resetting a receive queue changes the queue type to a send queue with all the pages flagged as unsent. This use is typical of a fax store-and-forward application.

Note: Once a receive queue is changed to a send queue, it cannot be changed back to a receive queue.

7.6.6 Image Conversion During Fax Transmission

NaturalFax for TAPI uses the parameters from FAX_TRANSMIT_PARMS and the remote fax terminal's capabilities to determine the image format used during a fax transmission.

The first step in determining the final transmission format is based on the capabilities of the transmitting and receiving fax terminals. The remote receiver announces its capabilities in the DIS frame. NaturalFax for TAPI uses the image format parameters in the FAX_TRANSMIT_PARMS structure and the receiver's capabilities to choose the initial transmission format. The initial transmission format is set to the FAX_TRANSMIT_PARMS value if the remote receiver is capable of supporting it; otherwise, the nearest value supported by the receiver is chosen.

The next step in determining the transmission format is based on the value of OTFmode in FAX_TRANSMIT_PARMS. The format of the stored file is compared with the initial transmission format. Conversion takes place according to the following criteria:

If OTFmode is set to:	And the stored file format requires...	Then...	Image Conversion
NFX_OTF_NEVER	Capabilities less than or equal to the initial transmission format	The stored image format is selected as the final transmission format.	None.
NFX_OTF_NEVER	More advanced capabilities than can be provided by the initial transmission format	The fax session fails, and NaturalFax for TAPI returns FAXMSG_SESSION_DONE with the error FAXMSG_CONVERSION_ REQUIRED. No file is sent, since the system cannot satisfy the needs of the receiver without performing a conversion.	None.
NFX_OTF_ONLY_IF_FAIL	Capabilities less than or equal to the initial transmission format	The stored file format is selected as the final transmission format.	None.
NFX_OTF_ONLY_IF_FAIL	More advanced capabilities than can be provided by the initial transmission format	The file is converted to match the initial transmission format, which will also be the final transmission format.	On-the-fly image conversion.
NFX_OTF_ALWAYS	Encoding format characteristics specified by the initial transmission format. If the stored file format does not match the initial transmission format, it will be converted	There will only be a conversion for resolution and page width if it is necessary to support a lesser transmission capability.	On-the-fly image conversion, if required.

Once the final transmission format is determined, it is sent back to the receiver in the DCS frame. The application can retrieve the final transmission format by interrogating the FAX_DOC_STATUS and FAX_SESSION_STATUS data structures.

In general, an application should use the best formatting that the receiving fax machine can support. Set FAX_TRANSMIT_PARMS to NFX_ENCODE_MMR, NFX_RESOLUTION_SUPER_HIGH, and NFX_PAGE_WIDTH_A3 to use the best capabilities of the receiving fax machine.

OTFmode can be set to NFX_OTF_ONLY_IF_FAIL to minimize the host execution time, or to NFX_OTF_ALWAYS to minimize transmission time. Checking and replacement of bad lines is performed when OTFmode is set to NFX_OTF_ONLY_IF_FAIL or NFX_OTF_ALWAYS.

Figure 6 illustrates the image format decision process during fax transmission:

Figure 6. Image Conversion Decision When Transmitting a Fax

7.6.7 Image Conversion During Fax Reception

NaturalFax for TAPI uses the parameters from FAX_RECEIVE_PARMS and the remote fax terminal's capabilities to determine the image format stored during a fax receive operation.

When NaturalFax acts as the receiving fax terminal, it sends the image format values from FAX_RECEIVE_PARMS to the remote transmitter in a DIS frame to announce the receiver's capabilities to the transmitter. The transmitter sends back a DCS frame with the final transmission format. The remote transmitter controls the choice of the final transmission format.

Once the final transmission format is determined, the application uses the values from FAX_DOC_PARMS and the value for OTFmode in FAX_RECEIVE_PARMS to determine how the incoming image data is stored. Conversion only takes place if OTFmode is set to NFX_OTF_ALWAYS. Otherwise, the file is stored in the format received.

If OTFmode is set to NFX_OTF_ALWAYS, the FAX_DOC_PARMS values for the document determine the final storage format. A conversion from lower to higher resolution, and from narrower to wider pages will be performed if specified. Using NFX_OTF_ALWAYS is appropriate when your application requires a specific image format, and there are sufficient host CPU resources to support on-the-fly conversion.

To use the minimum host CPU resources when receiving a fax, accept the highest quality the sender can provide and save the image directly to a file without performing conversion. This can be accomplished by using NXF_ENCODE_MMR, NFX_RESOLUTION_SUPER_HIGH, NFX_PAGE_WIDTH_A3, and NFX_OTF_NEVER in FAX_RECEIVE_PARMS.

The NaturalFax for TAPI receiver checks and replaces bad lines according to the value of badlineaction in FAX_RECEIVE_PARMS regardless of the value of OTFmode.

To retrieve the final storage format after the document is received, examine the FAX_DOC_STATUS or FAX_SESSION_STATUS structures.

Figure 7 illustrates how the stored image format is selected during a fax receive operation.

Figure 7. Image Conversion Decision When Receiving a Fax

7.7 Monitoring Fax Session Status

An application can monitor the progress of a fax session actively, by explicitly querying the status, and passively, by monitoring the NaturalFax events on a specified Natural Access context.

When an application receives an error as part of an event, it can decide to continue sending or receiving the remaining documents in the queue, or to abort the fax session with faxStopSession.

Use faxGetSessionStatus to obtain a snapshot of the status of the current fax session. This function fills in an FAX_SESSION_STATUS structure.

To retrieve information about a specific document, call faxGetDocStatus. This function fills in a FAX_DOC_STATUS structure.

Refer to Appendix C for a complete listing of NaturalFax errors, Appendix D for details about the status data structures, and Appendix E for a complete listing of NaturalFax events.

7.8 Requesting Fax Session Status

An application can monitor the progress of a fax session actively, by calling faxGetSessionStatus, or through normal processing of events.

When an application receives an error as part of an event, it can decide whether to continue sending or receiving the remaining documents in the queue, or to abort the fax session with faxStopSession.

Use faxGetSessionStatus to obtain a snapshot of the status of the current fax session. This function fills in a FAX_SESSION_STATUS structure.

To retrieve information about a specific document, call faxGetDocStatus. This function fills in a FAX_DOC_STATUS structure.

7.8.1 Error Handling During a Fax Session

During an active fax session (while sending or receiving a fax), it is important to monitor all events. Events can provide necessary information about error conditions, enabling the application to respond appropriately.

When an event signifies that an error has occurred, use faxGetMessage to see what the error is. It is then up to your application to decide how to respond to the error. For information about the meaning of errors returned in events, refer to
Appendix E - NaturalFax for TAPI Events.

7.8.2 Tracing NaturalFax for TAPI Applications

Tracing for NaturalFax for TAPI is available using Natural Access. To use Natural Access tracing, ctdaemon must be running.

The NFX service logs internal trace information to ctdaemon according to the trace mask setting. The following trace masks are available for fax:

Trace Mask	Description
0x000C00	Logs information relating to T.30 protocol.
0x000F00	Logs all available fax information.

Refer to the Natural Access Developer's Reference Manual for information about Natural Access trace masks.

Any fax errors and events in the trace file will appear with NFX prefixes, instead of FAX, because the translation of NaturalFax functions to NaturalFax for TAPI are on the TAPI side only.

Note: ctdaemon tracing is not available in Windows 2000.

7.9 Terminating and Shutting Down

After a fax session has completed, the application must release the call and tear down or reset any document queues. The application must also release the call after a completed fax session.

A normal fax session ends when the transmitter sends the DCN (disconnect) frame, which signals the remote fax terminal to disconnect. Some fax terminals may disconnect the call before they receive or transmit the DCN frame. Under these conditions, the FAXMSG_SESSION_DONE event is returned with reason code CTA_REASON_RELEASED or CTA_REASON_FINISHED. Refer to faxReceiveFax for more details.

7.9.1 Tearing Down a Document Queue

When your application is done sending and receiving faxes, it should destroy the document queues that it created. Call faxDestroyQueue to destroy a document queue.

7.10 Example: Sending a Fax

The following example code demonstrates how to send a fax and wait for completion:

void SendFaxDocAndWait( HCALL hCall, LPCTSTR szFileName, 
                    FAX_DOC_PARMS *fparms, FAX_TRANSMIT_PARMS *tparms )
{
    UINT uDeviceID;
    HFAX hFax;
    FAX_QUEUE_HANDLE hQueue;
    HANDLE hFaxEvent;
    FAXMESSAGE fmsg;

    /* Get handle for the fax device                                */
    faxGetID( hCall, &uDeviceID );

    /* Open the fax device                                           */
    faxOpen( &hFax, uDeviceID, (DWORD) &hFaxEvent, (DWORD) 0, \
   FXO_EVENT );

    /* create a transmit queue, enqueue a document, and fax it.      */
    faxCreateQueue( hFax, FAX_DOC_TRANSMIT, &hQueue );

    faxEnqueueDoc( hFax, hQueue, szFileName, fparms, &dwDocNumber );

    faxSendFax( hFax, hQueue, tparms, 0, 0 );

    /* Wait for the fax to be sent                                   */
    do
    {
        DWORD dwEvent = WaitForSingleObject( hFaxEvent, INFINITE );

        if ( dwEvent != WAIT_OBJECT_0 )
            break;

        faxGetMessage( hFax, &fmsg );
       
    }
    while( fmsg.hQueue != hQueue || fmsg.dwMsg != FAXMSG_SESSION_COMPLETED )
    
  /* When the fax is done, destroy the queue and release the handle */
    

    faxDestroyQueue( hFax, hQueue );

    faxClose( hFax );
}

7.11 Example: Receiving a Fax

The following code example shows how to receive a fax using the assisted function:

void ReceiveFaxDocAndWait( HCALL hCall, LPCSTR szFileName, FAX_DOC_PARMS* fparms, FAX_RECEIVE_PARMS* rparms )
{
  UINT uDeviceID;
  HFAX hFax;
  FAX_QUEUE_HANDLE hQueue;
  HANDLE hFaxEvent;
  FAXMESSAGE fmsg;
 
  /* Get a handle to the fax device */
  faxGetID( hCall, &uDeviceID );
 
  /* Open fax device */
  faxOpen( &hFax, uDeviceID, (DWORD) &hFaxEvent, (DWORD) 0, FXO_EVENT );

  /* Create receiving queue, add document filename to the queue, and start receiving */
  faxCreateQueue(  hFax, FAX_DOC_RECEIVE, &hQueue );

  faxEnqueueDoc( hFax, hQueue, szFileName, fparms, &dwDocNumber );

  faxReceiveFax( hFax, hQueue, rparms, 0, 0 );

  /* wait for the completion */
  do
 {
   DWORD dwEvent = WaitForSingleObject( hFaxEvent, INFINITE );

   if ( dwEvent != WAIT_OBJECT_0 )
   break;

   faxGetMessage( hFax, &fmsg );
 }
  while ( ! ( fmsg.hQueue == hQueue && fmsg.dwMsg == FAXMSG_SESSION_COMPLETED );

  /* Destroy the queue and release the handle */
  faxDestroyQueue( hFax, hQueue );

  faxClose( hFax );
}