Expand Minimize

OPENCARDNAME_EX structure

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;
  LPCTSTR                   lpstrTitle;
  LPCTSTR                   lpstrSearchDesc;
  HICON                     hIcon;
  POPENCARD_SEARCH_CRITERIA pOpenCardSearchCriteria;
  LPOCNCONNPROC             lpfnConnect;
  LPVOID                    pvUserData;
  DWORD                     dwShareMode;
  DWORD                     dwPreferredProtocols;
  LPTSTR                    lpstrRdr;
  DWORD                     nMaxRdr;
  LPTSTR                    lpstrCard;
  DWORD                     nMaxCard;
  DWORD                     dwActiveProtocol;
  SCARDHANDLE               hCardHandle;
} OPENCARDNAME_EX, *POPENCARDNAME_EX, *LPOPENCARDNAME_EX;

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.

ValueMeaning
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).

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

OPENCARDNAME_EXW (Unicode) and OPENCARDNAME_EXA (ANSI)

See also

Smart Card Return Values
SCardUIDlgSelectCard
SCardConnect
SCardEstablishContext
SCardReleaseContext

 

 

Community Additions

ADD
Show:
© 2014 Microsoft