VerifyChallengeResponse

When incoming request authentication is enabled, the media engine will send the SipIncomingAuthentication event to your application whenever a far end application or device responds to our challenge with authentication response data.

Along with the event, your application can access a CHALLENGE_AUTHENTICATION structure which contains data specific to the challenge response the far end sent. If the Operation member of the CHALLENGE_AUTHENTICATION structure is set to the value AUTHENTICATE_VERIFY_CREDENTIALS, then the challenge handle member of the CHALLENGE_AUTHENTICATION structure is available to your application. Your application can use this handle to verify the challenge response by calling this API procedure.

TELEPHONY_RETURN_VALUE VerifyChallengeResponse(

SIPHANDLE hStateMachine,

CHALLENGE_HANDLE hChallenge,

char *pPassword,

char *pRealm

);

Parameters:

hStateMachine

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

hChallenge

[in] A handle to internal authentication challenge information. This handle represents authentication information received from the far end.

pPassword

[in] A pointer to a NULL terminated string that contains the password for your authentication realm.

pRealm

[in] A pointer to a NULL terminated string that contains the name of your authentication realm.

Return Value:

If the function succeeds, the return value will be SipSuccess. In this case, your application will want to set the AuthorizationGranted member of the CHALLENGE_AUTHENTICATION structure to inform the media engine that the authentication response is valid and the incoming request can be processed as normal.

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.