• 4.14.1. Conventions for Specifying the devicename Parameter
• 4.14.2. Examples of the devicename Parameter
• 4.14.3. Other gc_OpenEx( ) Considerations

4.14. gc_OpenEx( )

The gc_OpenEx( ) function is used to open both network board and channel (time slot) devices. This generic call control function initializes the specified time slot on the specified trunk. A line device ID will be returned to the application. The E-1 or T-1 feature of this function specifies the voice device as part of the devicename parameter.

4.14.1. Conventions for Specifying the devicename Parameter

A device is specified by the devicename parameter using a format that includes protocol specific information.

The format for the fields used to specify this parameter is:

:N_<network_device_name>:P_<protocol_name>:V_<voice_channel_name>

The prefixes (N_, P_, and V_) are used for parsing purposes. These fields may appear in any order. The fields within the devicename parameter must each begin with a colon.

The conventions described below allow the Global Call API to map subsequent calls made on specific line devices or CRNs to interface-specific libraries.

• <network_device_name>: This field is required. It may be a board name or a time slot name:
  • If <network_device_name> is a board name, use the format: dtiB<number of board>.
  • If <network_device_name> is a time slot name, use the format: dtiB<number of board>T<number of time slot>.
• <protocol_name>: This field is required on Springware boards. It specifies the protocol to use. Use the root file name of the country dependent parameters (.cdp) file.

  NOTE:

  On DM3 boards, the protocol is determined at board initialization time and not when a Global Call device is opened. For compatibility, the <protocol_name> field may be specified, but it is not used.

• <voice_channel_name>: This field is optional depending on your application (see Section 5.1. Dedicated Voice Resources or Section 5.2. Shared Voice Resources). It specifies the name of the voice channel to be associated with the device being opened. Use the following format: dxxxB<virtual board number>C<channel number>.

  NOTE:

  Attachment to different types of DM3 voice devices is dependent on the protocol downloaded. For example, if one board has ISDN for protocols and another has T-1 CAS, the T-1 CAS network devices cannot be attached to the voice devices on the ISDN board. See the Global Call API Programming Guide for further information.

4.14.2. Examples of the devicename Parameter

The following examples illustrate the devicename parameter when using E-1 ICAPI protocols:

• For a D/300SC-E1 board specified as dtiB3, the devicename for time slot 1 on this board using the inbound Brazil protocol is:

        :N_dtiB3T1:P_br_r2_i

• To open both voice channel 2 on virtual voice board 4 and the above network device, the devicename for the inbound Brazil protocol is:

        :N_dtiB3T1:P_br_r2_i:V_dxxxB4C2

• A line device may represent a board, thus to open the board dtiB1, the devicename is:

        :N_dtiB1:P_br_r2_i




4.14.3. Other gc_OpenEx( ) Considerations

For E-1 CAS or T-1 robbed bit applications, always specify a network resource (board or time slot level) and a protocol. A voice resource (<voice_channel_name>) may also be specified for E-1 CAS or T-1 robbed bit operations. When a voice resource is specified, Global Call automatically opens the voice device and internally attaches the voice device to the line device.

When using the CT Bus and a voice resource is specified, the gc_OpenEx( ) function routes the voice and network resources together.

When the voice resource is not specified, the application must perform these functions (open device, route, attach); see Section 5.1. Dedicated Voice Resources and Section 5.2. Shared Voice Resources for details.

When a network resource is specified, the gc_OpenEx( ) function internally issues a dt_open( ) function. Likewise, when a voice resource is specified, the gc_OpenEx( ) function internally issues a dx_open( ) function. The corresponding network or voice device handle may be retrieved using the gc_GetResourceH( ) function. These lower level device handles may be useful for routing or for playing or recording a file.

If a gc_OpenEx( ) function fails with an error value of EGC_DXOPEN, then the internally issued dx_open( ) function failed. If a gc_OpenEx( ) function fails with an error value of EGC_DTOPEN, then the internally issued dt_open( ) function failed.

Click here to contact Telecom Support Resources