共用方式為

OPENCARDNAME_EXA 結構 (winscard.h)

  • 發行項

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

用於與 智慧卡資源管理員通訊的內容。 呼叫 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。

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 成員。 如果 lpfnConnect 為 NULL 且 dwShareMode 為非零，則會對使用 dwShareMode 和 dwPreferredProtocols 做為 dwShareMode 和 dwPreferredProtocols 參數的 SCardConnect 進行內部呼叫。 如果連線成功， hCardHandle 會設定為 SCardConnect 所傳回的句柄。 如果 lpfnConnect 為 NULL 且 dwShareMode 為零， hCardHandle 會設定為 NULL。

dwPreferredProtocols

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

lpstrRdr

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

nMaxRdr

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

lpstrCard

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

nMaxCard

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

dwActiveProtocol

對話框建立卡片連線時使用的實際通訊協定。

hCardHandle

透過內部對話框連線或 lpfnConnect 回呼) ， (連接的卡片句柄。

備註

注意

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

規格需求

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

另請參閱

SCardConnect

SCardEstablishContext

SCardReleaseContext

SCardUIDlgSelectCard

智慧卡傳回值