Share via


IMsgrLock::RequestChallenge method

[RequestChallenge is no longer available for use as of Windows Vista. See Windows Messenger for more information.]

Initiates an authentication challenge-response transaction between a Messenger client and a Messenger service .

Syntax

HRESULT RequestChallenge(
  [in] long lCookie
);

Parameters

lCookie [in]

Type: long

LONG that identifies the authentication transaction session.

Return value

Type: HRESULT

Returns one of the following values.

Return code Description
S_OK
The challenge was initiated successfully.
E_FAIL
The challenge has failed due to a catastrophic error.
E_INVALIDARG
The parameter passed to the method was not valid.
MSGR_E_API_NOTINITIALIZED
The Messenger client lock and key mechanism is not initialized.
MSGR_E_API_LOCKED
The Messenger service API is locked.
MSGR_E_API_PENDING_UNLOCK
The application timed out while waiting for the result of the challenge.
MSGR_E_API_UNLOCK_FAILED
The application response to the challenge failed.
MSGR_E_API_ALREADY_UNLOCKED
The Messenger service API is already unlocked.

Remarks

This method is by used by a Messenger client to gain access to the Messenger service APIs. When this method is called by a Messenger client, an authentication challenge from a Messenger service is invoked. When the Messenger service challenge is received by the Messenger client, the OnLockChallenge event is fired. The Messenger client can then proceed with the challenge-response authentication process by invoking the SendResponse method. For more information, see the overview on the Messenger Lock and Key API.

The client application can only request a challenge response from the server once. Therefore, if this method is called a second time during a Messenger client session, an error code is returned.

The following table lists the error codes returned by this method.

Error Code Meaning
MSGR_E_API_NOTINITIALIZED (0x81000751) The Messenger client lock and key mechanism is not initialized.
MSGR_E_API_LOCKED (0x81000752) The Messenger service API is locked.
MSGR_E_API_UNLOCK_FAILED (0x81000753) The application response to the challenge failed.
MSGR_E_API_ALREADY_UNLOCKED (0x81000754) The Messenger service API is already unlocked.
MSGR_E_API_PENDING_UNLOCK (0x81000755) The application timed out while waiting for the result of the challenge.
0x80004005 The challenge has failed due to a catastrophic error.
0x80000003 The parameter passed to the method was not valid.

Requirements

Minimum supported client
Windows XP [desktop apps only]
Minimum supported server
Windows Server 2003 [desktop apps only]
End of client support
Windows XP
End of server support
Windows Server 2003
Product
Messenger 4.5
Header
Msgrpriv.h
IDL
Msgrpriv.idl
DLL
Msgsc.dll

See also

IMsgrLock

OnLockChallenge

SendResponse

Messenger Session Invite and Messenger Private APIs