adiStartCallProgress

Starts monitoring call progress analysis data.

Supported board types

Prototype

DWORD adiStartCallProgress ( CTAHD ctahd, ADI_CALLPROG_PARMS *parms)

Argument

Description

ctahd

Context handle returned by ctaCreateContext or ctaAttachContext.

parms

Pointer to call progress analysis parameters, stored in the ADI_CALLPROG_PARMS, as follows (NULL designates default values):

typedef struct
{
  DWORD size;          // Size of this structure
  DWORD timeout;       // If no tone/voice detected, done via timeout (ms)
  DWORD busycount;     // Number of busy cycles until report and quit;
                       // busycount ignored if precise busy detected.
  DWORD ringcount;     // Number of ring cycles until report and quit.
  DWORD maxreorder;    // Separates fast busy from busy (ms)
  DWORD maxbusy;       // Separates busy from ring cycle (ms)
  DWORD maxring;       // Separates ring from dial tones (ms)
  DWORD maxringperiod; // Maximum ring period before CP_RING_QUIT (ms)
  DWORD voicemedium;   // Time after VOICE BEGIN until VOICE MEDIUM (ms)
  DWORD voicelong;     // Time after VOICE BEGIN until VOICE LONG (ms)
  DWORD voicextended; // Time after VOICE BEGIN until VOICE EXTENDED (ms)
  DWORD silencetime;   // Silence period after voice til VOICE END (ms)
  DWORD precqualtime; // Precise tone qualification time (ms)
  DWORD precmask;      // Precise tone mask
  DWORD stopmask;      // mask to auto-stop adiCallProgress:
  INT32 silencelevel; // Reference level below which is "silence" (dBm)
  DWORD voicetoneratio;// voice vs. tone ratio (IDUs)
  DWORD qualtonetime1; // Qualify time 1 for the TONE state (ms);
  DWORD qualtonetime2; // Qualify time 2 for the TONE state (ms);
  DWORD qualvoicetime1;// Qualify time 1 for the VOICE state (ms);
  DWORD qualvoicetime2;// Qualify time 2 for the VOICE state (ms);
  DWORD leakagetime;   // Leaky integrator time constant (in ms)
  DWORD noiselevel;    // Level window for QT2 state (in IDUs)
} ADI_CALLPROG_PARMS;

Refer to ADI_CALLPROG_PARMS for field descriptions.

Return values

Return value	Description
SUCCESS
CTAERR_BAD_ARGUMENT	Function argument had an invalid value, or a required pointer argument was NULL.
CTAERR_FUNCTION_ACTIVE	Function already started.
CTAERR_INVALID_CTAHD	Context handle is invalid.
CTAERR_INVALID_STATE	Function not valid in the current port state.
CTAERR_SVR_COMM	Server communication error.

Events

Event	Description
ADIEVN_CP_BUSYTONE	Detected a busy tone.
ADIEVN_CP_CED	Detected a called party modem or fax terminal tone.
ADIEVN_CP_DIALTONE	Detected a dial tone.
ADIEVN_CP_DONE	Call progress analysis terminated normally. The event value field can contain one of the following termination conditions or an error code: CTA_REASON_FINISHED CTA_REASON_TIMEOUT CTA_REASON_RELEASED CTA_REASON_STOPPED
ADIEVN_CP_NOANSWER	Detected no answer. The parameterized number of rings were detected without voice being detected.
ADIEVN_CP_RINGQUIT	Call progress analysis stopped detecting ring tones. Ring was previously detected and another ring was not detected in time. The cause can be a network error or a soft speaker answering the phone.
ADIEVN_CP_RINGTONE	Detected ring tone.
ADIEVN_CP_REORDERTONE	Detected a reorder (fast-busy) tone.
ADIEVN_CP_SIT	Detected a special information tone (SIT). If ADI_CPMSK_PRECISE_SITEXT is set in precmask, the low order three bits in the event value field indicate the type of SIT detected: 001 = intercept 011 = reorder; ineffective other 101 = vacant code 111 = no circuit available
ADIEVN_CP_STOPPED	Call progress analysis terminated by the application.
ADIEVN_CP_TDD	Detected a TDD/TTY device tone.
ADIEVN_CP_VOICE	Call progress analysis detected voice. The event value field contains one of the following: ADI_CP_VOICE_BEGIN ADI_CP_VOICE_MEDIUM ADI_CP_VOICE_LONG ADI_CP_VOICE_EXTENDED ADI_CP_VOICE_END

Details

The following DSP files must be loaded to the board before running adiStartCallProgress:

For these boards...

Load these DSP files...

callp.m54

ptf.m54

callp.f54

ptf.f54

Refer to DSP file summary for DSP descriptions. Refer to the board installation and developer's manual for a table of MIPS usage for all functions.

Use this function to start the call progress analysis operation. This is the same functionality utilized by call control. It can be used by applications that are not using standard call control, or by any application during the connected state.

Caution:

Modifying the following fields in ADI_CALLPROG_PARMS can compromise your application's ability to interact with the telephone network:

voicetoneratio

qualtonetime1

qualtonetime2

qualvoicetime1

qualvoicetime2

leakagetime

noiselevel

The call progress analysis operation always terminates when any of the following events occurs:

ADIEVN_CP_DIALTONE
ADIEVN_CP_BUSYTONE
ADIEVN_CP_RORDTONE
ADIEVN_CP_SIT
ADIEVN_CP_NOANSWER
ADIEVN_CP_CED
ADIEVN_CP_TDD

You can configure the ADI_CALLPROG_PARMS stopmask parameter to stop when any of the following events occur:

ADIEVN_CP_RINGTONE
ADIEVN_CP_RINGQUIT
ADIEVN_CP_VOICE_BEGIN
ADIEVN_CP_VOICE_MEDIUM
ADIEVN_CP_VOICE_LONG
ADIEVN_CP_VOICE_EXTENDED
ADIEVN_CP_VOICE_END

Example

/* Wait for voice detection or any network tone.
* Returns SUCCESS if voice is detected within 30 seconds, else DISCONNECT.
*/
int waitforvoice( CTAHD ctahd )
{
  ADI_CALLPROG_PARMS    parms;
  CTA_EVENT             event;
  DWORD                 last_cp_event = 0;

  ctaGetParms (ctahd, ADI_CALLPROG_PARMID, &parms, sizeof parms);
  parms.stopmask |= ADI_CPSTOP_ON_VOICE_BEGIN;
  parms.timeout = 30000;      /* Increase timeout from default 10 seconds */

  if( adiStartCallProgress (ctahd, &parms) != SUCCESS )
      return MYFAILURE;

  do
  {
      myGetEvent( &event );                  /* see ctaWaitEvent example */

      if (ADIEVN_CP_VOICE <= event.id && event.id <= ADIEVN_CP_CED)
            last_cp_event = event.id;

  } while (event.id != ADIEVN_CP_DONE);

  switch (event.value)
  {
      case CTA_REASON_FINISHED:
          if (last_cp_event == ADIEVN_CP_VOICE)
              return SUCCESS;
          else
              return MYDISCONNECT;             /* hang-up tone detected */

      case CTA_REASON_TIMEOUT:            /* nothing detected - give up */
      case CTA_REASON_RELEASED:              /* The call was terminated */
      case CTA_REASON_STOPPED:
      default:
          return MYDISCONNECT;
  }
}