The following information is useful when developing applications that retrieve status information about existing calls:
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.
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 |
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. |
held |
Set to non-zero value when a call is held. |
direction |
Indicates inbound or outbound call. Possible values are: NCC_CALL_INBOUND
|
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.
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: