OPENCARDNAMEA 構造体 (winscard.h)

[アーティクル]
07/16/2024

OPENCARDNAME 構造体には、GetOpenCardName 関数がスマートカードの初期化に使用する情報 カード の選択] ダイアログボックスが含まれています。 OPENCARDNAME_EX SCardUIDlgSelectCard を呼び出すことは、OPENCARDNAMEを使用して GetOpenCardName 呼び出すよりも推奨。 OPENCARDNAME は、下位互換性のために提供されています。

構文

typedef struct {
  DWORD          dwStructSize;
  HWND           hwndOwner;
  SCARDCONTEXT   hSCardContext;
  LPSTR          lpstrGroupNames;
  DWORD          nMaxGroupNames;
  LPSTR          lpstrCardNames;
  DWORD          nMaxCardNames;
  LPCGUID        rgguidInterfaces;
  DWORD          cguidInterfaces;
  LPSTR          lpstrRdr;
  DWORD          nMaxRdr;
  LPSTR          lpstrCard;
  DWORD          nMaxCard;
  LPCSTR         lpstrTitle;
  DWORD          dwFlags;
  LPVOID         pvUserData;
  DWORD          dwShareMode;
  DWORD          dwPreferredProtocols;
  DWORD          dwActiveProtocol;
  LPOCNCONNPROCA lpfnConnect;
  LPOCNCHKPROC   lpfnCheck;
  LPOCNDSCPROC   lpfnDisconnect;
  SCARDHANDLE    hCardHandle;
} OPENCARDNAMEA, *POPENCARDNAMEA, *LPOPENCARDNAMEA;

メンバーズ

dwStructSize

構造体の長さをバイト単位で指定します。このメンバーは NULLすることはできません。

hwndOwner

ダイアログボックスを所有するウィンドウ。このメンバーには、任意の有効なウィンドウハンドルを指定することも、デスクトップの既定値に対して NULL することもできます。

hSCardContext

スマートカードリソースマネージャーとの通信に使用されるコンテキスト。 SCardEstablishContext 呼び出して、リソースマネージャーコンテキストを設定し、SCardReleaseContext をして解放します。このメンバーは NULLすることはできません。

lpstrGroupNames

null で終わるグループ名文字列を含むバッファーへのポインター。バッファー内の最後の文字列は、2 つの null 文字で終了する必要があります。各文字列は、検索に含めるカードのグループの名前です。 lpstrGroupNames が NULL場合は、既定のグループ (Scard$DefaultReaders) が検索されます。

nMaxGroupNames

lpstrGroupNames 文字列内の最大バイト数 (ANSI バージョン) または文字 (Unicode バージョン)。

lpstrCardNames

null で終わるカード名文字列を含むバッファーへのポインター。バッファー内の最後の文字列は、2 つの 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

ダイアログボックスの初期化に使用できるビットフラグのセット。ダイアログボックスが戻るときに、ユーザーの入力を示すようにこれらのフラグを設定します。このメンバーは、次のフラグの組み合わせにすることができます。

価値	意味
SC_DLG_MINIMAL_UI	呼び出し元のアプリケーションによって検索されるカードが見つからないため、リーダーで使用できる場合にのみ、ダイアログボックスを表示します。これにより、カードを見つけ、(内部ダイアログボックスメカニズムまたはユーザーコールバック関数を介して) 接続し、呼び出し元のアプリケーションに返すことができます。
SC_DLG_NO_UI	検索結果に関係なく、カードの選択ユーザーインターフェイス (UI) の表示を強制しません。
SC_DLG_FORCE_UI	検索結果に関係なく、カードの選択 UI を強制的に表示します。

pvUserData

ユーザーデータへの void ポインター。このポインターは、Connect、Check、Disconnect ルーチンで呼び出し元に返されます。

dwShareMode

lpfnConnect NULLされていない場合、dwShareMode および dwPreferredProtocols メンバー無視されます。

lpfnConnect が NULL 、dwShareMode が 0 以外場合、その後、dwShareMode と dwPreferredProtocols を dwShareMode として使用し、dwPreferredProtocols パラメーターをする SCardConnect をする内部呼び出しが行われます。接続が成功した場合、hCardHandle hSCardConnectによって返されるハンドル設定されます。

lpfnConnect NULL 、dwShareMode が 0 の場合、ダイアログボックスは NULLとして hCardHandle 返します。

dwPreferredProtocols

dwShareModeで説明されているように、内部接続使用されます。

dwActiveProtocol

ダイアログボックスがカードに接続するときに使用されている実際のプロトコルを返します。

lpfnConnect

呼び出し元のカード接続ルーチンへのポインター。呼び出し元がカードに接続するために追加の処理を実行する必要がある場合、この関数ポインターはユーザーの接続関数に設定されます。接続関数が成功した場合、カードは接続されて初期化され、カードハンドルが返されます。

接続ルーチンのプロトタイプは次のとおりです。

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。

カードが検証ルーチンによって拒否された場合、lpfnDisconnectで示されているように、FALSE が返され、カード切断されます。

カードが検証ルーチンによって受け入れられる場合は、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
);

注 lpfnConnect 、lpfnCheck、および lpfnDisconnectを使用する場合は、3 つのコールバックプロシージャがすべて存在する必要があります。これらのコールバックを使用すると、呼び出し元のアプリケーションが適切なカードを見つけたことをさらに確認できます。これは、適切なカードが選択されていることを確認するための最良の方法です。

hCardHandle

接続されたカードのハンドル (内部ダイアログボックス接続または lpfnConnect コールバック)。

備考

手記

winscard.h ヘッダーは、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして OPENCARDNAME を定義します。エンコードに依存しないエイリアスをエンコードに依存しないコードと組み合わせて使用すると、コンパイルまたは実行時エラーが発生する不一致につながる可能性があります。詳細については、「関数プロトタイプの規則」を参照してください。

必要条件

要件	価値
サポートされる最小クライアント	Windows XP [デスクトップアプリのみ]
サポートされる最小サーバー	Windows Server 2003 [デスクトップアプリのみ]
ヘッダー	winscard.h

次の方法で共有

OPENCARDNAMEA 構造体 (winscard.h)

構文

メンバーズ

備考

必要条件

関連項目

フィードバック

その他のリソース