AddAuthorizationCredentials

If your application will be challenged by other telephony software or devices, you can use this API procedure to specify authorization data that will be used to fulfill the far end’s authorization challenge. This API procedure can be called multiple times with different authentication data. The authentication data is then maintained internally by the media engine. As your application software executes, the media engine inspects its internal list of authentication credentials to locate credentials that will fulfill any authorization challenge that may occur.

TELEPHONY_RETURN_VALUE AddAuthorizationCredentials(

SIPHANDLE hStateMachine,

char *pUserName,

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.

pUserName

[in] A user name that is used to authenticate with the far end challenging entity.

pPassword

[in] A password that is used to authenticate with the far end challenging entity. This password is only known to your application and the far end. This password is also referred to as a “shared secret”. The password specified here is never transmitted over the network when communicating with the far end applications or device.

pRealm

[in] The name of the realm that will be challenged. If you are not familiar with the concept of a realm, simply think of it as being similar to a domain name. Each telephony application or device that challenges your application could all have unique realms assigned to them.

Note: Specifying a "wild card" realm

If the realm string specified for this parameter is set to the wild card string (a null terminated string that contains only an asterisk such as: "*", the wild card user name and password will be used to respond to authentication challenges from the challenging realms using the realm name that is specified in the received SIP challenge response.

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.