The NCC API supports the ability to place a call on hold, and to retrieve a held call. Placing a call on hold frees the NCC API 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.
Some protocols do not support call hold/retrieve. The NCC_CAP_HOLD_CALL bit in the capabilitymask returned by nccQueryCapability indicates if the protocol supports call hold/retrieve.
To place a call on hold, the application invokes nccHoldCall with the handle of the call. When the application receives NCCEVN_CALL_HELD, the call is on hold. There is no call state transition. However, the line state goes to idle.
A call can be put on hold only from the connected state unless the capability bit NCC_CAP_HOLD_IN_ANY_STATE is set in the capabilitymask. The capabilitymask is retrieved with nccQueryCapability. If the bit is set, the call can be put on hold from any state, and change states while on hold.
The application can perform media functions on the held call such as playing a user voice file or silence, using a NaturalAccess media API. Depending upon the capabilities of the protocol, the application can also transfer a held call.
To retrieve a held call, the application invokes nccRetrieveCall with the handle of the call. When the application receives NCCEVN_CALL_RETRIEVED, the call is retrieved. There is no call state transition. However, the line state returns to active.
A held call can 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 with nccQueryCapability.
Note: Some protocols allow calls to be held and 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.