• 11.3.1. Initializing the GlobalCall API for DM3 Boards Only (Flexible Routing)
• 11.3.2. Device Discovery for DM3 Boards and Earlier-Generation Boards (Flexible Routing)

11.3. Initializing an R4 on DM3 Application

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. Where call control is not required, such as with ISDN NFAS, dt_open( ) may be used to open DM3 network interface devices.

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 scenario is that 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 Section 11.3.1. Initializing the GlobalCall API for DM3 Boards Only (Flexible Routing) for more information.

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 SCbus routing device information functions, such as dx_getctinfo( ) and dt_getctinfo( ), provide a programming solution to this problem. DM3 hardware is identified by the CT_DFDM3 value in the CT_DEVINFO.ct_devfamily field. Only DM3 devices will have the ct_devfamily field set to CT_DFDM3. See Section 11.3.2. Device Discovery for DM3 Boards and Earlier-Generation Boards (Flexible Routing) for more information.

The following guidelines for initializing applications apply to an R4 on DM3 flexible routing configuration.

11.3.1. Initializing the GlobalCall API for DM3 Boards Only (Flexible Routing)

This scenario is one where an R4 for DM3 application uses only DM3 boards in a flexible routing configuration.

When initializing an application to use DM3 boards, you must use GlobalCall to handle the call control. Initializing GlobalCall with only DM3 boards in the system is no different than when initializing GlobalCall with only earlier-generation devices in the system. This is because R4 on DM3 is flexible enough to support the different methods of GlobalCall initialization for both ISDN and CAS protocols.

Take note of the following flexibility that exists for the gc_Open( ) or gc_OpenEx( ) functions when opening a GlobalCall line device on DM3 boards:

• Due to the nature of DM3, the protocol name is irrelevant at the time of opening the GlobalCall line device; that is, the protocol name is ignored. Although it is unnecessary to specify a protocol name, you can retain a protocol name in this field to support earlier-generation boards and so as to retain compatibility with code for earlier-generation boards. Also, for R4 on DM3, all protocols are bi-directional. You do not need to dynamically open and close devices to change the direction of the protocol.
• It is not necessary to specify a voice device name when opening a GlobalCall line device. If you specify the voice device name, the network interface device is automatically associated with the voice device (they are attached and routed on the CT Bus). If you do not specify the voice device name when you open the GlobalCall line device, you can separately open a voice device, and then attach and route it to the network interface device. This flexibility allows you to port a GlobalCall application from earlier-generation boards to DM3 boards with little change and regardless of whether the application uses an ISDN or CAS protocol.
  
  Note that when opening a GlobalCall line device for CAS protocols on earlier-generation boards, the voice device name, network interface device name, and protocol name are required; otherwise the function fails. For ISDN protocols on earlier-generation boards, it is invalid to specify a voice device name; otherwise the function fails. For DM3 boards in a flexible routing configuration, only the network device name is required.

The following procedure shows how to initialize GlobalCall when using only DM3 boards (in a flexible routing configuration). For some steps, two alternatives are described (A and B), depending upon whether you want your application to retain the greatest degree of compatibility with GlobalCall using an ISDN protocol or a CAS protocol on earlier-generation boards. Since this procedure is oriented toward retaining compatibility with two common ways to initialize GlobalCall on earlier-generation boards, it is not intended as a recommendation of a preferred way to initialize GlobalCall on DM3 boards. The R4 GlobalCall API on DM3 allows design flexibility. The procedure for GlobalCall initialization for a given application would depend upon things such as whether earlier-generation boards and DM3 boards are used in the same system, what protocol is used, the purpose of the application program, and its design.

NOTE:

In Windows, use the sr_getboardcnt( ) function with the class name set to DEV_CLASS_DTI and DEV_CLASS_VOICE to determine the number of network and voice boards in the system, respectively. In Linux, use SRL device mapper functions to return information about the structure of the system. These functions are described in the Voice Software Reference - Standard Run-time Library.

1. Start/Initialize GlobalCall with gc_Start( ).
2. Use gc_Open( ) or gc_OpenEx( ) to open a GlobalCall line device.
   • Specify the network interface device name and the protocol name in the devicename parameter, as in the following example:
     
     ":N_dtiB1T1:P_ISDN"
   • Alternatively, specify the network interface device name, the voice device name, and the protocol name in the devicename parameter, as in the following example:
     
     ":N_dtiB1T1:V_dxxxB1C1:P_ar_r2_io"
3. Obtain the voice channel device handle.
   • Open a voice channel device (e.g., dxxxB1C1) with dx_open( ) to get its handle.
   • Alternatively, if you specified the voice device name in the devicename parameter in step 2, use gc_GetVoiceH( ) to get the handle.
4. Attach the voice and network interface devices.
   • Use gc_Attach( ) to attach the voice resource and the network interface line device.
   • Alternatively, if you specified the voice device name in the devicename parameter in step 2, the voice and network interface devices are attached by nature of the gc_Open( ), so no action is necessary for this step.
5. Use gc_GetNetworkH( ) to obtain the network interface timeslot device handle that is associated with the line device.
6. Set up SCbus full duplex routing between the network interface device and voice device.
   • Use nr_scroute(FULL DUPLEX).
   • Alternatively, if you specified the voice device name in the devicename parameter in step 2, the network interface device and voice device are automatically routed on the SCbus by nature of the gc_Open( ).

Repeat steps 2 to 6 for all GlobalCall device names.

11.3.2. Device Discovery for DM3 Boards and Earlier-Generation Boards (Flexible Routing)

The following procedure shows how to initialize an R4 on DM3 application and perform device discovery when the application supports both DM3 and earlier-generation boards.

NOTE:

In Windows, use the sr_getboardcnt( ) function with the class name set to DEV_CLASS_DTI and DEV_CLASS_VOICE to determine the number of network and voice boards in the system, respectively. In Linux, use SRL device mapper functions to return information about the structure of the system. These functions are described in the Voice Software Reference - Standard Run-time Library.

1. Open the first network interface timeslot device (e.g., dtiB1T1) on the first trunk with dt_open( ).
2. Call dt_getctinfo( ) and check the CT_DEVINFO.ct_devfamily value.
3. If ct_devfamily is CT_DFDM3, then flag all the network interface timeslot devices associated with the trunk as DM3 type.
4. Close the DTI device with dt_close( ).
5. Repeat steps 1 to 4 for each trunk.
6. Open the first voice channel device on the first voice board in the system with dx_open( ).
7. Call dx_getctinfo( ) and check the CT_DEVINFO.ct_devfamily value.
8. If ct_devfamily is CT_DFDM3, then flag all the voice channel devices associated with the board as DM3 type.
9. Close the voice channel with dx_close( ).
10. Repeat steps 6 to 9 for each voice board.
11. For those voice and network interface devices that are not DM3 devices, proceed with the standard initialization process for earlier-generation boards as performed in the original application.
12. For those voice and network interface devices that are DM3 devices, proceed with the initialization as described in Section 11.3.1. Initializing the GlobalCall API for DM3 Boards Only (Flexible Routing).

Click here to contact Dialogic Customer Engineering