NCC unsolicited events

Unsolicited events can occur at any time, regardless of the application's current activities. The following table lists the NCC unsolicited events:

Event

Description

NCCEVN_BILLING_INDICATION

Indicates that a billing indication was detected for an outbound call. This can be a billing pulse or some more complex indication. The event value field may contain the billing units charged, depending upon the protocol implementation.

This event is generated only if the NCC_REPORT_BILLING bit is set in the NCC.START.eventmask parameter.

NCCEVN_CALL_CONNECTED

Indicates that a call has reached the connected call state. The event value field contains the reason for connection.

NCCEVN_CALL_DISCONNECTED

This event indicates one of the following:

  • The application invoked nccDisconnectCall.

  • The remote party hung up. This event can occur in almost any call state.

  • The call is inbound, and the application rejected the call.

  • The call is outbound, the remote party answered, and the call failed to meet the criteria specified by the NCC_ADI_PLACECALL_PARMS connectmask passed with nccPlaceCall, or met the criteria specified by the disconnectmask.

The event value field contains the reason that the call was disconnected.

A disconnected call is no longer considered active. If there are no active calls on a line (all calls on the line are either held or disconnected), the line state returns to idle.

Disconnected calls should be released using nccReleaseCall.

NCCEVN_CALL_HELD

Indicates that a call has been placed on hold, either by the application or by a remote party. When a call is placed on hold, no call state change occurs. However, a call on hold is not considered active. If there are no active calls on a line (any calls on the line are either held or disconnected) the line state returns to idle.

Call holding is not supported by all protocols. The NCC_CAP_HOLD_CALL indicator in the capabilitymask returned by nccQueryCapability indicates if the current protocol supports this event or not.

Ordinarily, a call can only be placed on hold in the connected call state. However, if the NCC_CAP_HOLD_IN_ANY_STATE indicator is set in the capabilitymask for the protocol, the application can place a call on hold regardless of the call state.

The application can call nccGetCallStatus to determine whether a call is on hold or not. If a call is on hold, the held attribute in the NCC_CALL_STATUS structure returned for that call contains a non-zero value.

NCCEVN_CALL_PROCEEDING

Indicates that the switch has accepted the call setup request, and is in the process of attempting to ring the receiving end. Call progress analysis is begun. The call state changes to proceeding.

NCCEVN_CALL_RETRIEVED

Indicates that a call on hold was retrieved, either by the application or by a remote party. The call is now active. Since there is an active call on the line, the line state changes to active.

Call hold/retrieve is not supported by all protocols. NCC_CAP_HOLD_CALL in the capabilitymask returned by nccQueryCapability indicates if the current protocol supports this capability.

The application can call nccGetCallStatus to determine whether a call is on hold. If a call is on hold, the held attribute in the NCC_CALL_STATUS structure returned for that call contains a non-zero value.

If an automatic transfer fails, NCCEVN_CALL_RETRIEVED is returned, with a value field containing one of the NCC_DIS_xxx reason codes indicating why the transfer failed.

NCCEVN_CALL_STATUS_UPDATE

If call status information changes, the application receives this event. The event value field indicates the type of information that was changed. The application can then invoke nccGetCallStatus to get the updated information.

This event can occur in any call state, as long as the line state is active. It is generated only if the NCC_REPORT_STATUSINFO bit is set in the NCC.START.eventmask parameter.

NCCEVN_CAPABILITY_UPDATE

The application receives this event when the capabilities of a protocol change. The event value field indicates the capability that changed. The application can call nccQueryCapability to determine the current set of protocol capabilities.

NCCEVN_EXTENDED_CALL_STATUS_UPDATE

The application receives this event when protocol-specific call status information changes. The event value field indicates the kind of information that was changed. The application can then call nccGetExtendedCallStatus to retrieve this information.

This event is generated only if the NCC_REPORT_STATUSINFO bit is set in the NCC.START.eventmask parameter.

NCCEVN_INCOMING_CALL

Indicates that NCC detected an incoming call and all necessary call information (for example, digits) has been gathered. The call is now in the incoming call state. At this point, the application decides whether to accept, answer, or reject the call.

NCCEVN_LINE_IN_SERVICE

Indicates that an out-of-service line (a line in out-of-service line state) was placed in service. It is now in idle line state.

NCCEVN_LINE_OUT_OF_SERVICE

Indicates that a line was taken out of service. The event value field indicates the reason for taking the line out of service.

NCCEVN_PROTOCOL_ERROR

An error condition occurred. The call may be in an unusable state.

NCCEVN_PROTOCOL_EVENT

The protocol implementation generated an unsolicited event.

NCCEVN_RECEIVED_DIGIT

Indicates that a call address or subaddress digit has been received from the network. The application may receive several of these events, as digits are received in an overlapped fashion for an incoming call. The value field contains the digit. When the first digit is received, the call state changes from seizure to receiving digits. The call remains in this state until NCCEVN_INCOMING_CALL is received.

This event is generated only if the NCC_REPORT_DIGITS bit is set in the NCC.START.eventmask parameter.

NCCEVN_REJECTING_CALL

Either of the following has occurred:

  • The application has invoked nccRejectCall to reject an incoming call.

  • The application has failed to accept, answer, or reject an incoming call within the period of time specified by the NCC.START.waitforPCtime parameter.

The call enters the rejecting call state. The event value field contains the reason why the call was rejected.

NCCEVN_SEIZURE_DETECTED

Indicates that NCC has detected an incoming call. A call handle is created for the call. The call handle may now be used for all subsequent operations for this call. The new call begins in the seizure call state.