5.1 Introduction

5.2 Call Hold and Retrieve

5.2.1 Placing a Call on Hold

5.2.2 Retrieving a Held Call

5.2.3 Unsolicited Hold/Retrieve Events

5.3 Transferring Calls

5.3.1 Supervised Transfer

5.3.2 Blind (Automatic) Transfer

5.4 Blocking and Unblocking Calls

5.4.1 Blocking Calls

5.4.2 Unblocking Calls

5.1 Introduction

This chapter describes secondary call control functions using the NCC service:

• Call hold and retrieve

• Supervised transfer

• Blind transfer

• Call blocking and unblocking

The following NCC functions provide these services:

If you want to...	Then use...
Place a call on hold	nccHoldCall
Retrieve a call placed on hold	nccRetrieveCall
Direct the switch to transfer a call	nccAutomaticTransfer
Transfer a call (application-controlled)	nccTransferCall
Block all calls on a line	nccBlockCalls
Remove blocking on a line	nccUnblockCalls

5.2 Call Hold and Retrieve

The NCC service supports the ability to place a call on hold, and to retrieve a held call (make it no longer on hold). Placing a call on hold frees the NCC service call control resources to establish another call connection.

Placing a call on hold does not change the call state. However, a call on hold is no longer active. Since there are no active calls currently on the line, the line state changes to idle.

Not all protocols support call hold/retrieve. The NCC_CAP_HOLD_CALL bit in the capabilitymask returned by nccQueryCapability indicates if the protocol supports call hold/retrieve or not.

Several calls can be on hold on any given line. However, only one call on a line may be active at any given time.

5.2.1 Placing a Call on Hold

To place a call on hold, the application invokes nccHoldCall with the handle of the call. When the application receives an NCCEVN_CALL_HELD event, the call is on hold. There is no call state transition. However, the line state goes to Idle.

A call may be put on hold only from the connected state, unless the capability bit NCC_CAP_HOLD_IN_ANY_STATE is set in the capabilitymask retrieved via the nccQueryCapability function. If the bit is set, the call can be put on hold from any state, and change states while on hold.

The application may perform media functions on the held call (for example, play a user voice file, or silence) using a CT Access media service. Depending upon the capabilities of the protocol, the application may also transfer a held call.

5.2.2 Retrieving a Held Call

To retrieve a held call, the application invokes nccRetrieveCall with the handle of the call. When the application receives an NCCEVN_CALL_RETRIEVED event, the call is retrieved. There is no call state transition. However, the line state returns to active.

A held call may be retrieved only if it is in the connected state, unless the capability bit NCC_CAP_HOLD_IN_ANY_STATE is set in the capabilitymask. The capabilitymask is retrieved via the nccQueryCapability function.

5.2.3 Unsolicited Hold/Retrieve Events

Some protocols allow calls to be held/retrieved remotely. A call is held when an unsolicited NCCEVN_CALL_HELD event is received. The call is retrieved when an unsolicited NCCEVN_CALL_RETRIEVED event is received.

5.3 Transferring Calls

The NCC service supports the ability to transfer calls from a first party to a second party through a switch (for example, Private Branch Exchange (PBX), Centrex, or Centrex-like exchange). Two call transfer methods are supported:

• Supervised transfer using nccTransferCall. In this method, the application performs the transfer process.

• Blind, or automatic transfer using nccAutomaticTransfer. In this method, the application requests the switch to perform the transfer.

Not all protocols support blind and/or supervised call transfer. The NCC_CAP_SUPERVISED_TRANSFER bit in the capabilitymask returned by nccQueryCapability indicates if supervised call transfer is supported or not. NCC_CAP_AUTOMATIC_TRANSFER indicates if blind call transfer is supported or not.

5.3.1 Supervised Transfer

The supervised transfer method allows the application to control the transfer process.

Before the application can perform a supervised transfer, both of the calls to be connected must be in the connected state. One call must be on hold. The other call must not be on hold.

The NCC service does not support supervised transfer of calls on different lines. To transfer calls on different lines, use the blind, or automatic transfer method described in Section 5.3.2.

To perform the transfer, the application invokes nccTransferCall with the handles of the two calls. If the transfer completes successfully, the application receives two NCCEVN_CALL_DISCONNECTED events, one for each call. The value field of each event contains NCC_DIS_TRANSFER. As the event is returned for each call, the call enters the disconnected state from the point of view of the application. The application should invoke nccReleaseCall for each call handle, to destroy the handle and release resources. NCCEVN_CALL_RELEASED indicates that a call has been released.

If the transfer does not complete successfully, the application receives NCCEVN_CALL_DISCONNECTED events, with protocol-specific values. See your protocol-specific documentation for details.

Note that not all protocols support supervised call transfer. The NCC_CAP_SUPERVISED_TRANSFER bit in the capabilitymask returned by nccQueryCapability indicates if supervised call transfer is supported or not.

5.3.2 Blind (Automatic) Transfer

With the blind, or automatic, transfer method, the application requests the switch (a PBX, Centrex, or Centrex-like switch) to perform a call transfer. Only one party is in the connected state. A call is automatically placed to a second party. If the call succeeds, the transfer is automatically completed.

To perform the transfer, the application invokes nccAutomaticTransfer, with the handle of the current call, and the address of the party to transfer to (the party's extension). The current call must not be on hold. When invoking the function, the application specifies at what point the transfer is to take place. Three possibilities are supported:

Value	Transfer takes place...
NCC_TRANSFER_PROCEEDING	After the address is sent, and the switch has accepted the calls the request (the call is in proceeding call state)
NCC_TRANSFER_ALERTING	When the remote end is alerting.
NCC_TRANSFER_CONNECTED	When the second call reaches the connected state.

The automatic transfer function works as follows:

1. The function places the first party on hold. When this occurs, NCCEVN_CALL_HELD is returned to the application.

2. The function then attempts to place a second call to the specified address.

3. If the placed call reaches the stage specified as the point at which the transfer is to take place, the transfer is performed. The application receives a single NCCEVN_CALL_DISCONNECTED event with the reason code NCC_DIS_TRANSFER, indicating that the transfer succeeded and the original call is now in the disconnected state from the point of view of the application. The application should now invoke nccReleaseCall to destroy the call handle and release resources.

4. If the transfer fails, the first call is retrieved from hold and remains in the connected state. NCCEVN_CALL_RETRIEVED is returned, with a value field containing one of the NCC_DIS_xxx reason codes indicating why the transfer failed. For a list of possible NCC_DIS_xxx values, see NCCEVN_CALL_DISCONNECTED in Chapter 9.

Note that not all protocols support automatic call transfer. The NCC_CAP_AUTOMATIC_TRANSFER bit in the capabilitymask returned by nccQueryCapability indicates if automatic call transfer is supported or not.

5.4 Blocking and Unblocking Calls

Using the NCC service, the application can block all incoming calls on a line, and prevent placement of outbound calls on the line. While calls are being blocked, no call control events are generated for that line.

5.4.1 Blocking Calls

To block calls on a line, the application invokes nccBlockCalls with the line handle. nccBlockCalls may be invoked from any line state or call state. However, incoming calls will not be blocked on a line until there are no active calls on the line (the line state is idle).

Note: Since outbound-only trunks typically cannot be blocked, blocking a line is a valid action only when the trunk is capable of receiving calls (inbound-only or two-way trunks).

With the function invocation is specified the method to be used to block calls. Two methods are valid:

Method	Description
NCC_BLOCK_REJECTALL	Do not answer subsequent calls
NCC_BLOCK_OUT_OF_SERVICE	Place the line out of service

The NCC service waits until there are no active calls on the line. The line then enters the blocking state. The application receives NCCEVN_CALLS_BLOCKED. The line will remain in the blocking state until nccUnblockCalls is invoked.

The application may receive an incoming call event after invoking nccBlockCalls and before receiving NCCEVN_CALLS_BLOCKED. The application must handle the call (answering or rejecting it as necessary). Calls will not be blocked, and the application will not receive NCCEVN_CALLS_BLOCKED until there are no active calls.

5.4.2 Unblocking Calls

To unblock calls on a line in blocking line state, the application invokes nccUnblockCalls. This causes the line state to change to idle. The application receives NCCEVN_CALLS_UNBLOCKED. At this point, the application can receive or place calls on the line.

The application may invoke nccUnblockCalls to cancel a previous nccBlockCalls invocation before the line state becomes Idle. In this case, no events are received.

If the specified line is not in the blocking state, and no previously invoked nccBlockCalls is pending, nccUnblockCalls returns CTAERR_INVALID_STATE.