12.5.1. Porting an Application to R4 on DM3 with Fixed Routing
The following information describes how to develop applications for an R4 for DM3 fixed routing configuration, with a focus on modifying existing R4 API applications so that they can accommodate DM3 boards.
This information addresses general areas for migrating an existing R4 application to an R4 for DM3 application and provides examples from porting the existing Dialogic PANSR (polled asynchronous) Answering Machine demonstration program to R4 for DM3.
CT Bus, SCbus and DM3 Clusters with Fixed RoutingGeneral information on DM3 clustering is available in Section 12.1. Fixed and Flexible Routing Configurations. The following information applies to coupled resource clusters, which are used in the fixed routing configuration.
Figure 4. Default DM3 Fixed Routing Cluster for QuadSpan DM/V960-4T1 and DM/V1200-4E1 Boards
Figure 5 shows a default DM3 cluster for DM/VF boards such as DM/VF240-T1 and DM/VF300-E1. Note the addition of a fax resource in the same cluster.
Figure 5. Default DM3 Fixed Routing Cluster with Fax Resource for DM/VF Boards
The SCbus resource is the DM3 resource that provides access to the CT Bus. As indicated in Figure 4 and Figure 5, the only DM3 resource that has access to the SCbus resource is the Telephony Service Channel (TSC). None of the other resources have access to the SCbus resource and therefore cannot access the CT Bus directly.
In R4 for DM3, the TSC resource instance is abstracted by the DTI timeslot device, or dtiBnTm, while the rest of the resource instances are all grouped and abstracted by the voice channel device, or dxxxBnCm.
The immediate consequence of this DM3 clustering scheme is that the DTI devices, dtiBnTm, have full access and provide full support to the R4 SCbus routing API. On the other hand, the voice devices, dxxxBnCm, do not have direct access to the CT Bus, hence the R4 voice resource SCbus routing API has no effect on the DM3 voice devices.
Note that even though the DM3 hardware uses the CT Bus, R4 for DM3 abstracts its functionality using the R4 SCbus routing API.
The preceding concepts present what are perhaps the most challenging aspects of porting an existing R4 application to R4 for DM3. Here are some points to note about this configuration:
R4 for DM3 applications can continue using SCbus routing functions on the DTI network interface device, dtiBnTm, because DM3 clusters do not affect their operation.
The application can therefore find the CT Bus transmit timeslot and attach (listen) or de-attach (unlisten) a DTI timeslot device as desired. This is of particular interest for those applications that wish to connect two network interface devices in conversation, so that an inbound caller can be connected in conversation with an outbound call.
R4 for DM3 applications should not attempt to perform SCbus routing on voice channel devices, since the API function call would fail with error code EDX_SH_MISSING, indicating that the operation is not possible on the device.
12.5.2. Initializing an Application Under Different Hardware and API Scenarios (Fixed Routing)DM3 devices have similar characteristics to earlier-generation devices. The device must first be opened in order to obtain its handle, which can then be used to access the device functionality.
Since R4 for DM3 applications must use GlobalCall for call control, i.e., for call setup and tear-down, all Dialogic network interface devices must be opened using the gc_Open( ) or gc_OpenEx( ) function.
Once the call has been established, voice and or data streaming should be done using the Dialogic voice API. Functions such as dx_playiottdata( ), dx_reciottdata( ), and dx_dial( ) can be used. Of course, in order to do so, the voice device handle must be obtained. By the same token, in order to access the DTI routing functionality with functions such as dt_listen( ) and dt_unlisten( ), the corresponding DTI device handle must be obtained accordingly.
Application initialization differs depending on the types of hardware and the APIs used. The simplest hardware and API scenarios are those where the system contains only one type of board, so that the application uses either earlier-generation boards or DM3 boards but not both. In these cases, the initialization routine is the simplest in that it does not need to discover the board family type. See the following sections for descriptions and procedures for the stated API and hardware combinations:
Applications that want to make use of both earlier-generation and DM3 devices must have a way of differentiating what type of device is to be opened.
The dx_getctinfo( ) and dt_getctinfo( ) functions provide a programming solution to this problem. R4 for DM3 contains a new equate for the CT_DEVINFO.ct_devfamily, equal to CT_DFDM3. Only DM3 devices will have the ct_devfamily set to CT_DFDM3.
See the following sections for descriptions and procedures for the stated API and hardware combinations:
GlobalCall API with Earlier-Generation Boards OnlyThis scenario is one where a standard R4 application uses only earlier-generation boards. Standard R4 digital interface applications typically perform the following initialization routine:
This is necessary since digital interface timeslot devices and their corresponding voice channel devices are not attached nor routed to each other on the SCbus by default. This is true even for the default devices such as the first trunk timeslot and the first voice channel device for the same physical Span Card hardware.
This peculiar characteristic of earlier-generation Dialogic digital hardware, such as the Span Cards, forces the application to do the proper SCbus routing and attaching of the devices (steps 5 and 6 ).
GlobalCall API with DM3 Boards Only (Fixed Routing)This scenario is one where an R4 for DM3 application uses only DM3 boards.
SCbus routing and attaching of the devices is not necessary with DM3 hardware and the DM3 clustering scheme. The voice device and network interface timeslot that share the same DM3 cluster are permanently routed and attached to each other, and the voice device has no direct access to the CT Bus timeslots.
For the same reason, it is not possible to move audio from a voice device channel to a DTI network interface timeslot device when they do not share the same DM3 cluster. In other words, a dx_playiottdata( ) command over a specific device handle will result in audio being pumped to its corresponding DTI device that is within the same cluster.
In most cases, R4 for DM3 applications do not need to open the voice channel device and/or the network interface timeslot device directly using the voice and DTI APIs respectively, since it is neither necessary nor possible to attach both devices together from the host.
Furthermore, for the same reasons mentioned above, the gc_Open( ) device string should not indicate the name of the voice device channel. For example, the device name string for the gc_Open( ) function should look similar to the following:
":N_dtiB1T1:P_ISDN"
Although it is unnecessary to specify the ISDN protocol for R4 on DM3 boards, it is specified in this example to retain compatibility with R4 on earlier-generation boards. The gc_Open( ) function will internally open the associated voice channel.
An R4 for DM3 digital interface application would typically perform the following initialization routine:
GlobalCall API with DM3 and Earlier-Generation Boards (Fixed Routing)The following procedure shows how to initialize an application and perform device discovery when the application supports both DM3 and earlier-generation boards through the R4 GlobalCall API:
This initialization routine will not work well for an application that uses the R4 DTI API for the earlier-generation network interface devices in addition to the R4 for DM3 GlobalCall API for DM3 devices. This is the typical case of a T-1 robbed-bit application developed prior to the availability of the GlobalCall US T-1 protocol.
GlobalCall API with DM3 Boards and DTI API with Earlier-Generation Boards (Fixed Routing)The following procedure shows how to initialize an application and perform device discovery when the application supports both DM3 and earlier-generation boards through the R4 for DM3 GlobalCall API and the R4 DTI API, respectively:
12.5.3. Porting the PANSR Demonstration Program to R4 for DM3 with Fixed RoutingThe Dialogic Answering Machine Demonstration program (PANSR) is a sample demonstration program that uses the Dialogic R4 DTI and Voice APIs to simulate the operation of a simple household answering machine. This section describes the steps taken to port the existing PANSR demonstration program so that it can work with both earlier-generation and DM3 devices. The most important considerations when porting the code are included.
The PANSR demonstration program (hereafter referred to as "the demo") is an MFC GUI application that simulates a simple answering machine. The demo receives a call, plays an introduction prompt, and based on caller response, it either records a message or else plays a previously recorded message to the caller.
The original PANSR demo supports Analog, T-1 E&M robbed-bit, as well as a CAS E-1 protocol, and supports Span Cards and D/4x boards.
Convert Analog Call Control to GlobalCallThe main differences between standard R4 and R4 for DM3 are call control. The following table gives a brief explanation of how to convert an analog network interface call control to use GlobalCall.
Table 20. Porting Analog Call Control to GlobalCall (Fixed Routing)
Call State |
R4 Functions |
GlobalCall Functions |
System initialization |
dx_open( ) |
gc_Start( ) Note: After gc_Open( ) or gc_OpenEx( ), the application must wait for a GCEV_UNBLOCKED event before proceeding with a call (make call or wait call). |
Wait for inbound call |
Enable CST event mask DE_RINGS by calling dx_setevtmsk( ) |
gc_WaitCall( ) |
Answer inbound call |
dx_sethook( ) with DX_OFFHOOK |
gc_AcceptCall( ) |
Drop a call |
dx_sethook( ) with DX_ONHOOK |
gc_DropCall( ) |
Make outbound call |
dx_sethook( ) with DX_OFFHOOK |
gc_MakeCall( ) |
Wait for disconnect |
TDX_CST event of DE_LCOFF |
GlobalCall event GCEV_DISCONNECTED |
Retrieve Board Family InformationThe PANSR demo provides support for both earlier-generation and DM3 devices. For earlier-generation devices, the demo works the same as the previous version, but for DM3 devices, GlobalCall is adopted for call control. In order to determine if a device is an earlier-generation device or a DM3 device, the demo retrieves the device family information for all DTI and voice devices and stores the information in a global structure array for later reference.
The following code segment shows how to retrieve the family information for each board.
// Get number of DTI boards in system
if( sr_getboardcnt( DEV_CLASS_DTI, &Dti.NumBrdDevs ) == -1 )
{
MessageBox(hWnd, "Error in retrieving DTI board count", szAppName,
MB_OK|MB_APPLMODAL);
return FALSE;
}
if( Dti.NumBrdDevs )
{
for ( index = 0; index < Dti.NumBrdDevs; index++ )
{
sprintf( Dti.BrdNames[ index ], "dtiB%d\0", index + 1 );
sprintf( dev_name, "dtiB%dT1\0", index + 1 );
if(( tsdev = dt_open( dev_name, 0 ) ) == -1 )
{
sprintf( tmpbuff, "Cannot open channel %s. errno = %d", dev_name, errno );
MessageBox( hWnd, tmpbuff, szAppName, MB_OK|MB_APPLMODAL );
return FALSE;
}
// Get Device Information
if( dt_getctinfo( tsdev, &ct_devinfo ) == -1 )
{
sprintf( tmpbuff, "Error message = %s", ATDV_ERRMSGP( tsdev ) );
MessageBox( hWnd, tmpbuff, szAppName, MB_OK|MB_APPLMODAL );
dt_close( tsdev );
return FALSE;
}
if( dt_close( tsdev ) == -1 )
{
sprintf( tmpbuff, "Cannot close channel %s. errno = %d", dev_name, errno);
MessageBox( hWnd, tmpbuff, szAppName, MB_OK|MB_APPLMODAL );
return FALSE;
}
if ( ct_devinfo.ct_devfamily == CT_DFDM3 )
Dti.frontend[ index ] = CT_NTDM3;
else
Dti.frontend[ index ] = ct_devinfo.ct_nettype;
}
}
// Get number of voice boards in system
if( sr_getboardcnt( DEV_CLASS_VOICE, &( Vox.NumBrdDevs ) ) == -1)
{
MessageBox( hWnd, "Error retrieving voice board count", szAppName,
MB_OK|MB_APPLMODAL );
return FALSE;
}
// Make board and channel names for VOX devices
if( Vox.NumBrdDevs )
{
for ( index = 0; index < Vox.NumBrdDevs; index++ )
{
sprintf( Vox.BrdNames[ index ], "dxxxB%d\0", index + 1 );
sprintf( dev_name, "dxxxB%dC1\0", index + 1 );
if ( ( chdev = dx_open( dev_name, 0 ) ) == -1 )
{
sprintf( tmpbuff, "Cannot open channel %s. errno = %d", dev_name, errno );
MessageBox( hWnd, tmpbuff, szAppName, MB_OK|MB_APPLMODAL );
return FALSE;
}
// Get Device Information
if( dx_getctinfo( chdev, &ct_devinfo ) == -1 )
{
sprintf( tmpbuff, "Error message = %s", ATDV_ERRMSGP( chdev ) );
MessageBox( hWnd, tmpbuff, szAppName, MB_OK|MB_APPLMODAL );
dx_close( chdev );
return FALSE;
}
if( dx_close( chdev ) == -1 )
{
sprintf( tmpbuff, "Cannot close channel %s. errno = %d", dev_name, errno);
MessageBox( hWnd, tmpbuff, szAppName, MB_OK|MB_APPLMODAL );
return FALSE;
}
if( ct_devinfo.ct_devfamily == CT_DFDM3 )
Vox.frontend[ index ] = CT_NTDM3;
else
Vox.frontend[ index ] = CT_NTANALOG;
}
}
Based on the family information, the application can be customized to take advantage of the features for the type of board.
Initialize GlobalCallWhen the PANSR demo is executed on a system containing DM3 devices, GlobalCall must be initialized before opening the devices. If the PANSR demo is executed on a system containing earlier-generation devices, this step is skipped.
The following code segment shows how to initialize GlobalCall:
if( frontend == CT_NTDM3 )
{
if( gc_Start( NULL ) != GC_SUCCESS )
{
gc_ErrorValue( &gc_error, &cclibid, &cc_error);
gc_ResultMsg( LIBID_GC, (long) gc_error, &msg);
sprintf( tmpbuff, "Error in gc_Start ErrorValue: %d - %s\n", gc_error, msg);
disp_msg( tmpbuff );
QUIT( 2 );
}
}
Open DevicesFor earlier-generation devices, the PANSR demo opens voice devices and DTI devices with dx_open( ) and dt_open( ). If SCbus routing was selected as an option at the beginning of the demo, the demo calls the SCbus routing function nr_scroute( ) to route voice resources to DTI devices.
If the PANSR demo is executed on a system containing DM3 devices, the demo uses GlobalCall gc_Open( ) with the device naming convention ":N_dtiBxTx:P_protocol" instead of dx_open( ) and dt_open( ) to open GlobalCall device handles. The demo calls gc_GetVoiceH( ) to retrieve the associated voice handle and stores it in a channel-specific structure for later reference. The protocol name is retrieved from the internal protocol setting which the developer specified in application settings. Because SCbus routing of voice resources is not supported in the DM3 fixed routing configuration, the SCbus routing procedure for DM3 devices is skipped.
The following segment shows how to open GlobalCall devices and retrieve associated voice devices.
// Open GlobalCall device
sprintf( dxinfo[ channum ].ldevname, ":N_dtiB%dT%d:P_ISDN", dtibdnum, channum );
if( gc_Open( &dxinfo[ channum ].ldev, dxinfo[ channum ].ldevname, 0 ) == -1 )
{
gc_ErrorValue( &gc_error, &cclibid, &cc_error);
gc_ResultMsg( LIBID_GC, (long) gc_error, &msg);
sprintf( tmpbuff, "Unable to open DM3 %s\n%s", dxinfo[ channum ].ldevname,msg );
disp_msg( tmpbuff );
QUIT( 2 );
}
// Retrieve the associated voice device
gc_GetVoiceH( dxinfo[ channum ].ldev, &dxinfo[ channum ].chdev);
Process SRL EventsThe SRL event processing routine waits for any SRL event by calling sr_waitevt( ). For systems containing DM3 devices, the PANSR demo calls gc_GetMetaEvent( ) to process GlobalCall-specific events. Otherwise, sr_getevtdev( ) and sr_getevtdatap( ) are used to retrieve the appropriate information.
The structure METAEVENT, filled by gc_GetMetaEvent( ), contains all necessary event data for event processing, including the SRL event type, event handle and additional event data.
The following code segment shows how to process SRL events:
// Wait for SRL event
if( sr_waitevt( timeout ) != -1 )
{
if( frontend == CT_NTDM3 )
{
// DM3 devices
rc = gc_GetMetaEvent( &MetaEvent );
chtsdev = Metaevent.evtdev;
}
else
{
// earlier-generation devices
chtsdev = sr_getevtdev( );
}
...
// Further event process
...
}
Wait for Incoming CallFor earlier-generation devices, the PANSR demo relies on various interface-specific events to recognize an incoming call. On boards with an analog network interface, the demo waits for a TDX_CST event with DE_RINGS cst_event data. On boards with a digital network interface, the demo waits for changes in the E-1 or T-1 digital signal.
For DM3 devices, the demo calls gc_WaitCall( ) to initialize a "wait for incoming call" state. An incoming call is indicated by a GlobalCall event GCEV_OFFERED.
The following code segment shows how to initialize call waiting in asynchronous mode:
if( gc_WaitCall(dxinfo[ channum ].ldev, NULL, NULL, 0, EV_ASYNC) != GC_SUCCESS)
{
gc_ErrorValue( &gc_error, &cclibid, &cc_error);
gc_ResultMsg( LIBID_GC, (long) gc_error, &msg);
sprintf( tmpbuff, "gc_WaitCall Error%s\n%s", lineDevName,msg );
disp_msg( tmpbuff );
QUIT( 2 );
}
dxinfo[ channum ].state = ST_WTRING;
The incoming call is reported by the GlobalCall event GCEV_OFFERED.
Answer Inbound CallOn boards with an analog network interface, the demo calls dx_sethook( ) to go off hook. On earlier-generation boards with a digital network interface, the demo calls dt_settssigsim( ) to set digital signals indicating that the incoming call is answered.
For DM3 devices, the demo does the following:
The following code segment shows how to answer an incoming call in asynchronous mode:
rc = gc_GetMetaEvent( &dxinfo[ channum ].ch_Metaevent);
if( rc != GC_SUCCESS)
{
gc_ErrorValue( &gc_error, &cclibid, &cc_error);
gc_ResultMsg( LIBID_GC, (long) gc_error, &msg);
sprintf( tmpbuff, " gc_GetMetaEvent Error%s\n%s", lineDevName,msg );
disp_msg( tmpbuff );
QUIT( 2 );
}
rc = gc_GetCRN( &dxinfo[ channum ].crn, &dxinfo[ channum ].ch_Metaevent );
if( rc != GC_SUCCESS)
{
gc_ErrorValue( &gc_error, &cclibid, &cc_error);
gc_ResultMsg( LIBID_GC, (long) gc_error, &msg);
sprintf( tmpbuff, "gc_GetCRN Error%s\n%s", lineDevName,msg );
disp_msg( tmpbuff );
QUIT( 2 );
}
rc = gc_AnswerCall( dxinfo[ channum ].crn, 0, EV_ASYNC);
if( rc != GC_SUCCESS)
{
gc_ErrorValue( &gc_error, &cclibid, &cc_error);
gc_ResultMsg( LIBID_GC, (long) gc_error, &msg);
sprintf( tmpbuff, "gc_AnswerCall Error%s\n%s", lineDevName,msg );
disp_msg( tmpbuff );
QUIT( 2 );
}
Monitor Call DisconnectionAfter the call is answered, the call may be disconnected at any time. For earlier-generation devices, depending upon the network interface of the device, when a call is disconnected, the PANSR demo is notified. On boards with an analog network interface, the notification is a TDX_CST event in which the cst_event is DE_LCOFF. On earlier-generation boards with a digital network interface, the notification is through digital signaling.
For DM3 devices, the call disconnection is notified by the GlobalCall event GCEV_DISCONNECTED.
Drop CallFor earlier-generation devices, the PANSR demo drops a call in according to the network interface of the device. On boards with an analog network interface, the demo calls dx_sethook( ) to go on hook. On boards with a digital network interface, the demo calls dt_settssigsim( ) to transmit digital signals to drop the call.
For DM3 devices, the demo calls gc_DropCall( ) to drop the call. The completion of call dropping is indicated by the GlobalCall event GCEV_DROPCALL. After the call is dropped, the demo calls gc_ReleaseCall( ) to release the call completely.
The following code segment shows how to receive a call disconnect event and drop the call in asynchronous mode.
switch( event )
{
...
case GCEV_DISCONNECTED :
if( gc_DropCall( dxinfo[ channum ].crn, GC_NORMAL_CLEARING, EV_ASYNC )!= 0)
{
gc_ErrorValue( &gc_error, &cclibid, &cc_error);
gc_ResultMsg( LIBID_GC, (long) gc_error, &msg);
sprintf( tmpbuff, "The linedev %s call cannot be dropped!\nERROR: %s",
lineDevName, msg );
disp_msg( tmpbuff );
QUIT( 2 );
}
break;
case GCEV_DROPCALL:
if( gc_ReleaseCall( dxinfo[ channum ].crn ) != 0 )
{
gc_ErrorValue( &gc_error, &cclibid, &cc_error);
gc_ResultMsg( LIBID_GC, (long) gc_error, &msg);
sprintf( tmpbuff, "The linedev %s call cannot be released!\nERROR: %s",
lineDevName, msg );
disp_msg( tmpbuff );
QUIT( 2 );
}
break;
...
}
Clean-upIn application clean-up, the PANSR demo closes all opened devices. If GlobalCall was started, the demo calls gc_Stop( ) to stop GlobalCall.
Make Outbound CallThis is a topic not covered in the implementation of the PANSR demo, but is presented here to give information about how to make outbound calls using GlobalCall for DM3 devices.
For earlier-generation devices, analog network interface devices use dx_sethook( ) and dx_dial( ) with or without call analysis to make an outbound call, while digital network interface devices use dt_settssigsim( ) and corresponding call processing signaling to make an outbound call.
For DM3 devices, the program should use gc_MakeCall( ) to make a call. After a call is established or has failed to connect, the program will be informed by the GlobalCall events such as GCEV_CONNECTED, GCEV_ALERTING, or GCEV_DISCONNECTED.
Click here to contact Dialogic Customer Engineering
Copyright 2002, Intel Corporation