The NCC API supports the ability to transfer calls from a first party to a second party through a switch such as private branch exchange (PBX), Centrex, or Centrex-like exchange. The following call transfer methods are supported:
Supervised transfer using nccTransferCall. With this method, the application performs the transfer process. The calls to be connected are on the same line.
For the SIP API, the calls must be on two different lines, because SIP supports only one call per line. See the Dialogic® NaturalAccess™ SIP API Developer’s Manual for more information.
Blind, or automatic transfer using nccAutomaticTransfer. With this method, the application requests the switch to perform the transfer.
Two channel transfer using nccTransferCall. With this method, the application performs the transfer process as a supervised transfer. The calls to be connected are on different lines.
Some protocols do not support all transfer methods. Refer to Protocol capabilities for more information.
In a supervised transfer, the application controls the transfer process. Before the application can perform a supervised transfer,
Both calls must be in the connected state.
Only one call can be on hold.
Both calls must be on the same line.
Note: To transfer calls on different lines, use two channel transfer.
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 invokes nccReleaseCall for each call handle to destroy the handle and release resources. NCCEVN_CALL_RELEASED indicates that a call was released.
If the transfer does not complete successfully, the application receives NCCEVN_CALL_DISCONNECTED, with protocol-specific values. See the protocol-specific documentation for details.
In a blind or automatic transfer, the application requests the switch such as PBX, Centrex, or Centrex-like switch to perform a call transfer.
Only one party is in the connected state.
The current call must not be on hold.
To perform the transfer, the application invokes nccAutomaticTransfer with the handle of the current call and the address (for example, the extension) of the party to transfer to. When invoking the function, the application specifies at what point the transfer is to take place:
|
Value |
Transfer takes place... |
|---|---|
|
NCC_TRANSFER_PROCEEDING |
After the address is sent, and the switch has accepted the calls the request and 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. |
Blind (automatic) transfer follows this process:
|
Stage |
Description |
|
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 invokes 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. |
Two channel transfer allows you to transfer calls that are on different lines.
The calls do not need to be in a specific call state.
A call identifier must exist for at least one of the calls. A call identifier internally identifies a call in a two channel transfer. If the bit parameter NCC_REPORT_CALLID in NCC.START.eventmask is set, NCCEVN_CALLID_AVAILABLE is sent to the application, and the application can issue a two channel transfer.
Refer to the protocol-specific documentation for more information on call identifiers, and on the appropriate time to issue a call transfer.
To perform the transfer, the application invokes nccTransferCall with the handles of the two calls. If the transfer is successful, the application receives two NCCEVN_CALL_DISCONNECTED events. The value field of one event contains NCC_DIS_TRANSFER. The value field of the other event contains a reason code indicating a remote hang up.
As the event is returned for each call, the call enters the disconnected state from the point of view of the application. The application invokes nccReleaseCall for each call handle to destroy the handle and release resources. NCCEVN_CALL_RELEASED indicates that a call was released.
If the transfer is not successful, the application receives NCCEVN_PROTOCOL_ERROR. The value field of this event contains NCC_PROTERR_TCT_FAILED. The size field contains the protocol-specific reason code. Call states for both calls remain unchanged when receiving this event.