Windows Dev Center

Expand Minimize

OPENCARD_SEARCH_CRITERIA structure

The OPENCARD_SEARCH_CRITERIA structure is used by the SCardUIDlgSelectCard function in order to recognize cards that meet the requirements set forth by the caller. You can, however, call SCardUIDlgSelectCard without using this structure.

Syntax


typedef struct {
  DWORD         dwStructSize;
  LPTSTR        lpstrGroupNames;
  DWORD         nMaxGroupNames;
  LPCGUID       rgguidInterfaces;
  DWORD         cguidInterfaces;
  LPTSTR        lpstrCardNames;
  DWORD         nMaxCardNames;
  LPOCNCHKPROC  lpfnCheck;
  LPOCNCONNPROC lpfnConnect;
  LPOCNDSCPROC  lpfnDisconnect;
  LPVOID        pvUserData;
  DWORD         dwShareMode;
  DWORD         dwPreferredProtocols;
} OPENCARD_SEARCH_CRITERIA, *POPENCARD_SEARCH_CRITERIA, *LPOPENCARD_SEARCH_CRITERIA;

Members

dwStructSize

The length, in bytes, of the structure. Must not be NULL.

lpstrGroupNames

A pointer to a buffer containing null-terminated group name strings. The last string in the buffer must be terminated by two null characters. Each string is the name of a group of cards that is to be included in the search. If lpstrGroupNames is NULL, the default group (Scard$DefaultReaders) is searched.

nMaxGroupNames

The maximum number of bytes (ANSI version) or characters (Unicode version) in the lpstrGroupNames string.

rgguidInterfaces

Reserved for future use. An array of GUIDs that identifies the interfaces required. Set this member to NULL.

cguidInterfaces

Reserved for future use. The number of interfaces in the rgguidInterfaces array. Set this member to NULL.

lpstrCardNames

A pointer to a buffer that contains null-terminated card name strings. The last string in the buffer must be terminated by two null characters. Each string is the name of a card that is to be located.

nMaxCardNames

The maximum number of bytes (ANSI version) or characters (Unicode version) in the lpstrGroupNames string.

lpfnCheck

A pointer to the caller's card verify routine. If no special card verification is required, this pointer is NULL. If the card is rejected by the verify routine, FALSE is returned, and the card will be disconnected. If the card is accepted by the verify routine, TRUE is returned.

The prototype for the check routine is as follows.


Boolean Check(
  hSCardContext, // the card context passed in the parameter block
  hCard,         // card handle
  pvUserData     // pointer to user data passed in the parameter block
);


lpfnConnect

A pointer to the caller's card connect routine. If the caller needs to perform additional processing to connect to the card, this function pointer is set to the user's connect function. If the connect function is successful, the card is left connected and initialized, and the card handle is returned.

The prototype for the connect routine is as follows.


Connect(
  hSCardContext, // the card context passed in the parameter block
  szReader,      // the name of the reader
  mszCards,      // multiple string that contains
                 //    the possible card names in the reader
  pvUserData     // pointer to user data passed in parameter block
);


lpfnDisconnect

A pointer to the caller's card disconnect routine.

The prototype for the disconnect routine is as follows.


Disconnect(
  hSCardContext, // the card context passed in the parameter block
  hCard,         // card handle
  pvUserData     // pointer to user data passed in the parameter block
);


Note  When you use lpfnConnect, lpfnCheck, and lpfnDisconnect, all three callback procedures should be present. Using these callbacks allows further verification that the calling application has found the appropriate card. This is the best way to ensure the appropriate card is selected. However, when using a value that is not NULL for lpfnCheck, either both lpfnConnect and lpfnDisconnect must not be NULL (and pvUserData should also be provided), or dwShareMode and dwPreferredProtocols must both be set.
pvUserData

Void pointer to user data. This pointer is passed back to the caller on the Connect, Check, and Disconnect routines.

dwShareMode

If lpfnConnect is not NULL, the dwShareMode and dwPreferredProtocols members are ignored. If lpfnConnect is NULL and dwShareMode is nonzero, an internal call is made to SCardConnect that uses dwShareMode and dwPreferredProtocols as the parameter.

dwPreferredProtocols

Used for internal connection as described in dwShareMode.

Requirements

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

Winscard.h

Unicode and ANSI names

OPENCARD_SEARCH_CRITERIAW (Unicode) and OPENCARD_SEARCH_CRITERIAA (ANSI)

See also

OPENCARDNAME_EX
SCardUIDlgSelectCard

 

 

Community Additions

ADD
Show:
© 2015 Microsoft