GoOffHook

 

The GoOffHook API procedure is called by application software to accept (answer) an incoming phone call. This procedure can be called any time after the telephony engine event callback sends your application software the SipOkToAnswerCall event.

 

 

TELEPHONY_RETURN_VALUE GoOffHook(

SIPHANDLE hStateMachine,

int PhoneLine

);

 

 

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

 

 

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.

 

SipAlreadyOffHook

A phone line was requested to go off hook when it was already off hook. This error will happen if you call the GoOffHook 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.

 

SipBadPhoneLine

 

A telephony operation was specified using an invalid phone line. Phone lines are numbered starting from zero.

 

 

 

Remarks:

 

If your VOIP application is in the process of answering an incoming call (when a phone line enters the SipOkToAnswerCall state), it is a good idea to call the SetOutgoingLineOnly API procedure just before you call the GoOffHook API procedure. Doing so will ensure that the media engine will not assign a new incoming call to the phone line in the case that the current call gets quickly terminated by the far end. Calling the SetOutgoingLineOnly API procedure just before you answer the incoming call will help to simplify your incoming call handling logic.
 

If you call the SetOutgoingLineOnly API procedure before answering the incoming call, you must make sure to call the SetOutgoingLineOnly API procedure with the "enable state" parameter set to FALSE when the call finally is terminated. Doing so will allow the media engine to assign a new incoming call to the available line if required.