TerminateCall

The TerminateCall procedure is called by application software to terminate (hang up) an active phone call.

TELEPHONY_RETURN_VALUE TerminateCall(

SIPHANDLE hStateMachine,

int PhoneLine,

BOOL Synchronous,

DWORD TimeOutMs

);

Parameters:

hStateMachine

[in] The handle to the telephony engine. This is the handle that was returned by a previous call to the StartSipTelephony procedure.

PhoneLine

[in] The zero based phone line to access.

Synchronous

[in] If this parameter is non zero (TRUE), the procedure will not return until: the call is terminated or an error has been detected. If this parameter is zero (FALSE), then TerminateCall will return immediately with the return value of SipSuccess. The call’s termination progress and state changes should be monitored by application software using the event notification callback mechanism.

TimeOutMs

[in] If the phone call is being terminated synchronously, then this parameter specifies the maximum timeout in milliseconds the procedure will wait for the call to terminate (hang up the phone line).

Return Value:

If the function succeeds, the return value will be SipSuccess.

If the function fails, the return value will be one of the following values as specified by the TELEPHONY_RETURN_VALUE data type.

Value	Description
SipCallFailure	This is a generic "catch all" API error. If an error condition is not specified by any other API error value, this error will be returned.
SipInvalidHandle	An API procedure was passed an invalid handle. The telephony engine attempts to verify user specified telephony handles and returns this error when an invalid handle is detected.
SipNotEnabled	A telephony API operation was attempted but the telephony engine has not yet been enabled. For example: You will get this error if you attempt to place an out bound phone call using the MakeCall API procedure when the telephony engine is not yet enabled. After the telephony engine is instantiated, perform all other required configuration. The last step to perform is to enable the telephony engine using the SipTelephonyEnable API procedure. Once the telephony engine is enabled, you will be able to receive and initiate calls.
SipAlreadyOnHook	A phone line was requested to go on hook when it was already on hook. This error will happen if you call the TerminateCall API procedure more than once on any one phone line.
SipCallTimeOut	Indicates that the operation timed out waiting for completion. To remove this error, increase the time out value specified to complete the operation.
SipLineBusyOut	Indicates that a telephony operation was requested on a phone line that has been "busied out". To remove this error, remove the phone line from the "busy out" state and try the operation again. Any phone line that has been taken out of service (busied out) can not be used.
SipPhoneLineAccessError	An internal error was detected that disallowed access to internal phone line data.
SipBadPhoneLine	A telephony operation was specified using an invalid phone line. Phone lines are numbered starting from zero.

Remarks:

IMPORTANT:

The VOIP Media Engine is fully multi-threaded. As such, your application can cause deadlocks to occur if you arbitrarily use critical section or mutex objects to lock large spans of code across multiple application threads or Media Engine callback procedures (callback threads).

For example: If you have a thread that acquires a global mutex and then calls the TerminateCall API procedure, and you also have a receiver IVR callback procedure registered (this callback executes in a different thread context) that also wants to access the same mutex, a deadlock may occur while calling the TerminateCall API procedure.

The best way to avoid deadlocks of this nature it to lock small sections of code that either write or read application status values that are used throughout your VOIP application threads and Media Engine callbacks.