Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This function searches the readers listed in the rgReaderStatesparameter for a card with an ATR string that matches one of the ATRs specified in rgAtrMasks, returning immediately with the result.

Syntax 

LONG SCardLocateCards(
  SCARDCONTEXT 
hContext,
  LPSCARD_ATRMASK 
rgAtrMasks,
  DWORD  
cAtrs,
  LPSCARD_READERSTATE 
rgReaderStates,
  DWORD 
cReaders
);

Parameters

hContext

[in] Supplies the handle that identifies the resource manager context. A previous call to SCardEstablishContextsets the resource manager context.

rgAtrMasks

[in] Array of SCARD_ATRMASKstructures that contain the ATRs and ATR masks for the cards to search for.

cAtrs

[in] Number of elements in the rgAtrMasksarray.

rgReaderStates

[in, out] Supplies an array of SCARD_READERSTATEstructures that specify the readers to search, and receives the result.

cReaders

[in] Supplies the number of elements in the rgReaderStatesarray.

Return Value

The following table shows the possible return values.

Value Description

SCARD_S_SUCCESS

Succeeds

An error value (see Smart Card Error Valuesfor a list of all error values).

Fails

Remarks

This service is especially useful when used in conjunction with SCardGetStatusChange. If no matching cards are found by means of SCardLocateCards, the calling application may use SCardGetStatusChangeto wait for card availability changes.

Requirements

Header winscard.h
Library winscard.lib
Windows Embedded CE Windows CE .NET 4.1 and later
Windows Mobile Windows Mobile Version 5.0 and later