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 |
|---|---|
|
The challenge was initiated successfully. |
|
The challenge has failed due to a catastrophic error. |
|
The parameter passed to the method was not valid. |
|
The Messenger client lock and key mechanism is not initialized. |
|
The Messenger service API is locked. |
|
The application timed out while waiting for the result of the challenge. |
|
The application response to the challenge failed. |
|
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 |
|
| IDL |
|
| DLL |
|