(Page 4 of 23 in this chapter) Version

nccAutomaticTransfer

Description

Transfers a call on a PBX, Centrex, or Centrex-like, line.

Prototype

DWORD nccAutomaticTransfer ( NCC_CALLHD callhd,
char *digitstr,
unsigned transferwhen,
void *transferparms,
void *mgrcallparms,
void *protcallparms )
callhd Handle for a call that is in the Connected state. This call must not be held.
digitstr Pointer to address of the party to transfer to (e.g., the party's extension).
transferwhen Determines when call is to be transferred. The value can be any of the following:
NCC_TRANSFER_PROCEEDING: After digitstr dialed.
NCC_TRANSFER_ALERTING: When ring detected.
NCC_TRANSFER_CONNECTED: When called party answers.
transferparms Pointer to protocol-specific CT Access call transfer parameter structure. Specify NULL to use default values. See protocol-specific documentation for details.
mgrcallparms Pointer to manager-specific CT Access call placement parameter structure. Specify NULL to use default values. See protocol-specific documentation for details.
protcallparms Pointer to protocol-specific CT Access parameter structure. Specify NULL to use default values. See protocol-specific documentation for details.

Return Values

SUCCESS
CTAERR_BAD_ARGUMENT
Specified digit string is NULL.
CTAERR_INVALID_HANDLE
The call handle is not valid. It may have been released.
CTAERR_INVALID_STATE
Line is not in the appropriate state to invoke this function.
NCCERR_INVALID_CALL_STATE
Call is not in the Connected state, or is held.
NCCERR_NOT_CAPABLE
Protocol does not support the capability to transfer a call automatically. The application can determine if the protocol supports this feature by examining the NCC_CAP_AUTOMATIC_TRANSFER bit in the capabilitymask returned by nccQueryCapability.

Events

NCCEVN_CALL_HELD
Indicates that the first call is held.
NCCEVN_CALL_RETRIEVED
Indicates that the transfer failed. The event value field contains 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.
NCCEVN_CALL_DISCONNECTED
callhd 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 now release this call handle with nccReleaseCall. Note that other protocol-specific errors or reasons for disconnecting may be reported. See your protocol-specific implementation for more details.

Details

This function executes a "blind" transfer by performing placement of a "second" call and completing call transfer. This function will operate only when the first call handle is in the Connected state, or is on hold.
nccAutomaticTransfer works as follows:

The function places the first party on hold. NCCEVN_CALL_HELD is returned to the application.

The function places a second call to the specified address.

If the placed call reaches the transferwhen stage, the transfer is performed. NCCEVN_CALL_DISCONNECTED is returned, with reason NCC_DIS_TRANSFER, indicating that the transfer succeeded and the first call is in the Disconnected call state from the point of view of the application. The application should now invoke nccReleaseCall to destroy the call handle and release resources.

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.
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.

See Also

nccTransferCall

(Page 4 of 23 in this chapter) Version

tech_support@nmss.com

Copyright © 1999, Natural MicroSystems, Inc. All rights reserved.