3.1 A Typical Fax Application

3.2 A Typical Fax and Voice Application

3.3 Setting Up the Natural Access Environment

3.3.1 Initializing NaturalFax

3.3.2 Creating Event Queues and Contexts

3.3.3 Opening Services

3.4 Establishing a Call

3.4.1 Placing a Call

3.4.2 Receiving a Call

3.5 Using Document Queues

3.5.1 Building a Document Queue

3.6 Transmitting and Receiving Faxes

3.6.1 Transmitting Faxes

3.6.2 Receiving Faxes

3.6.3 Polling the Called Fax Terminal

3.6.4 Answering a Poll Request

3.6.5 Resetting a Document Queue

3.7 Performing Image Conversion

3.7.1 Performing Offline Image Conversion

3.7.2 Performing Online Image Conversion

Image Conversion During Fax Transmission

Image Conversion During Fax Reception

Generating TIFF-S Files on Receive

3.8 Monitoring Fax Session Status

3.8.1 Tracing NaturalFax Applications

3.8.2 Error Handling During a Fax Session

3.9 Terminating and Shutting Down

3.9.1 Tearing Down or Resetting a Document Queue

3.10 Closing Natural Access Services

3.1 A Typical Fax Application

Figure 2 shows the functions involved in a typical application that can transmit or receive faxes. NaturalFax invokes functions for transmitting and receiving a fax when a call is in the connected state. The document queue can be destroyed as soon as the fax session is complete, or after the call is disconnected.

Note: If you are using QX 2000 boards, use QDIMGR instead of ADIMGR.

Figure 2. Functions for a Typical Fax Application

3.2 A Typical Fax and Voice Application

Figure 3 depicts a typical fax and voice application. In this application, the document queue is created when the call is in the connected state.

Note: If you are using QX 2000 boards, use QDIMGR instead of ADIMGR.

Figure 3. Functions for a Typical Fax and Voice Application

3.3 Setting Up the Natural Access Environment

Set up the Natural Access environment before calling functions from the NaturalFax library. Perform the following steps to set up the Natural Access environment:

1. Initialize NaturalFax.

2. Create event queues and contexts.

3. Open services on each context.

The following sections briefly describe these steps. For detailed information on setting up the Natural Access environment, refer to the Natural Access Developer's Reference Manual.

3.3.1 Initializing NaturalFax

Use ctaInitialize to initialize NaturalFax and register the services available to the application. If ctdaemon is running, all services defined in cta.cfg are automatically registered when you invoke ctaInitialize.

If ctdaemon is not running, you must explicitly define the services and service managers in the call to ctaInitialize, as shown in the following code sample:

static DWORD initialize_base (void)
{
  CTA_SERVICE_NAME init_services [] =
    {
   { "ADI", "ADIMGR" },
   { "FXM", "ADIMGR" },
/*   { "ADI", "QDIMGR" },     for QX 2000 boards        */
/*   { "FXM", "QDIMGR" },     for QX 2000 boards        */
   { "FAX", "FAXMGR" },
   { "NFX", "NFXMGR" },
    };
    CTA_INIT_PARMS init_parms =
  {
   sizeof (CTA_INIT_PARMS), 
  };
    DWORD status;
    static int initialized = 0;
     if (initialized)
   return SUCCESS;
  status = ctaInitialize (init_services,
        sizeof init_services / sizeof init_services [0],
        & init_parms);
    if (status != SUCCESS)
   show_error (NULL_CTAHD, status, "CT Access initialization
    failed");
    else
   initialized = 1;
    return status;
}

For a complete list of NaturalFax services and service managers, refer to Section 2.3.1, NaturalFax Services.

3.3.2 Creating Event Queues and Contexts

After initializing NaturalFax, create the event queues and the contexts.

1. Create one or more event queues by calling ctaCreateQueue and specifying the service managers to attach to each queue. Attaching or binding a service manager to a queue makes that service manager available to the queue. A NaturalFax application uses the following service managers:

   Service Manager	Service
   ADIMGR (QDIMGR for QX 2000 boards)	ADI
   ADIMGR (QDIMGR for QX 2000 boards)	FXM
   NFXMGR	NFX
   FAXMGR	FAX

2. Create a context by calling ctaCreateContext, passing the queue handle (ctaqueuehd) returned from ctaCreateQueue. All events for services on the context are received in the specified event queue.
   ctaCreateContext returns a context handle (ctahd). The application supplies the context handle when invoking NaturalFax functions. Events communicated back to the application are also associated with the context.

Refer to the Natural Access Developer's Reference Manual for details on the programming models created by the use of Natural Access contexts and queues.

3.3.3 Opening Services

Opening a service on a context creates a service instance that defines a service and its associated resources (for example, MVIP board, stream, and timeslot). The context is a bound collection of service instances. A fax application usually opens the NFX, FAX, FXM, and ADI services on each individual context. Each context must specify the same board and MVIP address for the ADI and FXM service instances bound to it.

To open services on a context, call ctaOpenServices and pass a context handle and a list of service descriptor structures, one for each service. The service descriptor structure, CTA_SERVICE_DESC, contains the CTA_SERVICE_NAME, CTA_SERVICE_ADDR, CTA_SERVICE_ARGS, and CTA_MVIP_ADDR substructures, which provide the name of the service, its service manager, and service-specific arguments.

An application must open the ADI service to place or receive calls. The application must assign hardware resources to the service by filling in the board, bus, stream, timeslot, and mode fields in the CTA_MVIP_ADDR substructure. To ensure that the context is able to transmit and receive voice and signaling data, use ADI_FULL_DUPLEX mode.

The Fax Manager (FXM) service must use service-specific arguments to identify its hardware resources, because it provides the hardware interface for the NaturalFax service. When an application opens the FXM service, it must fill in the board, bus, stream, timeslot, and mode fields in the CTA_MVIP_ADDR substructure.

The NaturalFax (NFX) and Fax (FAX) services do not require any service-specific arguments. The NFX and FAX services use the same hardware resources specified by the FXM service opened on the same context.

The following code sample demonstrates creating a context and opening the NFX, FAX, FXM, and ADI services:

static DWORD create_context (CTAQUEUEHD queue,
            DWORD      board,
            DWORD      stream,
            DWORD      timeslot,
            DWORD      closure,
            char     * contextname,
            CTAHD    * contextptr)
{
    DWORD status;
    CTA_SERVICE_DESC services [4];
    DWORD service_count = 0;
    CTA_EVENT event;

    status = ctaCreateContext (queue, closure, contextname, contextptr);
    if (status != SUCCESS)
    {
   show_error (NULL_CTAHD, status, "CT Access context creation
   failed");
   return status;
    }
  /*
     * Now that we have a valid context, we can use
   * ctaGetText to get proper error messages.
     */

memset (& services, 0, sizeof services);

  services[service_count].name.svcname      = "ADI";
  services[service_count].name.svcmgrname   = "ADIMGR";
 /* for QX 2000 boards, use QDIMGR instead of ADIMGR                  */
  services[service_count].mvipaddr.board    = board;
  services[service_count].mvipaddr.stream   = stream;
  services[service_count].mvipaddr.timeslot = timeslot;
  services[service_count].mvipaddr.mode     = ADI_FULL_DUPLEX;
  service_count += 1;

  services[service_count].name.svcname      = "FXM";
  services[service_count].name.svcmgrname   = "ADIMGR";
 /* for QX 2000 boards, use QDIMGR instead of ADIMGR                  */
  services[service_count].mvipaddr.board    = board;
  services[service_count].mvipaddr.stream   = stream;
  services[service_count].mvipaddr.timeslot = timeslot;
  services[service_count].mvipaddr.mode     = ADI_FULL_DUPLEX;
  service_count += 1;



 /*
  * Specific MVIP_ADDR field assignments for the FXM, FAX, and NFX 
  * services are ignored; these services use the MVIP_ADDR data that was 
  * passed to the ADI service.
*/

  services[service_count].name.svcname      = "FAX";
  services[service_count].name.svcmgrname   = "FAXMGR";
  services[service_count].mvipaddr.board    = board;
  services[service_count].mvipaddr.stream   = stream;
  services[service_count].mvipaddr.timeslot = timeslot;
  services[service_count].mvipaddr.mode     = ADI_FULL_DUPLEX;
  service_count += 1;


  services[service_count].name.svcname      = "NFX";
  services[service_count].name.svcmgrname   = "NFXMGR";
  services[service_count].mvipaddr.board    = board;
  services[service_count].mvipaddr.stream   = stream;
  services[service_count].mvipaddr.timeslot = timeslot;
  services[service_count].mvipaddr.mode     = ADI_FULL_DUPLEX;
  service_count += 1;

  status = ctaOpenServices (* contextptr, services, service_count);
    if (status != SUCCESS)
    {
   show_error (* contextptr, status, "open services failed");
   return status;
    }

    /* Now we need to wait for the CTAEVN_OPEN_SERVICES_DONE event. */
    status = wait_event (queue, * contextptr, CTAEVN_OPEN_SERVICES_DONE,
        NULL, 0, & event);
    if (status != SUCCESS)
    {
   show_error (* contextptr, status, "open services failed");
   return status;
    }
    else if (event.value != CTA_REASON_FINISHED)
    {
   show_error (* contextptr, event.value, "open services done event");
   return event.value;
    }
    else
   return SUCCESS;
}

3.4 Establishing a Call

The process of establishing a call is specific to whether the application is acting as a calling fax terminal or as a called fax terminal. Use one or more call control functions from the ADI service to establish a call. Refer to the ADI Service Developer's Manual and the ADI Service Function Reference Manual for complete details on call control.

3.4.1 Placing a Call

Call progress analysis in the ADI service includes the capability to detect CED tones. A CED tone is a three second 2100 Hz tone indicating that a fax terminal has answered.

Enable CED tone detection when invoking adiStartCallProgress. The application generates an ADI service call progress event if it detects a CED tone. If no CED tone is detected, the application should provide a way to handle a call answered by a person or by a modem rather than by a fax machine.

3.4.2 Receiving a Call

The application invokes adiAnswerCall and adiStartToneDetector from the ADI service to answer an inbound call and detect CNG tones. The calling fax terminal sends a CNG tone, a 0.5 second 1100 Hz tone that indicates a fax terminal is calling.

If an application needs to handle both fax and human callers, it should start a special tone detector to detect CNG tones in conversation state. The application starts a fax session only if a CNG tone is detected. In a fax-only application, a fax session may be started as soon as the call is answered.

3.5 Using Document Queues

NaturalFax functions operate on document queues, not on individual files. Use a document queue for all fax operations, including transmitting or receiving single documents.

A document queue contains a list of one or more document files in TIFF-F or TIFF-S format. NaturalFax has two kinds of document queues: send queues and receive queues. Use send queues to transmit documents, and receive queues to receive documents.

Each document queue is linked to a specific context. Each context may have multiple send and receive queues.

3.5.1 Building a Document Queue

To create a new document queue, call nfxCreateQueue. This function returns a queue handle, which uniquely identifies the queue. When you call nfxCreateQueue, specify the type of queue to be created (send or receive).

After creating a send queue, use nfxEnqueueDoc 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 sends each enqueued file as a separate message (refer to Appendix D 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 receives a three page message followed by a five page message. NaturalFax will not send both files in a single eight page message.

Note: NaturalFax does not modify or delete any document files when sending. Only received document files can be modified.

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

NaturalFax 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.

3.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.

After a document queue is transmitted or received, the queue can be reset. Each page in a document in a send queue is flagged as sent when it is 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 or TIFF-S 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.

3.6.1 Transmitting Faxes

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

NaturalFax typically ends a fax session by transmitting a DCN (disconnect) frame to the remote fax terminal and sending an NFXEVN_SESSION_DONE event to the application. The application can release the call as soon as it receives the NFXEVN_SESSION_DONE event; it does not need to wait for a response from the remote fax terminal. The application must use ADI service functions to release the call after the DONE event is received.

You can also transmit a procedure interrupt request (PRI) frame to the receiving fax terminal after completing a send operation. PRI requests that the receiving fax terminal permit an operator action such as picking up the handset for voice. See nfxSendFax in Chapter 7 for more details about sending PRI requests.

3.6.2 Receiving Faxes

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

NaturalFax stores each fax document received in a separate file, using the list of file names specified by the NaturalFax receive queue. If the sending fax terminal indicates that it is starting a new document and NaturalFax has already used all available empty file names in the receive queue, the received document is appended to the last file in the receive queue. This could result in a TIFF file with unused image attributes.

3.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 may 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 nfxSendFax with a non-NULL receive_queue_handle argument. Since the calling fax terminal will be receiving faxes, it must have a receive queue ready to accept the received document files.

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

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

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

3.6.4 Answering a Poll Request

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

An application uses nfxAnswerFaxPoll to transmit its send queue in response to a poll request, rather than nfxSendFax. nfxAnswerFaxPoll must be called within three seconds of the receipt of NFXEVN_POLLED event. If the application does not respond to the poll within three seconds, it receives NFXEVN_SESSION_DONE. Alternatively, you can call nfxStopSession to refuse the poll request from the remote fax terminal.

If polling is not enabled, the NFXEVN_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 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)

3.6.5 Resetting a Document Queue

After a document queue is transmitted or received, reset it using nfxResetQueue.

Each page in a document is flagged as sent when it is successfully transmitted. Resetting a send queue resets the flags for each page of each of its component documents to unsent.

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.

3.7 Performing Image Conversion

You can convert a file's image characteristics offline before transmitting the fax, or online while transmitting and receiving a fax. Since image conversion consumes significant processor time, you may want to perform file conversions offline to conserve CPU resources for processing events during an active fax session.

3.7.1 Performing Offline Image Conversion

Use nfxConvertFileDirect to convert a file's image characteristics offline. Specify the input file, the output file, and the desired image characteristics. For detailed information about image format characteristics, refer to Chapter 5. Conversions of encoding type or page width do not affect image quality, but converting from a high to a lower resolution will affect image quality. Converting an image from a lower to a higher resolution is not recommended, since the image cannot be improved, and the resulting file will be larger than the original.

NaturalFax supports TIFF-F files with different image formats on its pages by converting the format of all pages in the file to the format of the first page. If the file requires an image format other than that of the first page, use nfxConvertFileDirect to convert all the pages in a file to a specific image format. You can also use nfxSplitFile to split the original file into multiple files, each of which contains one or more pages that have the same image format. Splitting the file does not alter the image format of any of its pages. You may want to use nfxSplitFile to preserve the original image quality if a document has different resolutions on different pages.

Use nfxMergeFile to combine multiple pages stored in separate files into a single document for transmission. Merging the file does not alter the image format of any of its pages.

To verify that a document is in the correct format for transmission by NaturalFax, use nfxCheckTIFF.

File format conversion is an I/O intensive operation. File I/O intensive operations, such as TIFF-F or TIFF-S conversion or verification, must not interfere with Natural Access event processing. Delays in application event processing can cause the fax session to time out. Applications must process events within three seconds of receipt. An application must continue processing events during an active fax session.

3.7.2 Performing Online Image Conversion

NaturalFax's receive and transmit parameter structures, NFX_RECEIVE_PARMS and NFX_TRANSMIT_PARMS, contain image format parameters for encoding, resolution, and page width. These parameters are used with the OTFmode (on-the-fly) parameter to determine the format of the image being transmitted or received. For detailed information about image format characteristics, refer to Chapter 5.

See NFX_TRANSMIT_PARMS or NFX_RECEIVE_PARMS for valid OTFmode parameters. When NaturalFax is receiving a fax, NFX_DOC_PARMS contains the image format parameters that determine how the image will be stored.

NFX_RECEIVE_PARMS contains the badlineaction parameter, which controls how the receiving fax terminal manages bad lines of data. See NFX_RECEIVE_PARMS for valid badlineaction parameters.

Image Conversion During Fax Transmission

This section describes how NaturalFax uses the parameters from NFX_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 uses the image format parameters in the NFX_TRANSMIT_PARMS structure and the receiver's capabilities to choose the initial transmission format. The initial transmission format is set to the NFX_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 NFX_TRANSMIT_PARMS. The format of the stored file is compared with the initial transmission format, and conversion takes place according to the following criteria:

• If OTFmode is set to NFX_OTF_NEVER, and the stored file format requires capabilities less than or equal to the initial transmission format, the stored image format is selected as the final transmission format. No image conversion is performed.

• If OTFmode is set to NFX_OTF_NEVER, and the stored file format requires more advanced capabilities than can be provided by the initial transmission format, the fax session fails, and NaturalFax returns NFXEVN_SESSION_DONE with the error NFXERR_CONVERSION_REQUIRED. No file is sent, since the system cannot satisfy the needs of the receiver without performing a conversion. No image conversion is performed.

• If OTFmode is set to NFX_OTF_ONLY_IF_FAIL, and the stored file format requires capabilities less than or equal to the initial transmission format, the stored file format is selected as the final transmission format. No image conversion is performed.

• If OTFmode is set to NFX_OTF_ONLY_IF_FAIL, and the stored file format requires more advanced capabilities than can be provided by the initial transmission format, the file is converted to match the initial transmission format. The initial transmission format is selected as the final transmission format. NaturalFax performs on-the-fly image conversion.

• If OTFmode is set to NFX_OTF_ALWAYS, the stored file format will always use the 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. NaturalFax performs on-the-fly image conversion if required.

After the decision is made, the final transmission format is sent back to the receiver in the DCS frame. The application can retrieve the final transmission format by interrogating the NFX_DOC_STATUS and NFX_FAX_STATUS data structures.

For the best image quality, an application should use the best formatting that the receiving fax machine can support. Set NFX_TRANSMIT_PARMS to use 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

Image Conversion During Fax Reception

This section describes how NaturalFax uses the parameters from NFX_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 NFX_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 NFX_DOC_PARMS and the value for OTFmode in NFX_RECEIVE_PARMS to determine how the incoming image data is actually stored. Conversion will only take 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 NFX_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 that 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 NFX_RECEIVE_PARMS.

To retrieve the final storage format after the document is received, examine the NFX_DOC_STATUS or NFX_FAX_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

Generating TIFF-S Files on Receive

When receiving an image to be used in future T.37 operations, the application can choose to

• Ensure that the image is transmitted in TIFF-S format by advertising only TIFF-S compatible capabilities, which minimizes CPU resources,
  or

• Receive the image in the fastest means possible, and use the OTF mode to convert the image to TIFF-S format after reception.

The following table summarizes how the document will be transmitted, as determined by the OTF mode, when NFX_RECEIVE_PARMS.ENCODING = TIFF_S.

OTF Mode	Advertised Parameters
NFX_OTF_NEVER	1D encoding Low resolution A4 page width
NFX_OTF_ALWAYS	MMR encoding (if ECM is enabled) or MR (if ECM is disabled) Low resolution A4 page width

3.8 Monitoring Fax Session Status

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

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 nfxStopSession.

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

To retrieve information about a specific document, call nfxGetDocStatus. This function fills in an NFX_DOC_STATUS structure.

For more information about...	Refer to...
NaturalFax errors or events	Appendix A
Modem metrics	Appendix E

3.8.1 Tracing NaturalFax Applications

Tracing for NaturalFax is available using Natural Access tracing functions. To use Natural Access tracing

• ctdaemon must be running.

• ctdaemon must launch a trace thread. See the Natural Access Developer's Reference Manual for more information on ctdaemon.

• The application must enable tracing in the call to ctaInitialize.
  If the application enables tracing in ctaInitialize and ctdaemon is not running, ctaInitialize will fail. The application must unset the trace mask in CTA_INIT_PARMS to disable tracing, and invoke ctaInitialize again.

• The application must initiate tracing by calling ctaSetTraceLevel with a specific context, the NFX service name, and a mask indicating what to trace.

• The NFX service must be specified in cta.cfg.

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

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

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

The following code demonstrates setting the trace level:

ctaSetTraceLevel( ctahd, "NFX", NFX_TRACE_T30 | CTA_TRACEMASK_ALL_EVENTS );

3.8.2 Error Handling During a Fax Session

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

The following ADI service error may be returned during an active fax session:

ADI Error Name	Description
ADIEVN_BOARD_ERROR	An unexpected error has occurred on your board. Contact NMS with the specific error information. This should be considered a fatal error on this channel.

For information on NaturalFax errors returned as part of a NaturalFax DONE event, refer to Appendix A. For information on Natural Access errors returned as part of a NaturalFax DONE event, refer to the Natural Access Developer's Reference Manual.

3.9 Terminating and Shutting Down

After a fax session completes, the application must release the call and tear down or reset any document queues.

A normal fax session ends with the transmitter sending the DCN (disconnect) frame, signaling 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 NaturalFax application may receive an ADIEVN_CALL_DISCONNECTED event before it receives the NFXEVN_SESSION_DONE event.

The application should wait for the NFXEVN_SESSION_DONE event, and then release the call as usual. The NFXEVN_SESSION_DONE event will contain a reason of CTA_REASON_RELEASED or CTA_REASON_FINISHED. Refer to Chapter 7, nfxReceiveFax, for more details.

Using NaturalFax with ADI call control or with ISDN Natural Call Control Interface (Layer 4) or using NaturalFax with ISDN Messaging API (Layer 3), the application responds differently to each of the three ways that a fax session terminates.

Termination	NaturalFax with ADI or ISDN Natural Call Control Interface
Normal Termination	· Application receives NFXEVN_SESSION_DONE with reason code CTA_REASON_FINISHED. · Application issues adiReleaseCall. Note: ADIEVN_CALL_DISCONNECTED can be ignored.
Abnormal Termination	· Application receives NFXEVN_SESSION_DONE with reason code CTA_REASON_RELEASED (or other error). · Application issues adiReleaseCall. Note: ADIEVN_CALL_DISCONNECTED can be ignored.
Application-initiated Termination	· Application calls nfxStopSession. · Application waits for NFXEVN_SESSION_DONE (with reason code CTA_REASON_STOPPED). · Application calls adiReleaseCall.

Termination	NaturalFax with ISDN Messaging API
Normal Termination	· Application receives NFXEVN_SESSION_DONE with reason code CTA_REASON_FINISHED. · Application issues a clear request (ACU_CLEAR_RQ).
Abnormal Termination	There are two variations of abnormal termination. Example 1: · Application receives a clear indication (ACU_CLEAR_IN). · Application issues nfxStopSession. · Application waits for NFXEVN_SESSION_DONE. · Application issues a clear response (ACU_CLEAR_RS). Example 2: · Application receives a clear confirmation (ACU_CLEAR_CO). · Application issues nfxStopSession. · Application waits for NFXEVN_SESSION_DONE.
Application-initiated Termination	· Application calls nfxStopSession. · Application waits for NFXEVN_SESSION_DONE (with reason code CTA_REASON_STOPPED). · Application issues a clear request (ACU_CLEAR_RQ).

For information about releasing and terminating calls, see the ADI Service Developer's Manual, AG ISDN for Natural Call Control Developer's Manual, and AG ISDN Messaging API Developer's Reference Manual.

3.9.1 Tearing Down or Resetting a Document Queue

A NaturalFax application can initiate multiple fax sessions during its execution, either simultaneously or in a series, according to the programming model used. It can also reset a document queue and use it again in a subsequent fax session.

Call nfxDestroyQueue to destroy a document queue.

To use a document queue after it has been successfully transmitted or received, call nfxResetQueue. Resetting a send queue resets the flags for each page of each of its component documents from sent to unsent. Resetting a receive queue changes it to a send queue, with all its component documents flagged as unsent.

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

3.10 Closing Natural Access Services

Natural Access supports opening and closing services on a context as needed during an application's execution. An application can free system resources it no longer needs to optimize performance.

Use ctaCloseServices to close the NaturalFax services. ctaCloseServices destroys any open document queues associated with the service on the specified context. ctaCloseServices does not release the call, nor does it close the ADI service unless specified.