Skip to content

Latest commit

 

History

History
218 lines (149 loc) · 9.32 KB

ns-winscard-opencardname_exa.md

File metadata and controls

218 lines (149 loc) · 9.32 KB
Raw
UID title description helpviewer_keywords old-location tech.root ms.assetid ms.date ms.keywords req.header req.include-header req.target-type req.target-min-winverclnt req.target-min-winversvr req.kmdf-ver req.umdf-ver req.ddi-compliance req.unicode-ansi req.idl req.max-support req.namespace req.assembly req.type-library req.lib req.dll req.irql targetos req.typenames req.redist ms.custom f1_keywords dev_langs topic_type api_type api_location api_name
NS:winscard.OPENCARDNAME_EXA
OPENCARDNAME_EXA (winscard.h)
The OPENCARDNAME_EX structure contains the information that the SCardUIDlgSelectCard function uses to initialize a smart card Select Card dialog box. (ANSI)
*LPOPENCARDNAME_EXA
*POPENCARDNAME_EXA
LPOPENCARDNAME_EX
LPOPENCARDNAME_EX structure pointer [Security]
OPENCARDNAME_EX
OPENCARDNAME_EX structure [Security]
OPENCARDNAME_EXA
OPENCARDNAME_EXW
POPENCARDNAME_EX
POPENCARDNAME_EX structure pointer [Security]
SC_DLG_FORCE_UI
SC_DLG_MINIMAL_UI
SC_DLG_NO_UI
_smart_opencardname_ex
security.opencardname_ex
winscard/LPOPENCARDNAME_EX
winscard/OPENCARDNAME_EX
winscard/OPENCARDNAME_EXA
winscard/OPENCARDNAME_EXW
winscard/POPENCARDNAME_EX
security\opencardname_ex.htm
security
fb9e64a9-441a-4c7b-b404-79682778c694
12/05/2018
*LPOPENCARDNAME_EXA, *POPENCARDNAME_EXA, LPOPENCARDNAME_EX, LPOPENCARDNAME_EX structure pointer [Security], OPENCARDNAME_EX, OPENCARDNAME_EX structure [Security], OPENCARDNAME_EXA, OPENCARDNAME_EXW, POPENCARDNAME_EX, POPENCARDNAME_EX structure pointer [Security], SC_DLG_FORCE_UI, SC_DLG_MINIMAL_UI, SC_DLG_NO_UI, _smart_opencardname_ex, security.opencardname_ex, winscard/LPOPENCARDNAME_EX, winscard/OPENCARDNAME_EX, winscard/OPENCARDNAME_EXA, winscard/OPENCARDNAME_EXW, winscard/POPENCARDNAME_EX
winscard.h
Windows
Windows XP [desktop apps only]
Windows Server 2003 [desktop apps only]
OPENCARDNAME_EXW (Unicode) and OPENCARDNAME_EXA (ANSI)
Windows
OPENCARDNAME_EXA, *POPENCARDNAME_EXA, *LPOPENCARDNAME_EXA
19H1
POPENCARDNAME_EXA
winscard/POPENCARDNAME_EXA
OPENCARDNAME_EXA
winscard/OPENCARDNAME_EXA
c++
APIRef
kbSyntax
HeaderDef
Winscard.h
OPENCARDNAME_EX
OPENCARDNAME_EXA
OPENCARDNAME_EXW

OPENCARDNAME_EXA structure

-description

The OPENCARDNAME_EX structure contains the information that the SCardUIDlgSelectCard function uses to initialize a smart card Select Card dialog box.

-struct-fields

-field dwStructSize

The length, in bytes, of the structure. The value of this member must not be NULL.

-field 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.

-field 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.

-field 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.

-field 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:".

-field 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".

-field 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.

-field pOpenCardSearchCriteria

A pointer to the OPENCARD_SEARCH_CRITERIA structure to be used, or NULL, if one is not used.

-field 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
);

-field pvUserData

A void pointer to user data. This pointer is passed back to the caller on the Connect routine.

-field 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.

-field dwPreferredProtocols

Used for internal connection as described in dwShareMode.

-field 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.

-field 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.

-field 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.

-field 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.

-field dwActiveProtocol

The actual protocol in use when the dialog box makes a connection to a card.

-field hCardHandle

A handle of the connected card (either through an internal dialog box connect or an lpfnConnect callback).

-see-also

SCardConnect

SCardEstablishContext

SCardReleaseContext

SCardUIDlgSelectCard

Smart Card Return Values

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