SCardListCards

The SCardListCards function searches the smart card database and provides a list of named cards previously introduced to the system by the user.

The caller specifies an ATR string, a set of interface identifiers (GUIDs), or both. If both an ATR string and an identifier array are supplied, the cards returned will match the ATR string supplied and support the interfaces specified.

LONG SCardListCards(
  IN SCARDCONTEXT hContext,
  IN LPCBYTE pbAtr,
  IN LPCGUID rgguidInterfaces,
  IN DWORD cguidInterfaceCount,
  OUT LPTSTR mszCards,
  IN OUT LPDWORD pcchCards
);
 

Parameters

hContext

Supplies the handle that identifies the resource manager context for the query. The resource manager context can be set by a previous call to SCardEstablishContext, or set to NULL if the query is not directed towards a specific context.

pbAtr

Supplies the address of an ATR string to compare to known cards, or NULL if no ATR matching is to be performed.

rgguidInterfaces

Supplies an array of identifiers (GUIDs), or NULL if no interface matching is to be performed. When an array is supplied, a card name will be returned only if all the specified identifiers are supported by the card.

cguidInterfaceCount

Supplies the number of entries in the rgguidInterfaces array. If rgguidInterfaces is NULL, then this value is ignored.

mszCards

Receives a multi-string that lists the smart cards found. If this value is NULL, SCardListCards ignores the buffer length supplied in pcchCards, returning the length of the buffer that would have been returned if this parameter had not been NULL to pcchCards and a success code.

pcchCards

Supplies the length of the mszCards buffer in characters, and receives the actual length of the multi-string structure, including all trailing Null characters. If the buffer length is specified as SCARD_AUTOALLOCATE, then mszCards is converted to a pointer to a string pointer, and receives the address of a block of memory containing the multi-string structure. This block of memory must be deallocated with SCardFreeMemory.

Return Values

Remarks

To return all smart cards introduced to the subsystem, set pbAtr and rgguidInterfaces to NULL.

SCardListCards is a database query function. For a description of other database query functions, see Smart Card Database Query Functions.

QuickInfo

  Windows NT: Use version 4.0 SP3 and later.
  Windows: Use Windows 95 OSR2.1.
  Windows CE: Unsupported.
  Header: Declared in winscard.h.
  Import Library: Link with winscard.lib.

See Also

SCardEstablishContext, SCardFreeMemory, SCardGetProviderId, SCardListInterfaces, SCardListReaderGroups, SCardListReaders