GetOutgoingCallErrorInfo

The GetOutgoingCallErrorInfo API procedure can be called by a user application to retrieve additional error information associated with an outgoing call. Under normal operating conditions, a far end SIP device or gateway may respond to a call initiation (INVITE request) by sending back an error response indication.

Application software can call this API procedure any time after it receives the SipFarEndIsBusy or SipFarEndError events from the media engine to retrieve the error information. Note that your application software should also call this API procedure before terminating the phone call using the TerminateCall API procedure.

The out going call information that will be made available to you is contained in a structure variable of type SIP_OUTGOING_CALL_ERROR_INFO.

TELEPHONY_RETURN_VALUE GetOutgoingCallInfo(

SIPHANDLE hStateMachine,

int PhoneLine,

SIP_OUTGOING_CALL_ERROR_INFO *pOutgoingCallErrorInfo

);

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.

pOutgoingCallErrorInfo

[out] A pointer to a structure variable of type SIP_OUTGOING_CALL_ERROR_INFO. Upon successful completion, the address pointed to by this parameter will be filled with out going call error information.

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.
SipBadParameter	For API procedures that receive pointers from user software, this error indicates that a NULL pointer condition was detected. Make sure all pointers your software passes to the telephony API are valid.
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.