Retrieving call information

The following information is useful when developing applications that retrieve status information about existing calls:

NCC functions for retrieving call information

To get call status information, the application can use the following NCC functions:

Function

Description

nccGetCallStatus

Returns an NCC_CALL_STATUS structure containing basic information about the call, such as the DID and ANI information, and whether or not the call is on hold.

nccGetExtendedCallStatus

Returns an NCC_CAS_EXT_CALL_STATUS structure containing other information about the call. For CAS, this information may include the user and toll category, and billing rate. The types of information received with this function differ from protocol to protocol.


Either of these synchronous functions can be invoked in any call state, as long as the line is in an active line state.

An application may also receive the unsolicited events NCCEVN_CALL_STATUS_UPDATE or NCCEVN_EXTENDED_CALL_STATUS_UPDATE while a particular call is still in progress. These events indicate a change in the status for the specified call. The application can examine the value field of the event for information about the type of status change that has occurred for the specific call. Then the application can invoke nccGetCallStatus or nccGetExtendedCallStatus to retrieve structures (NCC_CALL_STATUS or NCC_CAS_EXT_CALL_STATUS) that provide specific information about the call's status.

NCC_CALL_STATUS structure

nccGetCallStatus is a protocol independent NCC function that returns the following NCC_CALL_STATUS structure:

typedef struct
{     
          DWORD size ;
          DWORD state;
          char calledaddr [NCC_MAX_DIGITS+1];
          char callingaddr[NCC_MAX_DIGITS+1];
          char callingname[NCC_MAX_CALLINGNAME];
          DWORD pendingcmd;
          DWORD held;
          DWORD direction;
          CTAHD linehd;
} NCC_CALL_STATUS;

The NCC_CALL_STATUS structure contains the following fields:

Field

Description

size

Number of bytes written at the address pointed to by status.

state

Current call state. Valid states are:

NCC_CALLSTATE_INVALID
NCC_CALLSTATE_SEIZURE
NCC_CALLSTATE_RECEIVING_DIGITS
NCC_CALLSTATE_INCOMING
NCC_CALLSTATE_ACCEPTING
NCC_CALLSTATE_ANSWERING
NCC_CALLSTATE_REJECTING
NCC_CALLSTATE_CONNECTED
NCC_CALLSTATE_DISCONNECTED
NCC_CALLSTATE_OUTBOUND_INITIATED
NCC_CALLSTATE_PLACING
NCC_CALLSTATE_PROCEEDING

calledaddr

For inbound calls, the address of the requested number if provided (for example, DID).

callingaddr

For inbound calls, the address of the caller, if provided (for example, caller ID, ANI).

pendingcmd

The last call control command issued that has not yet been acknowledged by the board. This field is set when a call control command is sent to the board, and cleared on the next event that corresponding to the acknowledgment of the pending command.

Possible values are:

(0) No command pending.
NCC_PENDINGCMD_ACCEPT_CALL
NCC_PENDINGCMD_ANSWER_CALL
NCC_PENDINGCMD_AUTOMATIC_TRANSFER
NCC_PENDINGCMD_DISCONNECT_CALL
NCC_PENDINGCMD_HOLD_CALL
NCC_PENDINGCMD_PLACE_CALL
NCC_PENDINGCMD_REJECT_CALL
NCC_PENDINGCMD_RELEASED_CALL
NCC_PENDINGCMD_RETRIEVE_CALL
NCC_PENDINGCMD_TRANSFER_CALL
NCC_PENDINGCMD_SET_BILLING

held

Set to non-zero value when a call is held.

direction

Indicates inbound or outbound call. Possible values are:

NCC_CALL_INBOUND
NCC_CALL_OUTBOUND

 

linehd

Line (context) handle on which the call resides.


Note: NCC_CALL_STATUS fields are not guaranteed to be filled during call setup. The values of these fields depend on the information associated with the incoming call, and on the protocol used to set up the call.

NCC_CAS_EXT_CALL_STATUS structure

nccGetExtendedCallStatus returns the NCC_CAS_EXT_CALL_STATUS structure:

typedef struct
{
 DWORD size;
 char ANIpresentation;                    /* Set if the ANI presentation is restricted */
 char redirectingaddr [NCC_MAX_DIGITS+1]; /* Contains redirecting address information  */
 char redirectingreason;                  /* Contains the reason for redirection       */
 char usercategory;                       /* Contains the user category                */
 char tollcategory;                       /* Contains the toll category                */
 char carrierid [NCC_MAX_DIGITS+1];       /* Contains the carrier ID information       */
 WORD billingrate;                        /* Information passed with BILLING_SET event */
}NCC_CAS_EXT_CALL_STATUS;

The NCC_CAS_EXT_CALL_STATUS structure contains the following fields:

Field

Protocols that use the field

Description

ANIpresentation

MFC, EAM

Set if ANI presentation is restricted (caller ID information is restricted).

redirectingaddr

EUC (Sweden), LPS (with caller ID)

Redirecting number information (if the call has been redirected from another terminal).

redirectingreason

LPS (with caller ID)

Reason for call redirection (for example, busy, universal, or unanswered).

usercategory

MFC, EAM, R15, LPS (with caller ID)

Either the type of the calling party (for example, normal subscriber, operator, pay phone), or the type of call (protocol-specific).

tollcategory

MFC, EAM, LPS (with caller ID)

Generally the same as usercategory for MFC and EAM (it might be different for certain countries using the MFC-R2 protocol, if supported). For LPS, it is filled with the call qualifier information.

carrierid

FGD, LPS (with caller ID)

Carrier ID information. For LPS, it contains the first called line identity information.

billingrate

MFC, EAM

Indication if the current call is billed or free (for CAS protocols, the actual cost of an outbound call is calculated by counting billing pulses, if the network offers this service).


Note: Only a subset of NCC_CAS_EXT_CALL_STATUS fields are filled depending on the protocol used.

To verify whether specific fields are supported in your country, refer to: