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

Namespace:  LanScape
Assembly:  LMEVoipManaged (in LMEVoipManaged.dll) Version: 6.0.5226.26700

Syntax

C#
public VoipMediaEngine..::.TELEPHONY_RETURN_VALUE TerminateCall(
	int PhoneLine,
	bool Synchronous,
	uint TimeOutMs
)
Visual Basic (Declaration)
Public Function TerminateCall ( _
	PhoneLine As Integer, _
	Synchronous As Boolean, _
	TimeOutMs As UInteger _
) As VoipMediaEngine..::.TELEPHONY_RETURN_VALUE
Visual C++
public:
VoipMediaEngine..::.TELEPHONY_RETURN_VALUE TerminateCall(
	int PhoneLine, 
	bool Synchronous, 
	unsigned int TimeOutMs
)
J#
public VoipMediaEngine..::.TELEPHONY_RETURN_VALUE TerminateCall(
	int PhoneLine,
	boolean Synchronous,
	UInt32 TimeOutMs
)

Parameters

PhoneLine
Type: System..::.Int32
The zero based phone line to access.
Synchronous
Type: System..::.Boolean
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
Type: System..::.UInt32
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 VoipMediaEngine..::.TELEPHONY_RETURN_VALUE data type.

Return ValueDescription
SipCallFailure
This value is returned by telephony API procedures to indicate general API failure. This error value is used as a "catch all error". If you receive this error, check to make sure that all parameters specified in the API procedure call are correct. Particularly, verify that pointers to memory regions are valid. This error return value is only used if a mapping to another specific error value does not exist.

(API return value)

SipInvalidHandle
Application software specified an invalid telephony handle in one of the API procedures. This usually indicates memory corruption on the part of application software.

(API return value)

SipNotEnabled
Indicates that the telephony engine was not enabled for normal operation. Application software should always execute the SipTelephonyEnable()()() API procedure as the final step during configuration when initializing the telephony engine.

(API return value)

SipAlreadyOnHook
Application software tried to place the phone line on hook when the phone line was already in the on hook state.

(API return value)

SipCallTimeOut

Making an outbound call:

Indicates that a call was initiated using the MakeCall(String, String, UInt32, Int32, Boolean, UInt32) or MakeCallUri(String, Boolean, Int32, Boolean, UInt32) API procedures and call setup did not complete in the time specified. Either the call destination did not respond (is overloaded), the destination of the call is off line, or your host machine could not handle call setup in the time specified. To remove this error, increase the time out value specified to complete the operation.

Terminating a call:

Indicates that a call was terminated using the TerminateCall(Int32, Boolean, UInt32) API procedure and call tear down did not complete in the time specified. Either the call destination did not respond (is overloaded), the destination of the call is off line, or your host machine could not handle call termination in the time specified. To remove this error, increase the time out value specified to complete the operation.

Answering an inbound call:

Indicates that an inbound call was being answered using the GoOffHook(Int32) API procedure and call setup did not complete in the time specified. Either the call destination did not respond (is overloaded), the destination of the call is off line, or your host machine could not answer the call in the time specified. To remove this error, increase the time out value specified to complete the operation.

(API return value)

SipLineBusyOut
Application software attempted to use a phone line that was previously taken out of service by calling the BusyOutLine(Int32, Boolean) API procedure. Return the phone line to service and try the operation again. A phone line is placed back into service by calling the BusyOutLine(Int32, Boolean) API procedure with a value of FALSE.

(API return value)

SipPhoneLineAccessError
This value may be returned when initiating outgoing calls. It indicates there was an internal error detected while accessing internal phone line data. If you continually see this error, please contact LanScape support.

(API return value)

SipBadPhoneLine
Application software called a telephony API procedure and specified an invalid phone line. Phone lines are numbered starting from zero. This error is most commonly returned when attempting to access phone lines in excess of the max number of lines supported by the telephony engine.

(API return value)

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(Int32, Boolean, UInt32) 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(Int32, Boolean, UInt32) 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.

See Also