Previous PageTable Of Contents../index.htmlIndexNext Page


dx_dial( )

Description | Cautions | Example 1: | Example 2: | Example 3: | Example 4: | Errors | See Also

Name:

int dx_dial(chdev, dialstrp, capp, mode)

Inputs:

int chdev

  Valid Dialogic channel device handle

 

char *dialstrp

  pointer to the ASCIIZ dial string

 

DX_CAP *capp

  pointer to Call Analysis Parameter Structure

 

unsigned short mode

  asynchronous/synchronous setting and Call Analysis flag

Returns:

0 to indicate successful initiation (Asynchronous)
>=0 to indicate Call Analysis result if successful (Synchronous)
-1 if failure

Includes:

srllib.h
dxxxlib.h

Category:

I/O

Mode:

synchronous/asynchronous

Top Of PageDescription

The dx_dial( ) function dials an ASCIIZ string on an open, idle channel and optionally enables Call Analysis to provide information about the call.

To determine the state of the channel during a dial and/or Call Analysis, use ATDX_STATE( ), which will return one of the following:

CS_DIAL

dial state (with or without Call Analysis)

CS_CALL

Call Analysis state

NOTES:
1. dx_dial( ) doesn't affect the hook state.
2. dx_dial( ) doesn't wait for dial tone before dialing.
3. dx_dial( ) without Call Analysis enabled cannot be terminated using dx_stopch( ), unlike most I/O functions.

The function parameters are defined as follows:

Parameter

Description

chdev:

Specifies the valid channel device handle obtained when the channel was opened using dx_open( ).

Dialstrp:

Points to the ASCII dial string. dialstrp must contain a null-terminated string of ASCII characters. Valid dialing and control characters are described in Table 2. The dialing mode is specified by a "T" (DTMF tone dialing), "P" (pulse dialing), or "M" (MF dialing) in the dial string. If "T", "P", or "M" is not specified in dialstrp, DTMF tone dialing is used.

The pause character "," and the flash character "&" are not available in MF dialing mode. To send these characters while sending a string of MF digits, switch to DTMF or pulse mode before sending "," or "&", then switch back to MF mode by sending an "M". The following string demonstrates this use:

M*1234T,M5678a

capp:

Points to the Call Analysis Parameter Structure, DX_CAP. This structure is described in Chapter 4. Data Structures and Device Parameters.

To use the default Call Analysis parameters, specify NULL in capp and DX_CALLP in mode.

mode:

Specifies whether an ASCIIZ string should be dialed with or without Call Analysis enabled, and whether the function should run asynchronously or synchronously. mode is a bit mask that can be set to a combination of the following values:

 

DX_CALLP

  Call Analysis Enable Call Analysis.

 

EV_ASYNC

  Run dx_dial( ) asynchronously.

 

EV_SYNC

  Run dx_dial( ) synchronously (default).

 

To run dx_dial( ) without Call Analysis, specify only EV_ASYNC or EV_SYNC.

 

If dx_dial( ) is called on a channel that is on hook, the function will only dial digits. Call analysis will not occur.


Table 2. Valid Characters for Each Dialing Mode

Pulse Digit


Description

DTMF Digit


Description

MF Digit


Description

"0"-"9"

 

"0"-"9"

 

"0"-"9"

 
   

"*"

 

"*"

KP

   

"#"

 

"#"

ST

   

"a"

 

"a"

PST

   

"b"

 

"b"

ST2

   

"c"

 

"c"

ST3

   

"d"

 

"L"

 

","

pause

","

pause

"I"

 

"&"

flash

"&"

flash

"X"

 

"L"

 

"L"

     

"I"

 

"I"

     

"X"

 

"X"

     

Change dial mode to:

Change dial mode to:

Change dial mode to:

"P"

Pulse mode

"P"

Pulse mode

"P"

Pulse mode

"T"

DTMF mode

"T"

DTMF mode

"T"

DTMF mode

"M"

MF mode

"M"

MF mode

"M"

MF mode

Set the mode field to EV_ASYNC, using a bitwise OR. When running asynchronously, the function will return 0 to indicate it has initiated successfully, and will generate one of the following termination events to indicate completion:

TDX_DIAL

  termination of dialing (without Call Analysis)

TDX_CALLP

  termination of dialing (with Call Analysis)

If asynchronous dx_dial( ) terminates with a TDX_DIAL event, use ATDX_TERMMSK( ) to determine the reason for termination. If dx_dial( ) terminates with a TDX_CALLP event, use ATDX_CPTERM( ) to determine the reason for termination. These Call Analysis termination reasons are listed under the description of Call Analysis, below.

Use the SRL Event Management functions to handle the termination event. See Appendix A for more information about the Event Management functions.

By default, this function runs synchronously, and will return a 0 to indicate that it has completed successfully.

When synchronous dialing terminates, the function will return the Call Progress result (if Call Analysis is enabled) or 0 to indicate success (if Call Analysis isn't enabled).

Call Analysis

Call Analysis provides information about the call. It is enabled to run on the call after dialing completes by setting the mode field. The function can be set to run using default Call Analysis parameters, or by using the Call Analysis Parameter structure (DX_CAP).

Call Analysis results can be retrieved using ATDX_CPTERM( ). If dx_dial( ) is running synchronously, the Call Analysis results will also be returned by the function.

For more information about Call Analysis, see the Voice Software Reference - Voice Features Guide for Linux.

Possible Call Analysis termination reasons are listed below:

CR_BUSY

  line was busy

CR_CEPT

  operator intercept

CR_CNCT

  call connected

CR_ERROR

  Call Analysis error

CR_FAXTONE

  fax machine or modem

CR_NOANS

  no answer

CR_NODIALTONE

  no dial tone

CR_NORB

  no ringback

CR_STOPD

  Call Analysis stopped due to dx_stopch( )

If Call Analysis is enabled, additional information about the call can be returned using the following Extended Attribute functions:

ATDX_ANSRSIZ( )

  duration of answer

ATDX_CPERROR( )

  Call Analysis error

ATDX_CPTERM( )

  last Call Analysis termination

ATDX_CRTNID( )

  tone identifier

ATDX_DTNFAIL( )

  dial tone fail character

ATDX_FRQDUR( )

  duration of first frequency detected

ATDX_FRQDUR2( )

  duration of second frequency detected

ATDX_FRQDUR3( )

  duration of third frequency detected

ATDX_FRQHZ( )

  frequency detected in Hz

ATDX_FRQHZ2( )

  frequency of second detected tone

ATDX_FRQHZ3( )

  frequency of third detected tone

ATDX_LONGLOW( )

  duration of longer silence

ATDX_FRQOUT( )

  percent of frequency out of bounds

ATDX_SHORTLOW( )

  duration of shorter silence

ATDX_SIZEHI( )

  duration of non-silence

Top Of PageCautions

  1. If you attempt to dial a channel in MF mode and do not have MF capabilities on that channel, DTMF tone dialing is used.
  2. Issuing a dx_stopch( ) on a channel that is dialing without Call Analysis enabled has no effect on the dial, and will return 0. The digits specified in the dialstrp parameter will still be dialed.
  1. This function must be issued when the channel is idle.

Top Of PageExample 1: Call Analysis with specified parameters (Synchronous Mode)

Top Of PageExample 2: Call Analysis with default parameters

Top Of PageExample 3: Call Analysis with default parameters (Asynchronous, Callback Mode)

Top Of PageExample 4: PerfectCall Call Analysis (Synchronous Mode)

Top Of PageErrors

If this function returns -1 to indicate failure, call the SRL Standard Attribute function ATDV_LASTERR( ) to obtain the error code, or use ATDV_ERRMSGP( ) to obtain a descriptive error message. The error codes returned by ATDV_LASTERR( ) are described in Appendix B.

Top Of PageSee Also

Retrieving termination reasons and events for dx_dial( ) with Call Analysis:

Retrieving termination reasons for dx_dial( ) without Call Analysis:

Call Analysis:


Previous PageTable Of ContentsTop Of PageIndexNext Page

Click here to contact Dialogic Customer Engineering

Copyright 2001, Dialogic Corporation
All rights reserved
This page generated November, 2001