6.1 Introduction

6.2 Getting Line Status Information

6.3 Getting Call Status Information

6.4 Getting Extended Call Status Information

6.5 Status Change Notifications

6.5.1 Calling Address Information Changes

6.5.2 Protocol-Specific Call Status Information Changes

6.1 Introduction

This chapter describes how an application can access status information using NCC service functions.

The following status information is available:

• Line status: the current state of the line, the name of the protocol running on the line, etc.

• Call status: the current call state, calling address (caller ID), etc.

• Call status information specific to the protocol.

The following NCC functions provide these services:

If you want to...	Then use...
Get line status information	nccGetLineStatus
Get call status information	nccGetCallStatus
Get protocol-specific call status information	nccGetExtendedCallStatus

6.2 Getting Line Status Information

To get status information on a line, the application can invoke nccGetLineStatus with the line handle. This synchronous function can be called at any time, regardless of the line state or call state.

Line status information is returned in an NCC_LINE_STATUS structure. The structure looks like this:

typedef struct
{
  DWORD size;          /* No of bytes written to by linestatus     */ 
  DWORD state;         /* Current state of line                    */ 
  DWORD pendingcmd;    /* Last command not ack'd by board          */ 
  char protocol[NCC_MAX_PNAME+1]; /* Array of protocols on line    */ 
  CTA_MVIP_ADDR port;  /* MVIP address of port                     */ 
  unsigned numcallhd;  /* Number of unreleased call handles        */ 
} NCC_LINE_STATUS; 

The NCC_LINE_STATUS structure contains the following fields:

Field	Description
size	Number of bytes written at the address pointed to by linestatus argument (passed in nccGetLineStatus function invocation).
state	Current line state. Can be any of the following: NCC_LINESTATE_UNINITIALIZED NCC_LINESTATE_IDLE NCC_LINESTATE_BLOCKING NCC_LINESTATE_OUT_OF_SERVICE NCC_LINESTATE_ACTIVE
pendingcmd	The last line command issued that has not yet been acknowledged by the AG board. This field is set when a line control command is sent to the board, and cleared on the next event that corresponds to the acknowledgment of the pending command. Possible values are: (0) No command pending. NCC_PENDINGCMD_BLOCK_CALLS NCC_PENDINGCMD_UNBLOCK_CALLS NCC_PENDINGCMD_START_PROTOCOL NCC_PENDINGCMD_STOP_PROTOCOL
protocol	Arrays containing names of protocols running on this line.
port	MVIP address of call control resource (port), if needed, specified with ctaOpenServices invocation.
numcallhd	Number of unreleased call handles, starting from index 0.

6.3 Getting Call Status Information

To get status information on a line, the application can invoke nccGetCallStatus with the call handle. This synchronous function can be invoked in any call state, as long as the line is in an active or an idle line state.

Call status information is returned in an NCC_CALL_STATUS structure. The structure looks like this:

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;

The NCC_CALL_STATUS structure contains the following fields:

Field	Description
size	Number of bytes written at the address pointed to by callstatus argument (passed in nccGetCallStatus function invocation).
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	(Inbound calls) The address of the requested number if provided (for example, DNIS, DID).
callingaddr	(Inbound calls) The address of the caller, if provided (for example, caller ID, ANI).
callingname	(Inbound calls) The name information of the caller, if provided.
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 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: NCC_CALL_INBOUND NCC_CALL_OUTBOUND
linehd	Line (context) handle on which the call resides.

6.4 Getting Extended Call Status Information

With certain protocols, the application can retrieve a separate structure containing protocol-specific call control status information. (The application can invoke nccQueryCapability to determine if the protocol supports this feature.) This information may include billing rates, user-to-user information (UUI), etc. To learn more about the structure specific to your protocol, see your protocol-specific documentation.

To retrieve a structure containing protocol-specific information, the application invokes nccGetExtendedCallStatus. This synchronous function can be invoked in any call state, as long as the line state is active or idle.

6.5 Status Change Notifications

The application may receive events indicating that status information has changed. The following sections describe these events.

6.5.1 Calling Address Information Changes

If the calling address information (caller ID) changes, the application receives NCCEVN_CALL_STATUS_UPDATE. This event can occur in any call state, as long as the line state is Active or Idle. The value field of the event contains reason code NCC_CALL_STATUS_CALLINGADDR. The application can then invoke nccGetCallStatus to get the updated information.

Note: This event is generated only if the NCC_REPORT_STATUSINFO bit is set in the NCC.START.eventmask parameter (see Appendix C).

6.5.2 Protocol-Specific Call Status Information Changes

If protocol-specific call status information changes, the application receives NCCEVN_EXTENDED_CALL_STATUS_UPDATE. The application can then invoke nccGetExtendedCallStatus to get the updated information.

Note: This event is generated only if the NCC_REPORT_STATUSINFO bit is set in the NCC.START.eventmask parameter (see Appendix C).