OPENCARDNAMEW 結構 （winscard.h）

OPENCARDNAME 結構包含 GetOpenCardName 函式用來初始化智慧卡 的資訊，選取卡片 對話框。 使用 OPENCARDNAME_EX 呼叫 SCardUIDlgSelectCard，建議使用 OPENCARDNAME呼叫 getOpenCardName getOpenCardName。 OPENCARDNAME 提供回溯相容性。

語法

typedef struct {
  DWORD          dwStructSize;
  HWND           hwndOwner;
  SCARDCONTEXT   hSCardContext;
  LPWSTR         lpstrGroupNames;
  DWORD          nMaxGroupNames;
  LPWSTR         lpstrCardNames;
  DWORD          nMaxCardNames;
  LPCGUID        rgguidInterfaces;
  DWORD          cguidInterfaces;
  LPWSTR         lpstrRdr;
  DWORD          nMaxRdr;
  LPWSTR         lpstrCard;
  DWORD          nMaxCard;
  LPCWSTR        lpstrTitle;
  DWORD          dwFlags;
  LPVOID         pvUserData;
  DWORD          dwShareMode;
  DWORD          dwPreferredProtocols;
  DWORD          dwActiveProtocol;
  LPOCNCONNPROCW lpfnConnect;
  LPOCNCHKPROC   lpfnCheck;
  LPOCNDSCPROC   lpfnDisconnect;
  SCARDHANDLE    hCardHandle;
} OPENCARDNAMEW, *POPENCARDNAMEW, *LPOPENCARDNAMEW;

成員

dwStructSize

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

hwndOwner

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

hSCardContext

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

lpstrGroupNames

緩衝區的指標，其中包含以 Null 結尾的組名字符串。 緩衝區中的最後一個字串必須以兩個 Null 字元終止。 每個字串都是要包含在搜尋中的卡片群組名稱。 如果 lpstrGroupNamesNULL，則會搜尋預設群組 （Scard$DefaultReaders）。

nMaxGroupNames

lpstrGroupNames 字串中的位元元數上限（ANSI 版本）或字元數上限（Unicode 版本）。

lpstrCardNames

緩衝區的指標，其中包含 Null 終止的卡片名稱字串。 緩衝區中的最後一個字串必須以兩個 Null 字元終止。 每個字串都是要找到的卡片名稱。

nMaxCardNames

lpstrCardNames 字串中的位元元數上限（ANSI 版本）或字元數上限（Unicode 版本）。

rgguidInterfaces

保留供日後使用。 設定為 NULL。 識別所需介面的 GUID 陣列。

cguidInterfaces

保留供期貨使用。 設定為 NULL。 rgguidInterfaces 陣列中的介面數目。

lpstrRdr

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

nMaxRdr

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

lpstrCard

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

nMaxCard

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

lpstrTitle

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

dwFlags

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

pvUserData

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

dwShareMode

如果 lpfnConnect 不是 NULL，則會忽略 dwShareMode 和 dwPreferredProtocols 成員。

如果 lpfnConnect 為 null 且 dwShareMode 為非零， 接著會呼叫內部呼叫 SCardConnect，以使用 dwShareMode 和 dwPreferredProtocols 作為 dwShareMode，dwPreferredProtocols 参数。 如果連線成功，hCardHandle 會設定為 hSCardConnect 所傳回的句柄。

如果 lpfnConnectNULL，且 dwShareMode 為零，則對話框會傳回 hCardHandle 為 null。

dwPreferredProtocols

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

dwActiveProtocol

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

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

lpfnCheck

卡片驗證呼叫端例程的指標。 如果不需要特殊卡片驗證，此指標會 NULL。

如果驗證例程拒絕卡片，則會傳回 false ，且卡片已中斷連線，如 lpfnDisconnect所指示。

如果驗證例程接受卡片，則會傳回 true 。 當使用者接受卡片時，目前連線的所有其他卡片將會中斷連線，如 lpfnDisconnect所指示，而且此卡片會以找到的卡片的形式傳回。 找到的卡片會保持連線。

檢查例程的原型如下所示。

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

lpfnDisconnect

呼叫端卡片中斷連線例程的指標。

中斷聯機例程的原型如下所示。

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

hCardHandle

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

言論

要求

另請參閱

GetOpenCardName

SCardConnect

SCardEstablishContext

SCardReleaseContext

SCardUIDlgSelectCard