# NCC functions and solicited events

The following table lists NCC service functions and solicited events. Solicited events signify acknowledgments from the TCP of particular function calls. Functions are listed in alphabetical order. For detailed documentation of the functions, parameters, and events, refer to the Natural Call Control Service Developer's Reference Manual.

Function | Description and associated events
--- | ---
nccAcceptCall | Accepts an incoming call without answering or rejecting it. This allows the application to perform media functions (such as playing a voice file) before connecting (or rejecting) an inbound call. Note: Not all protocols support this function and the accepting state. The application can determine if the protocol supports this state by examining the NCC_CAP_ACCEPT_CALL bit in the capabilitymask returned by nccQueryCapability. If the remote party disconnects while the application accepts the call, then the application receives NCCEVN_CALL_DISCONNECTED. In this case, no NCCEVN_ACCEPTING_CALL event is delivered to the application. The application can accept a call using the following modes: NCC_ACCEPT_PLAY_SILENT: Do not play anything (digital trunks only). NCC_ACCEPT_PLAY_RING: Play a ring tone (works on all trunks). NCC_ACCEPT_USER_AUDIO: The application may generate a recorded message. If the remote party disconnects, the TCP interrupts the message (digital trunks only). Note: NCC_ACCEPT_PLAY_RING and NCC_ACCEPT_USER_AUDIO are not supported by all protocols. The application can determine if the protocol supports this capability by examining the NCC_CAP_MEDIA_IN_SETUP bit in the capabilitymask returned by nccQueryCapability. NCC_ACCEPT_PLAY_SILENT is the default accept mode supported by all protocols. Associated events: NCCEVN_ACCEPTING_CALL: The function has completed successfully and the call has entered the accepting call state. NCCEVN_CALL_DISCONNECTED: The remote party has disconnected. The call enters the disconnected call state.
nccAnswerCall | Answers an incoming call. If nccAnswerCall completes successfully, the call enters the answering call state. The application receives NCCEVN_ANSWERING_CALL. When the call is connected, the application receives NCCEVN_CALL_CONNECTED, and the call enters the connected call state. If the remote party disconnects while the call is in the answering call state, the application receives NCCEVN_CALL_DISCONNECTED. Associated events: NCCEVN_ANSWERING_CALL: The function has completed successfully and the call has entered the answering call state. NCCEVN_CALL_CONNECTED: The call is connected. The call enters the connected call state. NCCEVN_CALL_DISCONNECTED: The remote party has disconnected. The call enters the disconnected call state.
nccAutomaticTransfer | Transfers a call on a PBX, Centrex, or Centrex-like line. nccAutomaticTransfer executes a blind transfer by performing placement of a second call and completing call transfer. nccAutomaticTransfer operates only when the first call handle is in the connected state or is on hold. Note: Not all protocols support automatic call transfer. The application can determine if the protocol supports this state by examining the NCC_CAP_AUTOMATIC_TRANSFER bit in the capabilitymask returned by nccQueryCapability. The application determines when the call is to be transferred by specifying: NCC_TRANSFER_PROCEEDING: After the transfer address is dialed. NCC_TRANSFER_ALERTING: When a ring is detected. NCC_TRANSFER_CONNECTED: When called party answers. Associated events: NCCEVN_CALL_HELD: Indicates that the second call (to the transfer address) is in placing call state. NCCEVN_CALL_RETRIEVED: Indicates that the transfer failed. The event value field contains a NCC_DIS_xxx reason code indicating why the transfer failed. NCCEVN_CALL_DISCONNECTED: First call is in disconnected call state. Receipt of this event with reason code NCC_DIS_TRANSFER indicates successful completion of the automatic transfer. The application should release this call handle with nccReleaseCall. Note: Other protocol-specific errors or reasons for disconnecting may be reported.
nccBlockCalls | Blocks calls on a specified line handle. nccBlockCalls may be invoked from any line state, however, incoming calls will not be blocked until there are no calls on the line (the line has returned to idle line state). When using nccBlockCalls, specify the method to be used to block calls. Two methods are valid: NCC_BLOCK_REJECTALL: Do not answer subsequent calls. NCC_OUT_OF_SERVICE: Place the line out of service. When the line state has changed to blocking, the application receives NCCEVN_CALLS_BLOCKED. The value returned with this event contains the chosen blocking method. The line remains in the blocking state until nccUnblockCalls is called. The application may receive NCCEVN_INCOMING_CALL after invoking nccBlockCalls and before receiving NCCEVN_CALLS_BLOCKED. The application must handle the incoming call (accept it, answer it, etc.). The application will not receive the NCCEVN_CALLS_BLOCKED event until it releases all calls. If the blocking request fails for some reason, the application receives NCCEVN_BLOCK_FAILED. The line remains in the current state. nccUnBlockCalls can be used to cancel a blocking request initiated using nccBlockCalls. A blocking request can be canceled any time before NCCEVN_CALLS_BLOCKED is received. Associated events: NCCEVN_CALLS_BLOCKED: The block calls request completed successfully. The line state has changed to blocking. NCCEVN_BLOCK_FAILED: The request to block calls failed. The event value field contains the reason.
nccDisconnectCall | Disconnects a call that is connected to the network. nccDisconnectCall may also be used to abandon outbound call placement. The NCC_CAP_DISCONNECT_IN_ANY_STATE bit in the capabilitymask returned by nccQueryCapability determines the states in which nccDisconnectCall can be invoked. If the bit is set, nccDisconnectCall may be invoked in any call state except disconnected. If the bit is cleared, nccDisconnectCall can only be invoked in the connected call state. A disconnected call is no longer active. If no active calls exist on a line, the line state changes to idle. Associated event: NCCEVN_CALL_DISCONNECTED indicates that the disconnect operation has completed successfully and the call has entered the disconnected call state.
nccGetCallStatus | Retrieves the call control status and stores it in an NCC_CALL_STATUS structure. 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 once NCCEVN_INCOMING_CALL is received, or by waiting for NCCEVN_CALL_STATUS_UPDATE, with a value code of NCC_CALL_STATUS_CALLINGADDR. For more information, refer to the NCC_CALL_STATUS structure. Associated events: None.
nccGetExtendedCallStatus | Retrieves protocol-specific status information for a call and stores it in an NCC_CAS_EXT_CALL_STATUS structure. For more information, refer to the NCC_CAS_EXT_CALL_STATUS structure. Associated events: None.
nccGetLineStatus | Retrieves a snapshot of the port status and stores it in an NCC_LINE_STATUS structure. Associated events: None.
nccHoldCall | Puts a connected call on hold. There is no call state transition, but a call on hold is no longer active. Since there are no active calls currently on the line, the line state changes to idle. The call is on hold only after the application receives an NCCEVN_CALL_HELD event. The held field in the NCC_CALL_STATUS structure is set to a non-zero value. Use nccRetrieveCall to take the call off hold. Some protocols do not support the capability to put a call on hold. The application can determine if the protocol supports call hold/retrieve by examining the NCC_CAP_HOLD_CALL bit in the capabilitymask returned by nccQueryCapability. Some protocols allow a call to be put on hold only from the connected state. The application can determine whether or not a call can be put on hold from any state by examining the NCC_CAP_HOLD_IN_ANY_STATE bit in the capabilitymask returned by nccQueryCapability. Associated events: NCCEVN_CALL_HELD: The call hold attempt completed successfully and the call is now on hold. The line state is now idle. NCCEVN_HOLD_REJECTED: The request to put a call on hold was rejected. The value field contains information as to why the request was rejected.
nccPlaceCall | Places an outbound call to a specified digit string according to call placement parameters specified in NCC_ADI_PLACECALL_PARMS. NCCEVN_PLACING_CALL indicates that the call placement operation has completed successfully and the call has entered the placing call state. If the application receives NCCEVN_CALL_RELEASED (with an NCC_RELEASED_FALSE_SEIZURE reason code) instead of NCCEVN_PLACING_CALL, the line was seized for an incoming call before glare was resolved, and the TCP has released the outgoing call. The application should immediately abandon outbound call placement and handle the incoming call. The address digits can be sent all at once when invoking the function, or (with some protocols) digits can be sent in an overlapped fashion. Associated events: NCCEVN_PLACING_CALL: The TCP has seized an outbound trunk and resolved glare, and the call has entered the placing call state. NCCEVN_CALL_RELEASED: An incoming call was detected while call placement was taking place. The TCP has released the outbound call. The event value field contains NCC_RELEASED_GLARE. NCCEVN_CALL_PROCEEDING: The switch has accepted the call setup. The receiving side is being rung. The call enters the proceeding call state. NCCEVN_REMOTE_ALERTING: The remote end is in an alerting state (for example, is ringing). This event is generated only if the NCC_REPORT_ALERTING bit is set in the NCC.START.eventmask parameter. NCCEVN_REMOTE_ANSWERED: Generated at the first positive indication that the remote party has answered (for example, out-of-band signaling, voice, or modem tone). The event value field contains the indication type. This event is generated only if the NCC_REPORT_ANSWERED bit is set in the NCC.START.eventmask parameter. NCCEVN_CALL_CONNECTED: Both parties are now connected. The call enters the connected call state.
nccQueryCapability | Queries the capabilities of the protocol on a given line handle. The application can invoke this function to determine if the current protocol supports a given feature. nccQueryCapability returns an NCC_PROT_CAP structure containing capability information for the protocol. Associated events: None.
nccRejectCall | Rejects an incoming call. nccRejectCall causes the protocol to reject the incoming call using the method specified by method. Valid methods are: NCC_REJECT_PLAY_RINGTONE: Play ring tone (only option on analog trunks). NCC_REJECT_PLAY_BUSY: Plays a busy tone (digital trunks only). NCC_REJECT_PLAY_REORDER: Plays a reorder tone (digital trunks only). NCC_REJECT_USER_AUDIO: The application generates a recorded message, or a special information tone. If the remote party hangs up, the TCP interrupts the application tone or voice file (digital trunks only). When a call is being rejected, the application receives NCCEVN_REJECTING_CALL. To use the default rejection behavior for the current protocol, set method to 0. Note: If the remote party disconnects while the application is rejecting the call, the application receives NCCEVN_CALL_DISCONNECTED only. In this case, NCCEVN_REJECTING_CALL is not delivered. Associated events: NCCEVN_REJECTING_CALL: The reject call operation has completed successfully and the call has entered the rejecting call state. NCCEVN_CALL_DISCONNECTED: The remote party disconnected.
nccReleaseCall | Releases resources associated with a call in the disconnected state, and destroys a call handle. nccReleaseCall can only be called when a call is in the disconnected state. When a call is released, it is completely destroyed. The application can no longer retrieve call status information. Associated event: NCCEVN_CALL_RELEASED is returned after the protocol has performed the network procedures for releasing the call. All internal resources allocated to the call are released. After the application receives this event, no more DSP-related events are generated for this call handle.
nccRetrieveCall | Retrieves a call previously placed on hold with nccHoldCall. The call becomes active again. The line state changes to active. Associated events: NCCEVN_CALL_RETRIEVED: The call retrieve attempt completed successfully and the call is now no longer on hold. NCCEVN_RETRIEVE_REJECTED: The request to retrieve the call was rejected.
nccSendCallMessage | Pass through mechanism to send a protocol-specific call message directly to the TCP. Not used for CAS protocols. Associated events: None.
nccSendDigits | Continues the process of sending digits to place an outbound call (for protocols that support overlapped sending of digits). Associated events: None.
nccSendLineMessage | Pass through mechanism to send a protocol-specific line message. Not used for CAS protocols. Associated events: None.
nccStartProtocol | Prepares an uninitialized line to be used by a protocol to accept and/or place calls. When invoked, nccStartProtocol returns NCCEVN_START_PROTOCOL_DONE. This event acknowledges the protocol startup attempt. The event value field indicates whether the attempt was successful or not. Associated event: NCCEVN_START_PROTOCOL_DONE: Acknowledges the attempt by the application to start a protocol on a context (line handle). The event value field indicates if the protocol was started or not. The following reason codes may be returned: CTA_REASON_FINISHED indicates that the protocol has successfully been started on a context (line handle). The line state changes from uninitialized to idle. NCCREASON_OUT_OF_RESOURCES indicates that the protocol has not been started, because the mediamask parameter is not set correctly. The line remains in uninitialized line state. See the hardware documentation for details.
nccStopProtocol | Uninitializes an NCC line. If this command succeeds, the line state becomes uninitialized. Any calls that are on the line are released. An NCCEVN_CALL_RELEASED event is generated for each released call. Then an NCCEVN_STOP_PROTOCOL_DONE event is returned. Associated events: NCCEVN_START_PROTOCOL_DONE: The line state has successfully changed from idle to uninitialized. It can no longer be used to accept and/or place calls. NCCEVN_CALL_RELEASED: A call that was on the line was released before the protocol was stopped.
nccTransferCall | Completes supervised transfer of two calls. Only one of the two call handles can be in the connected state and not be on hold. Both calls must be on the same line (context) handle. When the transfer is completed, the application should invoke nccReleaseCall for both call handles to release their resources. Note: Not all protocols support supervised call transfer. The application can determine if the protocol supports this state by examining the NCC_CAP_SUPERVISED_TRANSFER bit in the capabilitymask returned by nccQueryCapability. When the transfer is completed, call nccReleaseCall to go back to the idle state. Associated event: NCCEVN_CALL_DISCONNECTED should be returned twice, once for each call. The event indicates that the call is disconnected (from the point of view of the application). If the call transfer is successful, the NCC_DIS_TRANSFER reason code is returned with this event. Other protocol-specific reason codes may be reported for failure to complete transfer. The CTA_EVENT structure containing this event also contains the first call handle (callhd1) of the nccTransferCall invocation.
nccUnBlockCalls | Used to release blocking of calls on the specified line (context) handle. When the line state has changed from blocking to idle, the application receives NCCEVN_CALLS_UNBLOCKED. It can then receive or place new calls. nccUnblockCalls may be used to cancel a previous nccBlockCalls invocation before the protocol is able to start blocking calls on the specified line. In this case, the application receives no events. If the call unblocking request fails for some reason, the application receives NCCEVN_UNBLOCK_FAILED. The line remains in the blocking line state. Associated events: NCCEVN_CALLS_UNBLOCKED: The unblock calls request completed successfully. The line state has changed to Idle. NCCEVN_UNBLOCK_FAILED: The request to unblock calls failed. The event value field contains the reason.

The NCC.START.eventmask parameter dictates whether certain informational call control events are generated. For detailed information about this structure, refer to the Natural Call Control Service Developer's Reference Manual.