(Page 1 of 1 in this chapter)

Chapter 2

Developing NaturalFax Applications

2.1 Introduction
2.1.1 Preparing the Hardware Environment
2.2 Setting Up the CT Access Environment
2.2.1 Using CT Access Services With NaturalFax
2.2.2 Initializing CT Access Services
2.2.3 Creating Event Queues and CTA Contexts
2.2.4 Opening Services
2.3 Establishing a Call
2.3.1 Placing a Call
2.3.2 Receiving a Call
2.4 Working with Document Queues
2.4.1 Building a Document Queue
2.5 Transmitting and Receiving Faxes
2.5.1 Transmitting Faxes
2.5.2 Receiving Faxes
2.5.3 Polling the Called Fax Terminal
2.5.4 Answering a Poll Request
2.5.5 Resetting a Document Queue
2.6 Performing Offline Image Conversion
2.7 Performing Online Image Conversion
2.7.1 Image Conversion During Fax Transmission
2.7.2 Image Conversion During Fax Reception
2.8 Monitoring Fax Session Status
2.8.1 Tracing NaturalFax Applications
2.8.2 Error Handling During a Fax Session
2.9 Terminating and Shutting Down
2.9.1 Tearing Down or Resetting a Document Queue
2.10 Closing CT Access Services
2.11 Managing Fax Licenses

2.1 Introduction

A NaturalFax application uses CT Access functions to perform application initialization and teardown, performs call control with functions from CT Access' ADI service, and uses NaturalFax 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 DONE event.

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

NaturalFax provides functions to:

Figure 1 shows how the CT Access, ADI, and NaturalFax APIs are used in a basic NaturalFax application outline:

Figure 1. Fax Application Summary






2.1.1	 Preparing the Hardware Environment





You must initialize and load any AG board(s) before you can run a CT Access or NaturalFax application. Use the agmon utility to perform hardware configuration and initialization. For information about agmon, see the AG Runtime Configuration and Developer's Manual.


 






2.2	 Setting Up the CT Access Environment





Before you can call functions from the NaturalFax library, the application must initialize CT Access and open the NFX, FAX, FXM, and ADI services. To set up the application:


    


  1. Initialize CT Access for the process.
    

    

  2. Create one or more event queues.
    

    

  3. Create one or more CTA contexts and attach them to an event queue.
    

    

  4. Open services on each CTA context.
    







2.2.1	 Using CT Access Services With NaturalFax





There are four CT Access services and three CT Access service managers required to develop a complete fax application:





 





 This Service...



 with this Service Manager...



 Provides...




 NFX



 NFXMGR



 Access to the NaturalFax API 




 FAX



 FAXMGR



 Support for the fax protocol (ITU T.30)




 FXM



 ADIMGR



 Interface to telephony board hardware for sending or receiving faxes 




 ADI



 ADIMGR



  Call establishment functions


















An application must open the NFX service to use any NaturalFax API functions. 



In order to send or receive a fax, the application must also open the FAX and FXM services. The FAX service provides the ITU T.30 protocol support required internally by NFX. The FXM service provides a hardware independent interface for the FAX service by handling all interactions with the telephony board. 



The application uses one or more function calls from the ADI service call control functions to establish a call.


Note:  An application performing fax file image conversions (no fax transmission or reception) requires only the NFX service.


A fax application usually opens the NFX, FAX, FXM, and ADI services on each individual CTA context. Each CTA context must specify the same board and MVIP address for the ADI and FXM service instances bound to it. 



The NFX and FAX service instances bound to a CTA context use the hardware resources that were specified by the FXM service instance bound to the same CTA context.






2.2.2	 Initializing CT Access Services





You register services by specifying the service and service manager names in the call to ctaInitialize. Only the services initialized in the call to ctaInitialize can be opened by the application. The following code sample demonstrates CT Access initialization for a NaturalFax application:


static DWORD initialize_base (void)
{
  CTA_SERVICE_NAME init_services [] =
    {
   { "ADI", "ADIMGR" },
   { "FXM", "ADIMGR" },
   { "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;
}

 






2.2.3	 Creating Event Queues and CTA Contexts





After initializing CT Access, create the event queues and CTA contexts.



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 and services: 


  





 Service Manager



 Service




 ADIMGR



 ADI




 ADIMGR



 FXM




 NFXMGR



 NFX




 FAXMGR



 FAX
















Create a CTA context by calling ctaCreateContext, passing the queue handle (ctaqueuehd) returned from ctaCreateQueue. All events for services on the CTA context will be received in the specified event queue.



ctaCreateContext returns a CTA context handle (ctahd). The CTA context handle is supplied by the application when invoking NaturalFax functions. Events communicated back to the application are also associated with the CTA context.



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






2.2.4	 Opening Services





Opening a service on a CTA context creates a service instance, which defines a service and its associated resources (e.g., MVIP board, stream, and timeslot). The CTA context is a bound collection of service instances.



An application opens services on a CTA context by calling ctaOpenServices, passing a CTA 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 in order to place or receive calls. The application must assign hardware resources to the ADI service by filling in the board, bus, stream, timeslot, and mode fields in the CTA_MVIP_ADDR substructure when opening the ADI service. To ensure that the CTA context will be able to transmit and receive voice and signaling data, use ADI_FULL_DUPLEX mode. 



The Fax Manager service (FXM) service must use service-specific arguments to identify its hardware resources, because it provides the hardware interface for the NaturalFax service. When it opens the FXM service, the application 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 CTA context. 


 



The following code excerpt demonstrates creating a CTA 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 CT Access 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";
    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";
    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;
}





2.3	 Establishing a Call





The specific process of call establishment depends on whether the application is acting as a calling fax terminal or as a called fax terminal. Use one or more function calls from the ADI service call control functions 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.


 






2.3.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 which indicates that a fax terminal has answered.



Keep CED tone detection enabled when invoking adiStartCallProgress. An ADI service call progress event will appear if a CED tone is detected. 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.






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






2.4	 Working with Document Queues





NaturalFax functions can operate only on document queues, not on individual files. You must use a document queue for any fax operation, even when transmitting or receiving a single document.



A document queue contains a list of one or more document files (the document files must be in TIFF-F 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 CTA context. Each CTA context may have multiple send and receive queues.






2.4.1	 Building a Document Queue





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



After creating a send queue, use nfxEnqueueDoc to add document files to the queue. Only files that already exist may 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 G 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 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 are modified.


Each document to be received must have an entry in the receive queue. When adding files using nfxEnqueueDoc, the receive name may 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.


 






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





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



It is also possible to 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 6 for more details about sending PRI requests.


 






2.5.2	 Receiving Faxes





An application must create a receive queue before it can call nfxReceiveFax 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. The files must not exist at the time nfxReceiveFax is invoked.



NaturalFax will store 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 nfxReceiveFax operation ends with an NFXEVN_SESSION_DONE event that contains NFXERR_NO_MORE_DOCUMENTS.


 



Figure 2 depicts the functions involved in a typical application that can transmit or receive faxes. Note that the NaturalFax functions for transmitting and receiving a fax are invoked 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.


 



Figure 2.	 Functions for a Typical Fax 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.


 



Figure 3.	 Functions for a Typical Fax and Voice Application



 






2.5.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)






2.5.4	 Answering a Poll Request





To enable polling from the receiving fax terminal, make sure that pollingenabled is set 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, nfxStopSession may be called to refuse the poll request from the remote fax terminal. 



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






2.5.5	 Resetting a Document Queue





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



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



The application developer is free to 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.





2.6	 Performing Offline Image Conversion





You can convert a file's image characteristics offline, before transmitting the fax, with nfxConvertFileDirect. When you invoke nfxConvertFileDirect, specify the input file, the output file, and the desired image characteristics. For detailed information about image format characteristics, refer to Chapter 4.



Note that conversions of encoding type or page width do not affect image quality. 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.



The current release of NaturalFax requires a TIFF-F file to have the same image format for all of its pages. Use nfxConvertFileDirect to convert a file with different image formats on its pages to a file with a single image format for all of its pages, or 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.



Keep in mind that file format conversion is an I/O intensive operation. File I/O intensive operations, such as TIFF-F conversion or verification, must not interfere with CT 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. 






2.7	 Performing Online Image Conversion





Online (also known as on-the-fly) conversions take place while transmitting and receiving a fax. Since image conversion consumes significant processor time, you may want to perform file conversions offline using nfxConvertFileDirect in order to conserve CPU resources for processing events during an active fax session.



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, in conjunction with the OTFmode parameter, to determine the format of the image being transmitted or received. For detailed information about image format characteristics, refer to Chapter 4.


 



NFX_RECEIVE_PARMS and NFX_TRANSMIT_PARMS each contain an on-the-fly (OTF) conversion field, OTFmode, that controls when, and under what conditions, the application performs online image conversion. OTFmode can be set to any of the following values:


  





 Value



 Description




 NFX_OTF_NEVER



 Never convert on the fly.




 NFX_OTF_ONLY_IF_FAIL



 Convert only if the fax operation would fail otherwise.




 NFX_OTF_ALWAYS



 Always convert as directed by the image 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. The parameter can be set to any of the following values:


  





 Value



 Description




 NFX_BAD_LINE_ACTION_NONE



 Do not repair bad lines.




 NFX_BAD_LINE_ACTION_DROP



 Eliminate bad line.




 NFX_BAD_LINE_ACTION_REPT



 Repeat previous good line.




 NFX_BAD_LINE_ACTION_TICK



 Replace bad line with a blank line and add a tick mark in the margin.















 






2.7.1	 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:




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



In general, 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



 






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



The NaturalFax receiver checks and replaces bad lines according to the value of badlineaction in NFX_RECEIVE_PARMS, regardless of the value of OTFmode. 



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






2.8	 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 CTA context. 



When an application receives an error as part of an event, it can decide whether it continues sending or receiving the remaining documents in the queue or aborts 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.



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






2.8.1	 Tracing NaturalFax Applications





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




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




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


 



The following code demonstrates setting the trace level:


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





2.8.2	 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, which enables the application to respond appropriately.



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





 





 Event



 Description




 ADIEVN_BOARD_ERROR



 An unexpected error has occurred on your AG board. Contact NMS with the specific error information. This should be considered a fatal error on this channel.


















The following NaturalFax errors may be returned as part of a NaturalFax DONE event:





 





 Error Name



 Description




 NFXERR_BAD_FILE_FORMAT 



 The specified file is not in TIFF-F format. 




 NFXERR_BAD_PAGE_SIZE



 Unsupported page size.




 NFXERR_BUFFER_UNDERRUN



 On fax transmit, buffers of image data have not been provided in time. Check your host computer loading to be sure events and disk I/O are being processed in a timely fashion.




 NFXERR_CARRIER_LOST



 The received signal has fallen below the level specified by NFX_RECEIVE_PARMS.threshold, and the fax session has been terminated.




 NFXERR_CONNECT_FAILED



 The called fax machine was not detected. Check that the number you are dialing is connected to a fax machine.




 NFXERR_CONVERSION_REQUIRED



 Cannot transmit file because there is a mismatch between the stored file format and the receiving fax terminal's capabilities and on-the-fly conversion has been disabled (otfmode in the receive or transmit parameters is set to NFX_OTF_NEVER).




 NFXERR_FAX_SERVICE



 A fatal error occurred in the FAX service. Contact NMS Developer Support.




 NFXERR_FXM_SERVICE



 A fatal error occurred in the FXM service. Contact NMS Developer Support.




 NFXERR_INCOMPATIBLE_RECEIVER



 The application has disabled on-the-fly conversion and the receiver can not handle the specified image format.




 NFXERR_INTERNAL_ERROR



 An unexpected internal error has occurred. Contact NMS Developer Support.




 NFXERR_LICENSE_ALREADY_ALLOC



 A fax license unit is already allocated to this CTA context




 NFXERR_NEGOTIATION_FAILED 



 Failed T.30 fax negotiation at the beginning of a session or between documents. When transmitting, this error indicates that training failed (usually due to bad phone line quality) or that the transmitter and receiver capabilities do not match. When receiving, this error indicates that training failed.




 NFXERR_NO_MODEMS



 The required DSP files are not configured or loaded to the AG board. The FXM service failed to start.




 NFXERR_NO_LICENSE



 No fax license unit is allocated to this CTA context.




 NFXERR_NO_MORE_LICENSES 



 There are no available fax license units.




 NFXERR_NO_MORE_DOCUMENTS 



 The fax session ended because there were no more receive files in the receive document queue.




 NFXERR_NO_PPM



 The receiver has not received a correct post-page message.




 NFXERR_NO_PPM_RESPONSE



 The receiver has not returned a correct response to the post-page message.




 NFXERR_NO_REMOTE



 The called fax terminal did not send a DIS signal.




 NFXERR_OPEN_QUEUE_FAILED



 Could not open the specified document queue. Check that you have a valid transmit queue.




 NFXERR_PROTOCOL_ERROR



 A T.30 protocol error occurred.




 NFXERR_QUEUE_EMPTY



 The specified document queue is empty.




 NFXERR_QUEUE_TOO_LATE



 Attempted to enqueue a file in an active transmit or receive queue too late in the fax session.




 NFXERR_RATE_TOO_LOW



 The receiving or transmitting fax terminal is attempting to receive or transmit at a rate lower than the minrate




 NFXERR_REMOTE_DCN



 The remote terminal has sent an unexpected disconnect (DCN) command frame.




 NFXERR_RETRAIN_NEGATIVE



 The page was received with errors, and NaturalFax has requested that the remote transmitter retransmit the last page.




 NFXERR_SESSION_FAILED



 The fax session failed due to an unexpected event. May indicate a T.30 timeout or failure to receive a post page message. Check your host processor CPU and I/O loading.


















The following CT Access errors can be returned as part of a NaturalFax DONE event:


  





 Error Name



 Description




 CTAERR_FILE_EXISTS



 You attempted to create a file that already exists. Remove or rename the existing file, or specify a different file name.




 CTAERR_FILE_NOT_FOUND



 The specified file does not exist. Create the file or specify a different file name.




 CTAERR_FILE_OPEN_FAILED



 File open failed due to a system error. Verify that the file exists.




 CTAERR_FILE_READ_FAILED



 The file is not opened or is locked, or the expected amount of data could not be read. Make sure that the file is of the expected type. Verify that an incorrect handle was not used to close another file.




 CTAERR_FILE_WRITE_FAILED



 The file is not open or is locked, or the expected amount of data could not be written. Verify that an incorrect handle was not used to close another file.




 CTAERR_FUNCTION_ACTIVE



 A function is already running on the CTA context. Be sure your application waits for a DONE event from other fax or voice operations before initiating a new fax operation.




 CTAERR_FUNCTION_NOT_ACTIVE



 An attempt was made to stop or modify a function that was not running.




 CTAERR_FUNCTION_NOT_AVAIL



 A NaturalFax DSP file has not been downloaded to the board. Check your AG configuration file and review agerror.log and ag.rpt for start-up problems.




 CTAERR_INVALID_CTAHD



 An invalid CTA context handle was passed as an argument to a function or the context was destroyed by another thread.




 CTAERR_OUT_OF_MEMORY



 Unable to allocate memory for queue, driver or CTA context, for play or record buffers, or for temporary storage. When this error occurs on a DONE event, it may mean that there was insufficient memory on the board.




 CTAERR_OUT_OF_RESOURCES



 A NaturalFax DSP function could not be started. Check to see that you are using the proper AG configuration for your application. Check to see that you have not exceeded the maximum number of fax operations for your hardware configuration.




 CTA_REASON_RELEASED



 The call has been disconnected by the remote fax machine. Check that events are being handled in a timely fashion. Check your host processor CPU loading. The application will also get ADIEVN_CALL_DISCONNECTED before it receives NFXEVN_SESSION_DONE with this reason code.



















2.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. NaturalFax sends a DCN (disconnect) frame at the end of a fax session, which signals the remote fax terminal to disconnect. The application must also use functions from the ADI service to release the call after a completed fax session.



Some fax terminals may disconnect the call before they receive 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 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 6, nfxReceiveFax, for more details.



For information about releasing and terminating calls, see the ADI Service Developer's Manual.






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





2.10	 Closing CT Access Services





CT Access supports opening and closing services on a CTA 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 CTA context. ctaCloseServices does not release the call, nor does it close the ADI service unless specified.


 






2.11	 Managing Fax Licenses 





A fax license is an allocation of fax resources. A fax license is only required for an active fax session. An active fax session begins when nfxSendFax or nfxReceiveFax is called and ends when the NFXEVN_SESSION_DONE event is received.



There are two ways to manage fax licenses: explicit allocation and automatic allocation.



With explicit allocation, the application explicitly allocates and releases license units using nfxGetLicense and nfxReleaseLicense. This allows the application to avoid a situation in which a call is placed, and the attempt to start a fax session fails because there are no available fax resources. 


Note:  If a fax license has been explicitly allocated, it must be explicitly freed at the end of the fax session. It will not be freed automatically.


Automatic allocation of fax licenses provides ease of use for the application. If an application does not explicitly allocate fax licenses, the NaturalFax functions will automatically allocate fax licenses as required.



nfxGetLicenseStatus reports the number of licensed fax units in use, and the number of units authorized for the system.



See the NaturalFax Installation Manual for details on obtaining and enabling fax licenses.











 
    (Page 1 of 1 in this chapter)




 




tech_support@nmss.com



Copyright © 1998, Natural MicroSystems, Inc.   All rights
reserved.