Interactive Programming Model

• Sample GRT Applications
• Initialization
• Polling for an Event
• Termination
• Advanced GRT Applications
• GRT API Data Structures

The interactive programming model, which is recommended for fax-only applications, separates and provides distinct control at all phases of a fax transaction. In general, the call setup and call release phases are handled by the application using other telephony resources in the system such as network interface cards, voice boards or PBX APIs. The fax channel in this configuration only performs the pre-message, message transmission and post-message procedures (Phases B, C and D).

In this model, the application must monitor the call and decide when to start the fax resource. In contrast to the batch mode, the application can continue to monitor the call through the entire fax transaction, electing to change session parameters, interrupt the call or just abort all together. The monitoring activity is accomplished by examining "Events" - distinct points in the fax protocol where the fax channel notifies the application a fax event has occurred.

This programming model is a powerful feature of the GDK system but requires more knowledge of fax, more host computer resources and has timing requirements that are not present in the batch mode model. Figure 3 illustrates the GRT event notification phases.

NOTE:

The TESTFAX sample code, which uses the interactive programming model, is located on the GDK product CD-ROM.

Figure 3. GRT Events

The GDK interactive, runtime API (GRT) events shown in Table 33 notify the fax application of the fax transaction's progress and provide opportunity for the application to get information generated during the transaction and, optionally, alter the course of the call based on that information.

Each event can be "armed" in one of two ways: by using the No Response Required method to simply receive notification, or using the Armed-Requires Response method so the application must respond to the event. In the case of response required, the application has choices such as GRT_CONTINUE, GRT_END_CALL, or use a GRT_QREC. For the case of responding with a new queue record, see Chapter 4 for detailed information on queue record fields and their effects.

A simple interactive fax session is outlined below:

• initialize the run-time interface (grtInit( ))
• START
• establish the starting parameters for the fax transaction by programming a queue record (see Chapter 4)
• establish a connection to a fax machine (by dialing or answering) with a telephony network interface card in your system (i.e., analog, T1, E1, ISDN, etc.)
• start the fax session (grtSubmitFax( ))
• monitor for call completion (grtGetEvent( ))
• process event (grtProcessCallTermEvent( ))
• another call? go to START
• program complete (grtStop( ))

Sample GRT Applications

The GRT APIs provide multi-threaded support on a per-channel basis. An application can assign threads of control for one or more fax channels dynamically. A channel can only be controlled by one GRT thread.

Figure 4. GRT API Structure

A simple GRT application consists of three major components: initialization, polling for an event, and termination.

Initialization

A GRT thread is initialized using the grtInit( ) function. This function accepts a range of channels, the same thread can control several channels. The function can be called multiple times in the same thread, as long as a GRT thread doesn't already control the channel range given.

NOTE:

grtInit( ) will not create a new thread - it initializes existing internal structures that maintain GRT state information. A C function must be called to create a new thread.

Here is an example of how to initialize the first two fax channels for processing GRT_CALL_TERM events:

#include "genra.h"  
int status;  
status = grtInit(1,2,GRT_CALL_TERM_ENABLE);




Polling for an Event

Polling is used to check event status to determine whether an event has occurred. To check for an event, use the grtGetEvent( ) function. This function checks the channel range for a given event.

Here is an example of how to poll for a GRT event on the first two channels in a fax system:

GRT_EVENT event;  
for(;;)  
{  
  if (grtGetEvent(1,2,&event) == GRT_SUCCESS)  
    break;  
  Sleep(1000L);  
}




Termination

GRT API processing is terminated using the grtStop( ) function. This function stops any GRT processing in the given range of channels. This function allows for dynamic allocation of channels and threads as the system load changes.

The following is an example of how to stop GRT processing on channels 1 and 2 in a fax system:

#include "genra.h"  
int status;  
status = grtStop(1,2);  
printf("status = %d\n",status);

NOTE:

grtStop( ) must be called before exiting the application. Otherwise, grtInit( ) for the same channel range will return error code 103.

Advanced GRT Applications

Advanced GRT applications have an additional component: responding to an event (i.e. grtRespond, grtRespondEndCall, grtRespondContinue, grtRespondQueueRec). Responding to an event allows the application to change the default action for the fax channel. The fax channel default action for each event, listed in Table 33, is to continue the fax transaction through each phase, until GRT_CALL_TERM (Phase E), then post the completed queue record to the queue file.

If an application wants to change the default action of an event, event notification and event response enable must be specified for that event when initializing the GRT interface for the fax channel. At each fax channel event notification, if event response is enabled, the application can respond to end the call (grtRespondEndCall) or to continue the call (grtRespondContinue).

For the GRT_CALL_PENDING event, the application has an additional response available (grtRespondQueueRec), with which the characteristics of the fax transmission can be changed through the submission of another queue record.

For example, turn-around polling can be accomplished by responding to the GRT_CALL_PENDING event with a queue record whose operation field is set to the GFQANSWER_RECEIVE_SEND value. Other queue record operation field values are listed in Chapter 4.

GRT API Data Structures

An alphabetized list of the GRT API data structures appears in the following section.

Click here to contact Dialogic Customer Engineering