SCardGetAttrib function (winscard.h)
The SCardGetAttrib function retrieves the current reader attributes for the given handle. It does not affect the state of the reader, driver, or card.
Syntax
LONG SCardGetAttrib(
[in] SCARDHANDLE hCard,
[in] DWORD dwAttrId,
[out] LPBYTE pbAttr,
[in, out] LPDWORD pcbAttrLen
);
Parameters
[in] hCard
Reference value returned from SCardConnect.
[in] dwAttrId
Identifier for the attribute to get. The following table lists possible values for dwAttrId. These values are read-only. Note that vendors may not support all attributes.
| Value | Meaning |
|---|---|
|
Answer to reset (ATR) string. |
|
DWORD encoded as 0xDDDDCCCC, where DDDD = data channel type and CCCC = channel number:
|
|
DWORD indicating which mechanical characteristics are supported. If zero, no special characteristics are supported. Note that multiple bits can be set:
|
|
Current block waiting time. |
|
Current clock rate, in kHz. |
|
Current character waiting time. |
|
Bit rate conversion factor. |
|
Current error block control encoding.
0 = longitudinal redundancy check (LRC) 1 = cyclical redundancy check (CRC) |
|
Clock conversion factor. |
|
Current byte size for information field size card. |
|
Current byte size for information field size device. |
|
Current guard time. |
|
DWORD encoded as 0x0rrrpppp where rrr is RFU and should be 0x000. pppp encodes the current protocol type. Whichever bit has been set indicates which ISO protocol is currently in use. (For example, if bit zero is set, T=0 protocol is in effect.) |
|
Current work waiting time. |
|
Default clock rate, in kHz. |
|
Default data rate, in bps. |
|
Reader's display name. |
|
Reserved for future use. |
|
Reader's system name. |
|
Instance of this vendor's reader attached to the computer. The first instance will be device unit 0, the next will be unit 1 (if it is the same brand of reader) and so on. Two different brands of readers will both have zero for this value. |
|
Single byte. Zero if smart card electrical contact is not active; nonzero if contact is active. |
|
Single byte indicating smart card presence:
0 = not present 1 = card present but not swallowed (applies only if reader supports smart card swallowing) 2 = card present (and swallowed if reader supports smart card swallowing) 4 = card confiscated. |
|
Single byte indicating smart card type:
0 = unknown type 1 = 7816 Asynchronous 2 = 7816 Synchronous Other values RFU. |
|
Maximum clock rate, in kHz. |
|
Maximum data rate, in bps. |
|
Maximum bytes for information file size device. |
|
Zero if device does not support power down while smart card is inserted. Nonzero otherwise. |
|
DWORD encoded as 0x0rrrpppp where rrr is RFU and should be 0x000. pppp encodes the supported protocol types. A '1' in a given bit position indicates support for the associated ISO protocol, so if bits zero and one are set, both T=0 and T=1 protocols are supported. |
|
Vendor-supplied interface device serial number. |
|
Vendor-supplied interface device type (model designation of reader). |
|
Vendor-supplied interface device version (DWORD in the form 0xMMmmbbbb where MM = major version, mm = minor version, and bbbb = build number). |
|
Vendor name. |
[out] pbAttr
Pointer to a buffer that receives the attribute whose ID is supplied in dwAttrId. If this value is NULL, SCardGetAttrib ignores the buffer length supplied in pcbAttrLen, writes the length of the buffer that would have been returned if this parameter had not been NULL to pcbAttrLen, and returns a success code.
[in, out] pcbAttrLen
Length of the pbAttr buffer in bytes, and receives the actual length of the received attribute If the buffer length is specified as SCARD_AUTOALLOCATE, then pbAttr is converted to a pointer to a byte pointer, and receives the address of a block of memory containing the attribute. This block of memory must be deallocated with SCardFreeMemory.
Return value
This function returns different values depending on whether it succeeds or fails.
| Return code | Description |
|---|---|
|
SCARD_S_SUCCESS. |
|
ERROR_NOT_SUPPORTED. |
|
An error code. For more information, see Smart Card Return Values. |
Remarks
The SCardGetAttrib function is a direct card access function. For more information on other direct access functions, see Direct Card Access Functions.
Examples
The following example shows how to retrieve an attribute for a card reader. The example assumes that hCardHandle is a valid handle obtained from a previous call to the SCardConnect function.
LPBYTE pbAttr = NULL;
DWORD cByte = SCARD_AUTOALLOCATE;
DWORD i;
LONG lReturn;
lReturn = SCardGetAttrib(hCardHandle,
SCARD_ATTR_VENDOR_NAME,
(LPBYTE)&pbAttr,
&cByte);
if ( SCARD_S_SUCCESS != lReturn )
{
if ( ERROR_NOT_SUPPORTED == lReturn )
printf("Value not supported\n");
else
{
// Some other error occurred.
printf("Failed SCardGetAttrib - %x\n", lReturn);
exit(1); // Or other appropriate action
}
}
else
{
// Output the bytes.
for (i = 0; i < cByte; i++)
printf("%c", *(pbAttr+i));
printf("\n");
// Free the memory when done.
// hContext was set earlier by SCardEstablishContext
lReturn = SCardFreeMemory( hContext, pbAttr );
}
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 |
See also
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for