Places a call.
DWORD nccPlaceCall ( CTAHD linehd, char *calledaddr, char *callingaddr, void *mgrcallparms, void *protcallparms, NCC_CALLHD *callhd )
|
Argument |
Description |
|
linehd |
Line handle used to open the NCC instance. |
|
calledaddr |
Pointer to the address of the remote party. Must be a NULL terminated string with a maximum of 32 digits (NCC_MAX_DIGITS). |
|
callingaddr |
Pointer to the address of the local party. Must be a NULL terminated string with a maximum of 32 digits (NCC_MAX_DIGITS). Can be NULL if the protocol implementation allows. |
|
mgrcallparms |
For all NaturalAccess protocols, this is interpreted as a pointer to an NCC_ADI_PLACECALL_PARMS structure. The default parameters are NCC.X.ADI_PLACECALL. typedef struct Refer to NCC.X.ADI_PLACECALL and to the nccadi.h file for more information. |
|
protcallparms |
Pointer to a protocol-specific NaturalAccess call placement parameter structure. Specify NULL to use 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. |
|
callhd |
Pointer to NCC_CALLHD. NCC assigns a valid call handle to a successfully initialized outbound call. This call handle is used in other call-related functions, such as nccHoldCall or nccReleaseCall. |
|
Return value |
Description |
|
SUCCESS |
|
|
CTAERR_BAD_ARGUMENT |
The calledaddr string is NULL, is not NULL terminated, or has more than 32 digits. The callingaddr string is not NULL terminated or has more than 32 digits. |
|
CTAERR_INVALID_HANDLE |
The NCC API is not opened on this context handle. |
|
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. |
|
Event |
Description |
|
NCCEVN_PLACING_CALL |
The call placement operation completed successfully and the call entered the placing state. |
|
NCCEVN_CALL_RELEASED |
An incoming call was detected during call placement. The TCP released the outbound call. The event value field contains NCC_RELEASED_GLARE. |
|
NCCEVN_CALL_PROCEEDING |
The switch accepted the call setup. The receiving side is being rung. The call enters the proceeding state. |
|
NCCEVN_REMOTE_ALERTING |
The remote end is in an alerting state (is ringing). This event is generated only if the NCC_REPORT_ALERTING bit is set in the NCC.START.eventmask parameter. For more information, refer to NCC API global parameters. |
|
NCCEVN_REMOTE_ANSWERED |
This event is generated at the first positive indication that the remote party has answered (for example, out-of-band signaling, voice, or modem tone). The event value field contains the indication type. This event is generated only if the NCC_REPORT_ANSWERED bit is set in the NCC.START.eventmask parameter. For more information, refer to NCC API global parameters. |
|
NCCEVN_CALL_CONNECTED |
Both parties are now connected. The call enters the connected state. |
calledaddr and callingaddr can be digit strings, IP addresses, or endpoint names, depending on the protocol.
If the application receives NCCEVN_CALL_RELEASED with an NCC_RELEASED_GLARE reason code instead of NCCEVN_PLACING_CALL, the line was seized for an incoming call before glare was resolved and the TCP has released the outgoing call. The application should immediately abandon outbound call placement and handle the incoming call. For information about managing call progress, refer to the Dialogic® NaturalAccess™ Alliance Device Interface API Developer's Manual.
The application can obtain protocol-specific information concerning the call, such as the B-channel location of a wireless protocol implementation, by invoking nccGetExtendedCallStatus.
Signaling protocols such as ISDN may support overlapped sending of digits. Such signaling may supply a partial dialing sequence when invoking nccPlaceCall, and use nccSendDigits to complete delivery of the remaining dialing sequence, in one or more chunks. The final character of each partial digit string should be a ~. When all digits are sent, the digit string specified in nccSendDigits should not include the final ~ character.
The application can determine whether or not a protocol supports overlapped sending of digits by examining the NCC_CAP_OVERLAPPED_SENDING bit in the capabilitymask returned by nccQueryCapability. For more information about overlapped sending of digits, see Sending overlapped digits.
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.