Places an outbound call.

DWORD adiPlaceCall( CTAHD ctahd,
char *digitstr,
ADI_PLACECALL_PARMS *parms )

ctahd Context handle returned by adiOpenPort.

digitstr Pointer to a NULL-terminated string containing the phone number to dial.

parms Pointer to an ADI_PLACECALL_PARMS structure, shown below (NULL uses default parameter values):

typedef struct
{
 DWORD size ; /* size of this structure             */
 DWORD connectmask; 
    /* events that transition to connected           */
 DWORD disconnectmask;
    /* events that transition to disconnected           */
 ADI_CALLPROG_PARMS callprog; 
    /* call progress analysis parameters           */
} ADI_PLACECALL_PARMS;

For the ADI_CALLPROG_PARMS structure, see the function adiStartCallProgress. See Appendix D for more details and default values.

• SUCCESS
• ADIERR_INVALID_CALL_STATE
• CTAERR_BAD_ARGUMENT
  digitstr is NULL
• CTAERR_INVALID_CTAHD
• CTAERR_INVALID_STATE

• ADIEVN_REMOTE_ALERTING
  This low-level event is generated when the first ring tone is detected. This event is generated only if the ADI_CC_REPTALERTING bit is set in the ADI_CALLCTL_PARMS eventmask passed to adiStartProtocol.
• ADIEVN_CALL_PROCEEDING
  This low-level event is generated after the digits have been delivered to the switch. This event is generated only if the ADI_CC_REPTPROCEEDING bit is set in the ADI_CALLCTL_PARMS eventmask passed to adiStartProtocol.
• ADIEVN_INCOMING_CALL
  Generated when an incoming call is detected. The application should proceed to process the incoming call.
• ADIEVN_PLACING_CALL
  Generated when the TCP has seized an outbound trunk and has resolved glare. The call control state changes to ADI_CC_STATE_PLACING_CALL. Except where noted in the disconnect event below, this event precedes all other events that can occur when placing a call.
• ADIEVN_REMOTE_ANSWERED
  This low-level event is generated at the first positive indication that the remote party has answered; e.g., out-of-band signaling, voice, or modem tone. This event is generated only if the ADI_CC_REPTANSWERED bit is set in the ADI_CALLCTL_PARMS eventmask passed to adiStartProtocol.
• ADIEVN_CALL_CONNECTED
  If the call is successfully placed, the connected event is generated and the call state transitions to the ADI_CC_STATE_CONNECTED state. The event value field contains the condition that satisfied the connection criteria, as listed below:
• ADI_CON_CED
  Fax terminal tone or modem tone was detected.
• ADI_CON_DIALTONE_DETECTED
  Detected dial tone while performing call analysis.
• ADI_CON_PROCEEDING
  Application forced connect after digits were delivered to the switch.
• ADI_CON_RING_QUIT
  Ring tone was detected but then stopped; nothing else detected.
• ADI_CON_SIGNAL
  Out-of-band signaling detection of remote answer.
• ADI_CON_SIT_DETECTED
  Detected special information tone (SIT).
• ADI_CON_TIMEOUT
  Nothing was detected. Assumption is that remote party answered before being alerted.
• ADI_CON_VOICE_BEGIN
  Voice was detected.
• ADI_CON_VOICE_END
  Silence detected after voice detected.
• ADI_CON_VOICE_EXTENDED
  Voice lasted for a specified (extended) duration.
• ADI_CON_VOICE_LONG
  Voice lasted for a specified (long) duration.
• ADI_CON_VOICE_MEDIUM
  Voice lasted for a specified (medium) duration.
• ADIEVN_CALL_DISCONNECTED
  A disconnected event is generated if AG Access fails to place the call because one of the disconnect criteria was met. The disconnected event transitions the call control state to the ADI_CC_STATE_DISCONNECTED. The reason for the disconnect is stored in the event value field, and can be one of the following:
• ADI_DIS_BUSY_DETECTED
  Detected a busy tone.
• ADI_DIS_CED
  Fax terminal tone or modem tone detected.
• ADI_DIS_DIALTONE_DETECTED
  Detected dial tone while performing call analysis.
• ADI_DIS_NO_DIALTONE
  No dial tone detected.
• ADI_DIS_NO_WINK
  Switch/CO is not responding to the seized line.
• ADI_DIS_REMOTE_NOANSWER
  No call progress analysis tones were detected after the call proceeding event.
• ADI_DIS_REORDER_DETECTED
  Detected reorder (fast busy) tone.
• ADI_DIS_RING_QUIT
  Ring tone was detected but stopped with no other call analysis events.
• ADI_DIS_SIGNAL
  Remote line picked up, then hung up before call analysis was done.
• ADI_DIS_SIT_DETECTED
  Detected special information tone (SIT).
• ADI_DIS_TIMEOUT
  No call analysis events for the parameterized time.

Each of the various connection reasons for voice are also available for disconnect. Other disconnect reasons are documented in the AG Access Developer's Manual and are also included in adidef.h.

digitstr may contain the following embedded escape characters which control the dialing sequence, as listed below:

Character	Description
;	(semicolon) Wait for precise dial tone.
.	(period) Insert long pause in dialing.
,	(comma) Insert short pause in dialing.
!	Flash-hook.
P	Switch to pulse dialing.
T	Switch to DTMF dialing.
M	Switch to MF dialing.

Note:	 When you place a call, the first event you receive is usually ADIEVN_PLACING_CALL. If call placement fails, you receive an ADIEVN_CALL_DISCONNECTED event with a value field of ADI_DIS_NO_DIALTONE or ADI_DIS_NO_WINK. If the port is a bi-directional trunk, ADIEVN_INCOMING_CALL may be received instead of ADIEVN_PLACING_CALL. If you receive an ADIEVN_INCOMING_CALL event, retry placing the outgoing call at a later time.

If an incoming call is detected during call placement, the application should proceed to process it.

Call placement and call control are discussed in detail in the AG Access Developer's Manual.

Note: This function is not available when using the NOCC protocol.

adiStartProtocol, adiReleaseCall, adiStartMFDetector (for MF table)

int myPlaceCall( CTAHD ctahd, char *digits, int accept_incoming )
{
    ADI_EVENT       event;

    adiPlaceCall( ctahd, digits, NULL );

    while( 1 )
    {
        myGetEvent( &event );           /* see adiFetchAndProcess example */

        switch( event.id )
        {
            case ADIEVN_INCOMING_CALL:      /* Now in the 'incoming call' state. */
                /*
                 * Glare: The protocol has detected an incoming call when we
                 * tried to place our call.
                 */
                if( accept_incoming )
                    adiAnswerCall( ctahd, 1 );
                else
                    adiRejectCall( ctahd, ADI_REJ_PLAY_REORDER );
                break;

            case ADIEVN_CALL_CONNECTED:    /* Now in the 'connected' state. */
                /*
                 * After PLACING_CALL, this event indicates that a specific
                 * connection criteria was met. For an INCOMING_CALL, this is
                 * reached when the specified number of rings have been
                 * detected/generated and the protocol has answered the call.
                 * Application is now in the 'connected' (conversation)
                 * state, and may play, record, collect DTMFs, etc.
                 * May also release the call to hang up or in response to the
                 * remote party hanging up.
                 */
                return SUCCESS;

            case ADIEVN_CALL_DISCONNECTED:  /* Now in the 'disconnected' state. */
                /*
                 * Before ANSWER_CALL or PLACING_CALL, indicates the network
                 * is not acknowledging outbound seizure. After PLACING_CALL,
                 * indicates that a specific disconnect criteria was met.
                 * After ANSWER_CALL, this is reached when the remote party
                 * hangs up during either the rejecting or answering states.
                 */
                return MYDISCONNECT;

            case ADIEVN_ANSWERING_CALL:     /* Now in the 'answering' state. */
            case ADIEVN_REJECTING_CALL:     /* Now in the 'rejecting' state. */
            default:
                break;
        }
    }
}