OPENCARDNAME_EXA structure (winscard.h)
The OPENCARDNAME_EX structure contains the information that the SCardUIDlgSelectCard function uses to initialize a smart card Select Card dialog box.
Syntax
typedef struct {
DWORD dwStructSize;
SCARDCONTEXT hSCardContext;
HWND hwndOwner;
DWORD dwFlags;
LPCSTR lpstrTitle;
LPCSTR lpstrSearchDesc;
HICON hIcon;
POPENCARD_SEARCH_CRITERIAA pOpenCardSearchCriteria;
LPOCNCONNPROCA lpfnConnect;
LPVOID pvUserData;
DWORD dwShareMode;
DWORD dwPreferredProtocols;
LPSTR lpstrRdr;
DWORD nMaxRdr;
LPSTR lpstrCard;
DWORD nMaxCard;
DWORD dwActiveProtocol;
SCARDHANDLE hCardHandle;
} OPENCARDNAME_EXA, *POPENCARDNAME_EXA, *LPOPENCARDNAME_EXA;
Members
dwStructSize
The length, in bytes, of the structure. The value of this member must not be NULL.
hSCardContext
The context used for communication with the smart card resource manager. Call SCardEstablishContext to set the resource manager context and SCardReleaseContext to release it. The value of this member must not be NULL.
hwndOwner
The window that owns the dialog box. This member can be any valid window handle, or it can be NULL for the desktop default.
dwFlags
A set of bit flags that you can use to initialize the dialog box. When the dialog box returns, it sets these flags to indicate the user's input. This member can be one of the following flags.
| Value | Meaning |
|---|---|
|
Display the dialog box only if the card being searched for by the calling application is not located and available for use in a reader. This allows the card to be found, connected (either through the internal dialog box mechanism or the user callback functions), and returned to the calling application. |
|
Force no display of the Select Card user interface (UI), regardless of search outcome. |
|
Force display of the Select Card UI, regardless of the search outcome. |
lpstrTitle
A pointer to a string to be placed in the title bar of the dialog box. If this member is NULL, the system uses the default title "Select Card:".
lpstrSearchDesc
A pointer to a string to be displayed to the user as a prompt to insert the smart card. If this member is NULL, the system uses the default text "Please insert a smart card".
hIcon
A handle to an icon (32 x 32 pixels). You can specify a vendor-specific icon to display in the dialog box. If this value is NULL, a generic, smart card reader–loaded icon is displayed.
pOpenCardSearchCriteria
A pointer to the OPENCARD_SEARCH_CRITERIA structure to be used, or NULL, if one is not used.
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
);
pvUserData
A void pointer to user data. This pointer is passed back to the caller on the Connect routine.
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 dwShareMode and dwPreferredProtocols parameters. If the connect succeeds, hCardHandle is set to the handle returned by SCardConnect. If lpfnConnect is NULL and dwShareMode is zero, hCardHandle is set to NULL.
dwPreferredProtocols
Used for internal connection as described in dwShareMode.
lpstrRdr
If the card is located, the lpstrRdr buffer contains the name of the reader that contains the located card. The buffer should be at least 256 characters long.
nMaxRdr
Size, in bytes (ANSI version) or characters (Unicode version), of the buffer pointed to by lpstrRdr. If the buffer is too small to contain the reader information, SCardUIDlgSelectCard returns SCARD_E_NO_MEMORY and the required size of the buffer pointed to by lpstrRdr.
lpstrCard
If the card is located, the lpstrCard buffer contains the name of the located card. The buffer should be at least 256 characters long.
nMaxCard
Size, in bytes (ANSI version) or characters (Unicode version), of the buffer pointed to by lpstrCard. If the buffer is too small to contain the card information, SCardUIDlgSelectCard returns SCARD_E_NO_MEMORY and the required size of the buffer in nMaxCard.
dwActiveProtocol
The actual protocol in use when the dialog box makes a connection to a card.
hCardHandle
A handle of the connected card (either through an internal dialog box connect or an lpfnConnect callback).
Remarks
Note
The winscard.h header defines OPENCARDNAME_EX as an alias that 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 is 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] |
| Header | winscard.h |