Transfers a call on a PBX, Centrex, or Centrex-like line.
DWORD nccAutomaticTransfer ( NCC_CALLHD callhd, char *digitstr, unsigned transferwhen, void *transferparms, void *mgrcallparms, void *protcallparms )
|
Argument |
Description |
|
callhd |
Handle of the call being transferred. |
|
digitstr |
Pointer to the address (the party's extension) of the party to which to transfer to. This value must be a NULL terminated string with a maximum of 32 digits. |
|
transferwhen |
Determines when the call is to be transferred. See Blind (automatic) transfer for the transfer values. |
|
transferparms |
Pointer to a protocol-specific NaturalAccess call transfer parameter structure. Specify NULL to use the default values. See the protocol-specific documentation for details. |
|
mgrcallparms |
Pointer to a manager-specific NaturalAccess call placement parameter structure. Specify NULL to use the default values. For all NaturalAccess protocols, this is a pointer to an NCC_ADI_PLACECALL_PARMS structure; the default parameters are NCC.X.ADI_PLACECALL. |
|
protcallparms |
Pointer to a protocol-specific NaturalAccess parameter structure. Specify NULL to use the default values. For the CAS API, this is a pointer to an NCC_ADI_CAS_PARMS structure; the default parameters are NCC.X.ADI_CAS. For ISDN Software, this is a pointer to a PLACECALL_EXT structure; the default parameters are NCC.X.ADI_ISDN.PALCECALL_EXT. For the SIP API, this is a pointer to a SIP data buffer. See the Dialogic® NaturalAccess™ SIP API Developer’s Manual for more information. |
|
Return value |
Description |
|
SUCCESS |
|
|
CTAERR_BAD_ARGUMENT |
The specified digit string is NULL, is not NULL terminated, or has more than 32 digits. |
|
CTAERR_INVALID_HANDLE |
The call handle is not valid. It may have been released. |
|
CTAERR_INVALID_STATE |
The line is not in the appropriate state to invoke this function. |
|
CTAERR_SVR_COMM |
A server communication error occurred. |
|
NCCERR_ADDRESS_BLOCKED |
Too many calls were placed to this address or a call was placed too recently. |
|
NCCERR_INVALID_CALL_STATE |
The call is not in the connected state or is held. |
|
NCCERR_NOT_CAPABLE |
The protocol does not support the capability to transfer a call automatically. |
|
Event |
Description |
|---|---|
|
NCCEVN_CALL_HELD |
The first call is held. |
|
NCCEVN_CALL_RETRIEVED |
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. |
|
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. Other protocol-specific errors or reasons for disconnecting may be reported. See your protocol-specific documentation for more details. |
nccAutomaticTransfer executes a blind transfer by placing a second call and completing call transfer. This function operates only when the first call handle is in the connected state or is on hold.
nccAutomaticTransfer works as follows:
|
Stage |
Description |
|
1 |
The function places the first party on hold and returns NCCEVN_CALL_HELD to the application. |
|
2 |
The function places a second call to the specified address. |
|
3 |
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. |
Not all protocols support automatic call transfer. The application can determine if the protocol supports this method by examining the NCC_CAP_AUTOMATIC_TRANSFER bit in the capabilitymask returned by nccQueryCapability. Refer to Blind (automatic) transfer for more information on how automatic transfer works.
Note: International regulatory approvals require you to limit attempts by an automated dialer to call a given number. Limits are placed on both the number and the frequency of the call attempts. For more information, refer to Limiting call attempts by automatic dialers.