nccGetCallStatus

Retrieves the call control status and stores it in an NCC_CALL_STATUS structure.

Prototype

DWORD nccGetCallStatus ( NCC_CALLHD callhd, NCC_CALL_STATUS *callstatus, unsigned size )

Argument

Description

callhd

Handle of the call for which you want to retrieve status information.

callstatus

A pointer to the NCC_CALL_STATUS structure to receive the call status:

typedef struct
{
 DWORD size;         /* No of bytes written to by callstatus    */ 
 DWORD state;        /* Current call state                      */ 
 char calledaddr [NCC_MAX_DIGITS+1]; /* Called number address   */ 
 char callingaddr[NCC_MAX_DIGITS+1]; /* Calling number address  */ 
 char callingname[NCC_MAX_CALLING_NAME]; /* Calling name info   */ 
 DWORD pendingcmd;   /* Last command not ack'ed by board        */ 
 DWORD held;         /* Non--zero value when call is held       */ 
 DWORD direction;    /* Indicates inbound or outbound call      */ 
 CTAHD linehd;       /* Line handle on which call resides       */ 
} NCC_CALL_STATUS;
 

See the Details section for field descriptions.

size

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

Return values

Return value

Description

SUCCESS

 

CTAERR_BAD_ARGUMENT

The status pointer is NULL.

CTAERR_INVALID_HANDLE

The call handle is not valid. It may have been released.

CTAERR_SVR_COMM

A server communication error occurred.

Details

nccGetCallStatus retrieves the status of a specified call. When the function returns, the NCC_CALL_STATUS size field contains the actual number of bytes written.

Caller ID data is written to the NCC_CALL_STATUS structure. Applications that require caller ID data can check the calling party's ID by invoking nccGetCallStatus after NCCEVN_INCOMING_CALL is received, or by waiting for NCCEVN_CALL_STATUS_UPDATE, with a value code of NCC_CALL_STATUS_CALLINGADDR.

The NCC_CALL_STATUS structure contains the following fields:

Field

Description

size

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

state

Current call state. Possible state values 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, DNIS, DID).

callingaddr

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

callingname

For inbound calls, the name information of the caller, if provided.

pendingcmd

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

Possible pendingcmd 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_RETRIEVE_CALL

  • NCC_PENDINGCMD_SET_BILLING

  • NCC_PENDINGCMD_TRANSFER_CALL

  • NCC_PENDINGCMD_RELEASE_CALL

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.

See also

nccGetExtendedCallStatus, nccGetLineStatus