CardChangeAuthenticatorEx function
This topic is not current. For the most current information about the Smart Card API, see Smart Card Minidriver Specification.
The CardChangeAuthenticatorEx function, defined by a smart card module, changes the authentication data associated with a smart card and a specified user type, using a specified personal identification number (PIN)
Syntax
DWORD WINAPI CardChangeAuthenticatorEx(
_In_ PCARD_DATA pCardData,
_In_ DWORD dwFlags,
_In_ PIN_ID dwAuthenticatingPinId,
_In_ PBYTE pbAuthenticatingPinData,
_In_ DWORD cbAuthenticatingPinData,
_In_ PIN_ID dwTargetPinId,
_In_ PBYTE pbTargetData,
_In_ DWORD cbTargetData,
_In_ DWORD cRetryCount,
_Out_opt_ PDWORD pcAttemptsRemaining
);
Parameters
-
pCardData [in]
-
A pointer to the CARD_DATA structure received from a call to the CardAcquireContext function.
-
dwFlags [in]
-
The type of authentication that this function performs. This parameter can be one of the following values.
Value Meaning - CARD_UNBLOCK_PIN_CHALLENGE_RESPONSE
- 1
The authentication data in the pbCurrentAuthenticator and pbNewAuthenticator buffers are responses to a challenge returned by the CardGetChallenge function. - CARD_UNBLOCK_PIN_PIN
- 2
The authentication data in the pbCurrentAuthenticator and pbNewAuthenticator buffers are PIN data. -
dwAuthenticatingPinId [in]
-
The PIN to be authenticated.
-
pbAuthenticatingPinData [in]
-
A pointer to a byte buffer containing the PIN data to be authenticated.
-
cbAuthenticatingPinData [in]
-
The length, in bytes, of the PIN data pointed to by the pbAuthenticatingPinData parameter
-
dwTargetPinId [in]
-
A pointer to the PIN to be updated.
-
pbTargetData [in]
-
A pointer to a buffer that contains the new PIN identifier.
-
cbTargetData [in]
-
The length, in bytes, of the PIN in the buffer pointed to by the pbTargetData parameter.
-
cRetryCount [in]
-
The number of incorrect attempts at authentication that are allowed before the smart card is blocked.
To leave the number of allowed attempts unchanged, set the value of this parameter to zero.
Card modules that do not support setting the number of allowed attempts should return SCARD_E_INVALID_PARAMETER if this parameter is set to any value other than zero.
-
pcAttemptsRemaining [out, optional]
-
On output, a pointer to a DWORD variable that contains the number of times that incorrect authentication data 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, it returns zero.
Requirements
Minimum supported client |
Windows Vista [desktop apps only] |
Minimum supported server |
Windows Server 2008 [desktop apps only] |