Share via

OPENCARDNAMEA 構造体 (winscard.h)

  • [アーティクル]

OPENCARDNAME 構造体には、GetOpenCardName 関数がスマート カード [カードの選択] ダイアログ ボックスを初期化するために使用する情報が含まれています。 OPENCARDNAME で GetOpenCardName を呼び出すよりも、OPENCARDNAME_EXを使用して SCardUIDlgSelectCard を呼び出することをお勧めします。 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 は nMaxCard 内のバッファーのSCARD_E_NO_MEMORYと必要なサイズを返します。

lpstrTitle

ダイアログ ボックスのタイトル バーに配置する文字列へのポインター。 このメンバーが NULL の場合、システムは既定のタイトル "Select Card:" を使用します。

dwFlags

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

値 説明
SC_DLG_MINIMAL_UI
 呼び出し元のアプリケーションによって検索されるカードが見つからない場合、リーダーで使用できる場合にのみ、ダイアログ ボックスを表示します。 これにより、カードを見つけ、(内部ダイアログ ボックス メカニズムまたはユーザー コールバック関数を介して) 接続し、呼び出し元のアプリケーションに返すことができます。
SC_DLG_NO_UI
 検索結果に関係なく、 Select Cardユーザー インターフェイス (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 の場合、ダイアログ ボックスは hCardHandleを NULL として返します。

dwPreferredProtocols

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

dwActiveProtocol

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

lpfnConnect

呼び出し元の接続ルーチンカードへのポインター。 呼び出し元がカードに接続するために追加の処理を実行する必要がある場合、この関数ポインターはユーザーの 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 です。

カードが検証ルーチンによって拒否された場合は、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 ヘッダーは、OPENCARDNAME を別名として定義し、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択します。 エンコードに依存しないエイリアスをエンコードニュートラルでないコードと組み合わせて使用すると、コンパイルまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。

要件

   
サポートされている最小のクライアント Windows XP (デスクトップ アプリのみ)
サポートされている最小のサーバー Windows Server 2003 (デスクトップ アプリのみ)
Header winscard.h

関連項目

GetOpenCardName

SCardConnect

SCardEstablishContext

SCardReleaseContext

SCardUIDlgSelectCard