AbortIncomingCall

The AbortIncomingCall procedure is called by application software to abort (Ignore) a received incoming phone call. When this API procedure is called, the media engine will send a SIP status response back to the other user agent or configured SIP proxy.

Note: This API procedure should only be called when your application receives the SipOkToAnswerCall event from the Media Engine.

TELEPHONY_RETURN_VALUE AbortIncomingCall(

SIPHANDLE hStateMachine,

int PhoneLine,

int AbortSipStatusCode,
char *pAbortSipReasonPhrase

);

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.

AbortSipStatusCode

[in] Specifies the SIP error response code that should be sent to the far end device that initiated the call. Generally this value should be in the range of 400 to 699. See the latest SIP RFC for status code descriptions. Normally your application will want to send the "480 Temporarily Unavailable" response back to the far end of the call. In this case, your application should set the AbortSipStatusCode parameter to a value of 480 and the pAbortSipReasonPhrase parameter to the "Temporarily Unavailable" reason phrase string.

pAbortSipReasonPhrase

[in] The user defined "man readable" reason phrase that will be included in the response that is sent to the far end device. This can be any ASCII string you require but is generally set to a reason phrase as specified by the SIP RFC.

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.
SipBadPhoneLine	A telephony operation was specified using an invalid phone line. Phone lines are numbered starting from zero.