Retrieves a snapshot of the call control status and stores it in an ADI_CALL_STATUS structure.

Note: This function and all other ADI call control functions have been superseded by the NCC service. For more information, see the Natural Call Control Service Developer's Reference Manual.

DWORD adiGetCallStatus ( CTAHD ctahd,
ADI_CALL_STATUS *status,
unsigned size )

ctahd CTA context handle returned by ctaCreateContext.

status Pointer to the ADI_CALL_STATUS structure, as shown:

typedef struct
{ /* Used by adiGetCallStatus */
DWORD size; /* Size returned by adiGetCallStatus */
DWORD state; /* Call states (ADI_CC_STATE_xxx) */
INT32 reason; /* Reason for going back to IDLE state */
char calledaddr [ADI_MAX_DIGITS+1];
/*DNIS info, called no. */
/* (null-terminated string) */
char callingaddr[ADI_MAX_DIGITS+1];
/*ANI info, calling no. */
/* (null-terminated string) */
char callingname[ADI_MAX_CNAME+1];
/* Calling party name */
DWORD pendingcommand; /* Current unacknowledged command */
char usercategory; /* User category of the calling party */
char tollcategory; /* Toll category (generally same as */
/* usercategory) */
BYTE stream; /* MVIP address of B channel */
BYTE timeslot; /* MVIP address of B channel */
WORD billingrate; /* Billing rate of call */
char callednumplan; /* Q.931 numbering plan ID of */
/* called number (if supported) */
char callednumtype; /* Q.931 number type of */
/* called number (if supported) */
char callingnumplan; /* Q.931 numbering plan ID of */
/* calling number (if supported) */
char callingnumtype; /* Q.931 number type of */
/* calling number (if supported) */
char callingpres; /* Caller ID presentation indicator */
char callingscreen; /* Q.931 ANI screening indicator */
char progressdescr; /* Progress descriptor */
char releasecause; /* Cause for call release */

char redirectingaddr[ADI_MAX_DIGITS+1];
/* Redirecting no. info */
char redirectingplan; /* Q.931 numbering plan ID of */
/* redirecting number (if supported) */
char redirectingtype; /* Q.931 number type of */
/* redirecting number (if supported) */
char redirectingpres; /* Redirecting number presentation */
/* indicator */
char redirectingscreen;
/* Q.931 redirecting number screen */
/* indicator */
char redirectingreason;
/* Q.931 reason for redirection */
char originalcalledaddr [ADI_MAX_DIGITS+1];
/* (For future use) */
char UUI[132]; /* User-to-user information */
/* (132 chars max) */
} ADI_CALL_STATUS;

size Size (in bytes) of the user-supplied status information space.

• SUCCESS
• CTAERR_BAD_ARGUMENT
  status pointer is NULL.
• CTAERR_BAD_SIZE
  size is smaller than the size of DWORD.
• CTAERR_FUNCTION_NOT_ACTIVE
  This error is returned when a function call is made to ADI call control when the NCC service is active.
• CTAERR_INVALID_CTAHD
• CTAERR_INVALID_STATE

None.

This function retrieves the call control status of the current or most recent call. Upon returning from the function, the ADI_CALL_STATUS size field contains the actual number of bytes written. For incoming calls, invoke adiGetCallStatus after receiving the ADIEVN_INCOMING_CALL event.

Caller ID data is written to the ADI_CALL_STATUS structure. Specific details about caller ID data is protocol-dependent, but in general, an application needs to analyze the call status for every incoming call.

Another trigger for calling this function is reception of ADIEVN_STATUSINFO_UPDATE, an asynchronous event which informs the application that a field has changed in the call status structure.

The ADI_CALL_STATUS structure contains the following fields:

Field	Description
size	Number of bytes written at the address pointed to by the status argument in adiGetCallStatus.
state	Current call control state: ADI_CC_STATE_xxx (refer to the ADI Service Developer's Manual for more details about call control).
reason	Reason for the last disconnect (return to Idle state). reason is 0 if the application initiated the disconnect. Otherwise, reason is the value received in the ADIEVN_CALL_ DISCONNECTED event.
calledaddr	For inbound calls, the called party address (DNIS information). This null-terminated string is formatted differently for different protocols.
callingaddr	For inbound calls, the calling party address - the Automatic Number Identification (ANI) digits. This string is formatted differently for different protocols.
callingname	Calling party name. Always empty for AG ISDN.
pendingcommand	The last call control command issued that has not yet been acknowledged by the TCP. This field is set when a call control command is sent to the AG board. The field is cleared on the next event that causes a transition to a new call state. Possible values are: Value Description 0 No command pending. 1 ADI_PENDCMD_PLACE_CALL 2 ADI_PENDCMD_ANSWER_CALL 3 ADI_PENDCMD_REJECT_CALL 4 ADI_PENDCMD_RELEASE_CALL 5 ADI_PENDCMD_TRANSFER_CALL 6 ADI_PENDCMD_PLACE_SECOND 7 ADI_PENDCMD_RELEASE_SECOND 8 ADI_PENDCMD_ACCEPT_CALL
usercategory	User category of the incoming call. Reported by some CAS protocols. Not used by AG ISDN.
tollcategory	Toll category of the incoming call. Reported by some CAS protocols. Not used by AG ISDN.
stream	Stream and timeslot together indicate the MVIP address of the B channel. Use if the TCP is in Non-Exclusive Mode. For more information, see the AG ISDN for Natural Call Control Developer's Manual.
timeslot	This field and stream together indicate the MVIP address of the B channel. Use if the TCP is in Non-Exclusive Mode. For more information, see the AG ISDN for Natural Call Control Developer's Manual.
billingrate	Billing rate of call.
callednumplan	(ISDN only) Q.931 numbering plan ID of called address (if supported).
callednumtype	(ISDN only) Q.931 type of called address (if supported).
callingnumplan	(ISDN only) Q.931 numbering plan ID of calling address (if supported).
callingnumtype	(ISDN only) Q.931 type of calling address (if supported).
callingpres	Presentation indicator for calling address. Used with Q.931 and certain digital CAS protocols.
callingscreen	(ISDN only) Q.931 screening indicator.
progressdescr	(ISDN only) Cause for progress message.
releasecause	(ISDN only) Cause for call release.
redirectingaddr	(ISDN only) The redirecting address.
redirectingplan	(ISDN only) Q.931 numbering plan ID of redirecting address (if supported).
redirectingtype	(ISDN only) Q.931 type of redirecting address (if supported).
redirectingpres	(ISDN only) Presentation indicator for redirecting address.
redirectingscreen	(ISDN only) Q.931 screening indicator for redirecting address (if supported).
redirectingreason	(ISDN only) Reason for redirection.
originalcalledaddr	Reserved for future use.
UUI	(ISDN only) User-to-user information (up to 132 characters).

For more information about controlling calls under specific TCPs, refer to the AG CAS for ADI Service Installation and Developer's Manual.

adiPlaceCall, adiAnswerCall, adiReleaseCall, adiTransferCall, adiPlaceSecondCall, adiReleaseSecondCall, adiRejectCall, adiBlockCalls, adiUnBlockCalls

void myShowCallState( CTAHD ctahd )
{
    ADI_CALL_STATUS call_status;

    adiGetCallStatus( ctahd, &call_status, sizeof call_status );
    switch( call_status.state )
    {
        case ADI_CC_STATE_STOPPED:       puts("Stopped/not active");     break;
        case ADI_CC_STATE_IDLE:          puts("Idle/active/waiting");    break;
        case ADI_CC_STATE_INCOMING_CALL: puts("Incoming call avail");    break;
        case ADI_CC_STATE_ACCEPTING_CALL:puts("Accepting call");         break;
        case ADI_CC_STATE_ANSWERING_CALL:puts("Answering call");         break;
        case ADI_CC_STATE_PLACING_CALL:  puts("Placing call");           break;
        case ADI_CC_STATE_DISCONNECTED:  puts("Remote disconnected");    break;
        case ADI_CC_STATE_BLOCKING:      puts("App blocking calls");     break;
        case ADI_CC_STATE_CONNECTED:     puts("Connected/conversation"); break;
        case ADI_CC_STATE_REJECTING_CALL:puts("Rejecting incoming call");break;
        case ADI_CC_STATE_OUT_OF_SERVICE:puts("Line out-of-service");    break;
        case ADI_CC_STATE_PLACING_CALL2: puts("Placing 2nd call/xfer");  break;
        case ADI_CC_STATE_CONNECTED2:    puts("Connected to 2nd call");  break;
    }
}