OPENCARDNAME_EXA結構（winscard.h）

發行項
07/16/2024

OPENCARDNAME_EX 結構包含 SCardUIDlgSelectCard 函式用來初始化智慧卡的資訊，選取卡片 對話框。

語法

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;

成員

dwStructSize

結構的長度，以位元組為單位。這個成員的值不得 NULL。

hSCardContext

用於與智慧卡通訊的內容，resource Manager。呼叫 SCardEstablishContext 來設定資源管理員內容，並 SCardReleaseContext 加以釋放。這個成員的值不得 NULL。

hwndOwner

擁有對話框的視窗。此成員可以是任何有效的視窗句柄，也可以針對桌面預設值 NULL。

dwFlags

一組位旗標，可用來初始化對話方塊。當對話框傳回時，它會設定這些旗標來指出用戶的輸入。這個成員可以是下列其中一個旗標。

價值	意義
SC_DLG_MINIMAL_UI	只有在呼叫端應用程式所搜尋的卡片找不到且可用於讀取器時，才會顯示對話框。這可讓卡片找到、連接（透過內部對話框機制或使用者回呼函式），並傳回給呼叫的應用程式。
SC_DLG_NO_UI	不論搜尋結果為何，強制不顯示選取卡片使用者介面（UI）。
SC_DLG_FORCE_UI	不論搜尋結果為何，強制顯示選取卡片 UI。

lpstrTitle

要放在對話框標題列中之字串的指標。如果此成員 NULL，則系統會使用預設標題「選取卡片：」。

lpstrSearchDesc

要向使用者顯示的字串指標，提示插入智慧卡。如果此成員 NULL，則系統會使用預設文字「請插入智慧卡」。

hIcon

圖示的句柄（32 x 32 圖元）。您可以指定要顯示在對話框中的廠商特定圖示。如果此值 NULL，則會顯示一般智慧卡讀取器載入圖示。

pOpenCardSearchCriteria

要使用的 OPENCARD_SEARCH_CRITERIA 結構的指標，如果未使用 NULL，則 NULL。

lpfnConnect

呼叫端卡片連接例程的指標。如果呼叫端需要執行其他處理以連線到卡片，此函式指標會設定為使用者的 connect 函式。如果 connect 函式成功，卡片會保持連線並初始化，並傳回卡片句柄。

線上例程的原型如下所示。

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

用戶數據的 void 指標。此指標會傳回 Connect 例程上的呼叫端。

dwShareMode

如果 lpfnConnect 不是 NULL，則會忽略 dwShareMode 和 dwPreferredProtocols 成員。如果 lpfnConnectNULL，且 dwShareMode 為非零， SCardConnect 進行內部呼叫，dwShareMode 和 dwPreferredProtocols 作為 dwShareMode 和 dwPreferredProtocols 参数。如果連線成功，hCardHandle 會設定為 SCardConnect 所傳回的句柄。如果 lpfnConnectNULL，且 dwShareMode 為零，hCardHandle 設定為 NULL。

dwPreferredProtocols

用於內部連線，如 dwShareMode中所述。

lpstrRdr

如果卡片位於，lpstrRdr 緩衝區會包含包含所找到卡片的讀取器名稱。緩衝區長度至少應為 256 個字元。

nMaxRdr

大小，以位元組為單位（ANSI 版本）或字元（Unicode 版本），由 lpstrRdr所指向的緩衝區。如果緩衝區太小而無法包含讀取器資訊，SCardUIDlgSelectCard 會傳回SCARD_E_NO_MEMORY，以及 lpstrRdr所指向之緩衝區所需的大小。

lpstrCard

如果卡片位於，lpstrCard 緩衝區包含所找到卡片的名稱。緩衝區長度至少應為 256 個字元。

nMaxCard

大小，以位元組為單位（ANSI 版本）或字元（Unicode 版本），由 lpstrCard所指向的緩衝區。如果緩衝區太小而無法包含卡片資訊，SCardUIDlgSelectCard 會傳回SCARD_E_NO_MEMORY，且 nMaxCard中所需的緩衝區大小。

dwActiveProtocol

當對話框連接到卡片時，使用中的實際通訊協定。

hCardHandle

連接的卡片句柄（透過內部對話框連接或 lpfnConnect 回呼）。

言論

注意

winscard.h 標頭會將 OPENCARDNAME_EX定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

要求

要求	價值
最低支援的用戶端	Windows XP [僅限傳統型應用程式]
支援的最低伺服器	Windows Server 2003 [僅限傳統型應用程式]
標頭	winscard.h