OPENCARDNAME_EXW 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;
  LPCWSTR                    lpstrTitle;
  LPCWSTR                    lpstrSearchDesc;
  HICON                      hIcon;
  POPENCARD_SEARCH_CRITERIAW pOpenCardSearchCriteria;
  LPOCNCONNPROCW             lpfnConnect;
  LPVOID                     pvUserData;
  DWORD                      dwShareMode;
  DWORD                      dwPreferredProtocols;
  LPWSTR                     lpstrRdr;
  DWORD                      nMaxRdr;
  LPWSTR                     lpstrCard;
  DWORD                      nMaxCard;
  DWORD                      dwActiveProtocol;
  SCARDHANDLE                hCardHandle;
} OPENCARDNAME_EXW, *POPENCARDNAME_EXW, *LPOPENCARDNAME_EXW;

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
SC_DLG_MINIMAL_UI
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.
SC_DLG_NO_UI
Force no display of the Select Card user interface (UI), regardless of search outcome.
SC_DLG_FORCE_UI
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 which 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 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

See also

SCardConnect

SCardEstablishContext

SCardReleaseContext

SCardUIDlgSelectCard

Smart Card Return Values