CardAuthenticatePin function
This topic is not current. For the most current information about the Smart Card API, see Smart Card Minidriver Specification.
The CardAuthenticatePin function, defined by a smart card module, authenticates a user by submitting a PIN to the smart card.
Syntax
DWORD WINAPI CardAuthenticatePin(
_In_ PCARD_DATA pCardData,
_In_ LPWSTR pwszUserId,
_In_ PBYTE pbPin,
_In_ DWORD cbPin,
_Out_opt_ PDWORD pcAttemptsRemaining
);
Parameters
-
pCardData [in]
-
A pointer to the CARD_DATA structure received from a call to the CardAcquireContext function.
-
pwszUserId [in]
-
A pointer to a string that contains the user ID. This ID is associated with the PIN specified by the pbPin parameter.
This parameter can be one of the following values.
Value Meaning - wszCARD_USER_EVERYONE
- L"anonymous"
The user is anonymous. - wszCARD_USER_USER
- L"user"
The user is not an administrator. - wszCARD_USER_ADMIN
- L"admin"
The user is an administrator. We recommend that administrators be authenticated by using the CardGetChallenge and CardAuthenticateChallenge functions instead of by using this function. -
pbPin [in]
-
A pointer to a buffer that contains the PIN.
-
cbPin [in]
-
The size, in bytes, of the pbPin buffer.
-
pcAttemptsRemaining [out, optional]
-
On output, a pointer to a DWORD variable that contains the number of times that an incorrect PIN can be submitted before the card is locked.
If this function has already returned a zero as the value of this parameter and is called again, the function fails and returns SCARD_W_CHV_BLOCKED.
If the value of this parameter is NULL, the smart card module ignores it.
Card modules that do not support a count of remaining authentication attempts should return a value of 1 for this parameter if the value of the parameter on input is not NULL.
Return value
If the function succeeds, the function returns zero.
If the function fails, it returns a nonzero error value or one of the following possible error values.
| Return code/value | Description |
|---|---|
|
The value of the pbPin parameter is NULL. |
|
The PIN is incorrect. |
|
The card has been blocked after too many attempts that use the wrong PIN. |
Requirements
| Minimum supported client |
Windows XP [desktop apps only] |
| Minimum supported server |
Windows Server 2003 [desktop apps only] |
| Header |
|