SCardConnectA function (winscard.h)
The SCardConnect function establishes a connection (using a specific resource manager context) between the calling application and a smart card contained by a specific reader. If no card exists in the specified reader, an error is returned.
Syntax
LONG SCardConnectA(
[in] SCARDCONTEXT hContext,
[in] LPCSTR szReader,
[in] DWORD dwShareMode,
[in] DWORD dwPreferredProtocols,
[out] LPSCARDHANDLE phCard,
[out] LPDWORD pdwActiveProtocol
);
Parameters
[in] hContext
A handle that identifies the resource manager context. The resource manager context is set by a previous call to SCardEstablishContext.
[in] szReader
The name of the reader that contains the target card.
[in] dwShareMode
A flag that indicates whether other applications may form connections to the card.
[in] dwPreferredProtocols
A bitmask of acceptable protocols for the connection. Possible values may be combined with the OR operation.
Value | Meaning |
---|---|
|
T=0 is an acceptable protocol. |
|
T=1 is an acceptable protocol. |
|
This parameter may be zero only if dwShareMode is set to SCARD_SHARE_DIRECT. In this case, no protocol negotiation will be performed by the drivers until an IOCTL_SMARTCARD_SET_PROTOCOL control directive is sent with SCardControl. |
[out] phCard
A handle that identifies the connection to the smart card in the designated reader.
[out] pdwActiveProtocol
A flag that indicates the established active protocol.
Value | Meaning |
---|---|
|
T=0 is the active protocol. |
|
T=1 is the active protocol. |
|
SCARD_SHARE_DIRECT has been specified, so that no protocol negotiation has occurred. It is possible that there is no card in the reader. |
Return value
This function returns different values depending on whether it succeeds or fails.
Return code | Description |
---|---|
|
SCARD_S_SUCCESS. |
|
An error code. For more information, see Smart Card Return Values. |
|
The reader was unable to connect to the card. |
Remarks
The SCardConnect function is a smart card and reader access function. For more information about other access functions, see Smart Card and Reader Access Functions.
Examples
The following example creates a connection to a reader. The example assumes that hContext is a valid handle of type SCARDCONTEXT received from a previous call to SCardEstablishContext.
SCARDHANDLE hCardHandle;
LONG lReturn;
DWORD dwAP;
lReturn = SCardConnect( hContext,
(LPCTSTR)"Rainbow Technologies SCR3531 0",
SCARD_SHARE_SHARED,
SCARD_PROTOCOL_T0 | SCARD_PROTOCOL_T1,
&hCardHandle,
&dwAP );
if ( SCARD_S_SUCCESS != lReturn )
{
printf("Failed SCardConnect\n");
exit(1); // Or other appropriate action.
}
// Use the connection.
// Display the active protocol.
switch ( dwAP )
{
case SCARD_PROTOCOL_T0:
printf("Active protocol T0\n");
break;
case SCARD_PROTOCOL_T1:
printf("Active protocol T1\n");
break;
case SCARD_PROTOCOL_UNDEFINED:
default:
printf("Active protocol unnegotiated or unknown\n");
break;
}
// Remember to disconnect (by calling SCardDisconnect).
// ...
Note
The winscard.h header defines SCardConnect as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.
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 |