OPENCARDNAME

The OPENCARDNAME structure contains the information that the GetOpenCardName function uses to initialize a smart card common dialog.

typedef struct tagOCNA {
    DWORD           dwStructSize;
    HWND            hwndOwner;
    SCARDCONTEXT    hSCardContext;
    LPTSTR          lpstrGroupNames;
    DWORD           nMaxGroupNames;
    LPTSTR          lpstrCardNames;
    DWORD           nMaxCardNames;
    LPGUID          rgguidInterfaces;
    DWORD           cguidInterfaces;
    LPTSTR          lpstrRdr;
    DWORD           nMaxRdr;
    LPTSTR          lpstrCard;
    DWORD           nMaxCard;
    LPCTSTR         lpstrTitle;
    DWORD           dwFlags;
    LPVOID          pvUserData;
    DWORD           dwShareMode;
    DWORD           dwPreferredProtocols;
    DWORD           dwActiveProtocol;
    LPOCNCONNPROCA  lpfnConnect;
    LPOCNCHKPROC    lpfnCheck;
    LPOCNDSCPROC    lpfnDisconnect;
    SCARDHANDLE     hCardHandle;
} OPENCARDNAME, *LPOPENCARDNAME;;
 

Members

dwStructSize

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

hwndOwner

Identifies the window that owns the dialog box. This member can be any valid window handle, or it can be NULL for desktop default.

hSCardContext

Context used for communication with the smart card resource manager. Call SCardEstablishContext to set the resource manager context and SCardReleaseContext to release it. Must not be NULL.

lpstrGroupNames

Points 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

Maximum number of bytes (ANSI version) or characters (UNICODE version) in the lpstrGroupNames string.

lpstrCardNames

Points to a buffer containing 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

Maximum number of bytes (ANSI version) or characters (UNICODE version) in the lpstrCardNames string.

rgguidInterfaces

An array of GUIDs identifying the interfaces required. NULL for this release (RFU).

cguidInterfaces

The number of interfaces in the rgguidInterfaces array. NULL for this release (RFU).

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

Specifies the 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, GetOpenCardName 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

Specifies the 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, GetOpenCardName returns SCARD_E_NO_MEMORY and the required size of the buffer in nMaxCard.

lpstrTitle

Points 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 (that is, "Select Card:").

dwFlags

A set of bit flags 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 a combination of the following flags:

Flag	Meaning
SC_DLG_MINIMAL_UI	Displays the dialog 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 mechanism or the user callback functions), and returned to the calling application.
SC_DLG_NO_UI	Force no display of the common dialog UI, regardless of search outcome.
SC_DLG_FORCE_UI	Force display of the common dialog UI, regardless of the search outcome.

pvUserData

A 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 dwProtocols members are ignored. If lpfnConnect is NULL and dwShareMode is non-zero, then an internal call is made to SCardConnect using dwShareMode and dwProtocol 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, the common dialog returns hCardHandle as NULL.

dwPreferredProtocols

Used for internal connection as described in dwShareMode.

dwActiveProtocol

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

lpfnConnect

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

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

lpfnCheck

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, as indicated by lpfnDisconnect.

If the card is accepted by the verify routine, TRUE is returned. When the user accepts the card, all other cards currently connected will be disconnected, as indicated by lpfnDisconnect, and this card will be returned as the located card. The located card will remain connected.

The prototype for the check routine is

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

lpfnDisconnect

Pointer to the caller's card disconnect routine.

The prototype for the disconnect routine is

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

hCardHandle

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

See Also

Error Codes, GetOpenCardName, SCardConnect, SCardEstablishContext, SCardReleaseContext