# Retrieving call information

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

- NCC functions for retrieving call information

- NCC_CALL_STATUS structure

- NCC_CAS_EXT_CALL_STATUS structure

## 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:

- BellCore caller ID data

- NTT (Japan) caller ID data

- ETSI (France) caller ID data