SCardReconnect function (winscard.h)

Article
02/22/2024

The SCardReconnect function reestablishes an existing connection between the calling application and a smart card. This function moves a card handle from direct access to general access, or acknowledges and clears an error condition that is preventing further access to the card.

Syntax

LONG SCardReconnect(
  [in]            SCARDHANDLE hCard,
  [in]            DWORD       dwShareMode,
  [in]            DWORD       dwPreferredProtocols,
  [in]            DWORD       dwInitialization,
  [out, optional] LPDWORD     pdwActiveProtocol
);

Parameters

[in] hCard

Reference value obtained from a previous call to SCardConnect.

[in] dwShareMode

Flag that indicates whether other applications may form connections to this card.

Value	Meaning
SCARD_SHARE_SHARED	This application will share this card with other applications.
SCARD_SHARE_EXCLUSIVE	This application will not share this card with other applications.

[in] dwPreferredProtocols

Bitmask of acceptable protocols for this connection. Possible values may be combined with the OR operation.

The value of this parameter should include the current protocol. Attempting to reconnect with a protocol other than the current protocol will result in an error.

Value	Meaning
SCARD_PROTOCOL_T0	T=0 is an acceptable protocol.
SCARD_PROTOCOL_T1	T=1 is an acceptable protocol.

[in] dwInitialization

Type of initialization that should be performed on the card.

Value	Meaning
SCARD_LEAVE_CARD	Do not do anything special on reconnect.
SCARD_RESET_CARD	Reset the card (Warm Reset).
SCARD_UNPOWER_CARD	Power down the card and reset it (Cold Reset).

[out, optional] pdwActiveProtocol

Flag that indicates the established active protocol.

Value	Meaning
SCARD_PROTOCOL_T0	T=0 is the active protocol.
SCARD_PROTOCOL_T1	T=1 is the active protocol.

Return value

This function returns different values depending on whether it succeeds or fails.

Return code	Description
Success	SCARD_S_SUCCESS.
Failure	An error code. For more information, see Smart Card Return Values.

Remarks

SCardReconnect is a smart card and reader access function. For information about other access functions, see Smart Card and Reader Access Functions.

Examples

The following example shows reestablishing a connection.

DWORD     dwAP;
LONG      lReturn;

// Reconnect.
// hCardHandle was set by a previous call to SCardConnect.
lReturn = SCardReconnect(hCardHandle,
                         SCARD_SHARE_SHARED,
                         SCARD_PROTOCOL_T0 | SCARD_PROTOCOL_T1,
                         SCARD_LEAVE_CARD,
                         &dwAP );
if ( SCARD_S_SUCCESS != lReturn )
    printf("Failed SCardReconnect\n");

Requirements

Requirement	Value
Minimum supported client	Windows XP [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	winscard.h
Library	Winscard.lib
DLL	Winscard.dll

Share via