Win32 API 日本語リファレンス
ホーム › Security.Credentials › OPENCARD_SEARCH_CRITERIAA

OPENCARD_SEARCH_CRITERIAA

構造体
📘 Microsoft Learn (日本語) · English
サイズx64: 96 バイト / x86: 52 バイト

サイズ=各フィールドのバイト数(x64/x86 で異なる場合は x64/x86 と併記)。x64/x86 列=フィールドのバイトオフセット(HSPで dupptr / lpoke / wpoke 等に使用)。

フィールド

フィールド型サイズx64x86説明
dwStructSizeDWORD4+0+0構造体の長さ(バイト単位)。NULL であってはなりません。
lpstrGroupNamesLPSTR8/4+8+4null で終わるグループ名文字列を格納したバッファーへのポインター。バッファー内の最後の文字列は 2 つの null 文字で終端されていなければなりません。各文字列は、検索対象に含めるカードのグループ名です。lpstrGroupNames が NULL の場合は、既定のグループ (Scard$DefaultReaders) が検索されます。
nMaxGroupNamesDWORD4+16+8lpstrGroupNames 文字列の最大バイト数 (ANSI 版) または最大文字数 (Unicode 版)。
rgguidInterfacesGUID*8/4+24+12将来の使用のために予約済みです。必要なインターフェイスを識別する GUID の配列です。このメンバーには NULL を設定してください。
cguidInterfacesDWORD4+32+16将来の使用のために予約済みです。rgguidInterfaces 配列内のインターフェイスの数です。このメンバーには NULL を設定してください。
lpstrCardNamesLPSTR8/4+40+20null で終わるカード名文字列を格納したバッファーへのポインター。バッファー内の最後の文字列は 2 つの null 文字で終端されていなければなりません。各文字列は、検索対象となるカードの名前です。
nMaxCardNamesDWORD4+48+24lpstrGroupNames 文字列の最大バイト数 (ANSI 版) または最大文字数 (Unicode 版)。
lpfnCheckLPOCNCHKPROC8/4+56+28

呼び出し元のカード検証ルーチンへのポインター。特別なカードの検証が不要な場合、このポインターは NULL です。検証ルーチンによってカードが拒否された場合は FALSE が返され、カードは切断されます。検証ルーチンによってカードが受け入れられた場合は TRUE が返されます。

チェックルーチンのプロトタイプは次のとおりです。

Boolean Check(
  hSCardContext, // the card context passed in the parameter block
  hCard,         // card handle
  pvUserData     // pointer to user data passed in the parameter block
);
lpfnConnectLPOCNCONNPROCA8/4+64+32

呼び出し元のカード接続ルーチンへのポインター。カードへの接続に追加の処理が必要な場合、この関数ポインターにはユーザーの接続関数を設定します。接続関数が成功した場合、カードは接続および初期化された状態のまま残り、カードハンドルが返されます。

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

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
);
lpfnDisconnectLPOCNDSCPROC8/4+72+36

呼び出し元のカード切断ルーチンへのポインター。

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

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 つのコールバックプロシージャすべてを指定する必要があります。これらのコールバックを使用すると、呼び出し元のアプリケーションが適切なカードを見つけたことをさらに検証できます。これは、適切なカードが選択されていることを確認する最善の方法です。ただし、lpfnCheck に NULL 以外の値を使用する場合は、lpfnConnect と lpfnDisconnect の両方が NULL でないか (この場合は pvUserData も指定してください)、あるいは dwShareMode と dwPreferredProtocols の両方が設定されていなければなりません。
pvUserDatavoid*8/4+80+40ユーザーデータへの void ポインター。このポインターは、Connect、Check、Disconnect の各ルーチンで呼び出し元に渡し返されます。
dwShareModeDWORD4+88+44lpfnConnect が NULL でない場合、dwShareMode メンバーと dwPreferredProtocols メンバーは無視されます。lpfnConnect が NULL で、かつ dwShareMode が 0 以外の場合は、dwShareMode と dwPreferredProtocols をパラメーターとして使用する SCardConnect への内部呼び出しが行われます。
dwPreferredProtocolsDWORD4+92+48dwShareMode で説明されているとおり、内部での接続に使用されます。

公式ドキュメント

OPENCARD_SEARCH_CRITERIA 構造体は、呼び出し元が設定した要件を満たすカードを認識するために SCardUIDlgSelectCard 関数で使用されます。ただし、この構造体を使用せずに SCardUIDlgSelectCard を呼び出すこともできます。

解説(Remarks)

メモ

winscard.h ヘッダーは、OPENCARD_SEARCH_CRITERIA を、UNICODE プリプロセッサ定数の定義に基づいてこの関数の ANSI 版と Unicode 版を自動的に選択するエイリアスとして定義しています。エンコーディングに依存しないエイリアスと、エンコーディングに依存するコードを混在させると、不一致が生じてコンパイルエラーや実行時エラーの原因となる場合があります。詳細については、関数プロトタイプの規則を参照してください。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での定義

#include <windows.h>

// OPENCARD_SEARCH_CRITERIAA  (x64 96 / x86 52 バイト)
typedef struct OPENCARD_SEARCH_CRITERIAA {
    DWORD dwStructSize;
    LPSTR lpstrGroupNames;
    DWORD nMaxGroupNames;
    GUID* rgguidInterfaces;
    DWORD cguidInterfaces;
    LPSTR lpstrCardNames;
    DWORD nMaxCardNames;
    LPOCNCHKPROC lpfnCheck;
    LPOCNCONNPROCA lpfnConnect;
    LPOCNDSCPROC lpfnDisconnect;
    void* pvUserData;
    DWORD dwShareMode;
    DWORD dwPreferredProtocols;
} OPENCARD_SEARCH_CRITERIAA;
using System;
using System.Runtime.InteropServices;

[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
public struct OPENCARD_SEARCH_CRITERIAA
{
    public uint dwStructSize;
    public IntPtr lpstrGroupNames;
    public uint nMaxGroupNames;
    public IntPtr rgguidInterfaces;
    public uint cguidInterfaces;
    public IntPtr lpstrCardNames;
    public uint nMaxCardNames;
    public IntPtr lpfnCheck;
    public IntPtr lpfnConnect;
    public IntPtr lpfnDisconnect;
    public IntPtr pvUserData;
    public uint dwShareMode;
    public uint dwPreferredProtocols;
}
Imports System.Runtime.InteropServices

<StructLayout(LayoutKind.Sequential, CharSet:=CharSet.Unicode)>
Public Structure OPENCARD_SEARCH_CRITERIAA
    Public dwStructSize As UInteger
    Public lpstrGroupNames As IntPtr
    Public nMaxGroupNames As UInteger
    Public rgguidInterfaces As IntPtr
    Public cguidInterfaces As UInteger
    Public lpstrCardNames As IntPtr
    Public nMaxCardNames As UInteger
    Public lpfnCheck As IntPtr
    Public lpfnConnect As IntPtr
    Public lpfnDisconnect As IntPtr
    Public pvUserData As IntPtr
    Public dwShareMode As UInteger
    Public dwPreferredProtocols As UInteger
End Structure
import ctypes
from ctypes import wintypes

class OPENCARD_SEARCH_CRITERIAA(ctypes.Structure):
    _fields_ = [
        ("dwStructSize", wintypes.DWORD),
        ("lpstrGroupNames", ctypes.c_void_p),
        ("nMaxGroupNames", wintypes.DWORD),
        ("rgguidInterfaces", ctypes.c_void_p),
        ("cguidInterfaces", wintypes.DWORD),
        ("lpstrCardNames", ctypes.c_void_p),
        ("nMaxCardNames", wintypes.DWORD),
        ("lpfnCheck", ctypes.c_void_p),
        ("lpfnConnect", ctypes.c_void_p),
        ("lpfnDisconnect", ctypes.c_void_p),
        ("pvUserData", ctypes.c_void_p),
        ("dwShareMode", wintypes.DWORD),
        ("dwPreferredProtocols", wintypes.DWORD),
    ]
#[repr(C)]
pub struct OPENCARD_SEARCH_CRITERIAA {
    pub dwStructSize: u32,
    pub lpstrGroupNames: *mut core::ffi::c_void,
    pub nMaxGroupNames: u32,
    pub rgguidInterfaces: *mut core::ffi::c_void,
    pub cguidInterfaces: u32,
    pub lpstrCardNames: *mut core::ffi::c_void,
    pub nMaxCardNames: u32,
    pub lpfnCheck: *mut core::ffi::c_void,
    pub lpfnConnect: *mut core::ffi::c_void,
    pub lpfnDisconnect: *mut core::ffi::c_void,
    pub pvUserData: *mut core::ffi::c_void,
    pub dwShareMode: u32,
    pub dwPreferredProtocols: u32,
}
import "golang.org/x/sys/windows"

type OPENCARD_SEARCH_CRITERIAA struct {
	dwStructSize uint32
	lpstrGroupNames uintptr
	nMaxGroupNames uint32
	rgguidInterfaces uintptr
	cguidInterfaces uint32
	lpstrCardNames uintptr
	nMaxCardNames uint32
	lpfnCheck uintptr
	lpfnConnect uintptr
	lpfnDisconnect uintptr
	pvUserData uintptr
	dwShareMode uint32
	dwPreferredProtocols uint32
}
type
  OPENCARD_SEARCH_CRITERIAA = record
    dwStructSize: DWORD;
    lpstrGroupNames: Pointer;
    nMaxGroupNames: DWORD;
    rgguidInterfaces: Pointer;
    cguidInterfaces: DWORD;
    lpstrCardNames: Pointer;
    nMaxCardNames: DWORD;
    lpfnCheck: Pointer;
    lpfnConnect: Pointer;
    lpfnDisconnect: Pointer;
    pvUserData: Pointer;
    dwShareMode: DWORD;
    dwPreferredProtocols: DWORD;
  end;
const OPENCARD_SEARCH_CRITERIAA = extern struct {
    dwStructSize: u32,
    lpstrGroupNames: ?*anyopaque,
    nMaxGroupNames: u32,
    rgguidInterfaces: ?*anyopaque,
    cguidInterfaces: u32,
    lpstrCardNames: ?*anyopaque,
    nMaxCardNames: u32,
    lpfnCheck: ?*anyopaque,
    lpfnConnect: ?*anyopaque,
    lpfnDisconnect: ?*anyopaque,
    pvUserData: ?*anyopaque,
    dwShareMode: u32,
    dwPreferredProtocols: u32,
};
type
  OPENCARD_SEARCH_CRITERIAA {.bycopy.} = object
    dwStructSize: uint32
    lpstrGroupNames: pointer
    nMaxGroupNames: uint32
    rgguidInterfaces: pointer
    cguidInterfaces: uint32
    lpstrCardNames: pointer
    nMaxCardNames: uint32
    lpfnCheck: pointer
    lpfnConnect: pointer
    lpfnDisconnect: pointer
    pvUserData: pointer
    dwShareMode: uint32
    dwPreferredProtocols: uint32
struct OPENCARD_SEARCH_CRITERIAA
{
    uint dwStructSize;
    void* lpstrGroupNames;
    uint nMaxGroupNames;
    void* rgguidInterfaces;
    uint cguidInterfaces;
    void* lpstrCardNames;
    uint nMaxCardNames;
    void* lpfnCheck;
    void* lpfnConnect;
    void* lpfnDisconnect;
    void* pvUserData;
    uint dwShareMode;
    uint dwPreferredProtocols;
}

HSP用 定義

HSP3.7/3.8 は構造体機能が無いため4byte整数配列(dim)+peek/poke で操作(32/64bitでサイズ・位置が異なる場合はタブで分割)。IronHSP は NSTRUCT(#defstruct/stdim/->)で32/64bit共通。

; HSP3.7/3.8 は構造体機能が無いため、4byte整数の配列変数で操作します。(x86 レイアウト)
; OPENCARD_SEARCH_CRITERIAA サイズ: 52 バイト(x86)
dim st, 13    ; 4byte整数×13(構造体サイズ 52 / 4 切り上げ)
; dwStructSize : DWORD (+0, 4byte)  st.0 = 値  /  値 = st.0   (lpoke/lpeek も可)
; lpstrGroupNames : LPSTR (+4, 4byte)  st.1 = 値  /  値 = st.1   (lpoke/lpeek も可)
; nMaxGroupNames : DWORD (+8, 4byte)  st.2 = 値  /  値 = st.2   (lpoke/lpeek も可)
; rgguidInterfaces : GUID* (+12, 4byte)  varptr(st)+12 を基点に操作(4byte:入れ子/配列)
; cguidInterfaces : DWORD (+16, 4byte)  st.4 = 値  /  値 = st.4   (lpoke/lpeek も可)
; lpstrCardNames : LPSTR (+20, 4byte)  st.5 = 値  /  値 = st.5   (lpoke/lpeek も可)
; nMaxCardNames : DWORD (+24, 4byte)  st.6 = 値  /  値 = st.6   (lpoke/lpeek も可)
; lpfnCheck : LPOCNCHKPROC (+28, 4byte)  st.7 = 値  /  値 = st.7   (lpoke/lpeek も可)
; lpfnConnect : LPOCNCONNPROCA (+32, 4byte)  st.8 = 値  /  値 = st.8   (lpoke/lpeek も可)
; lpfnDisconnect : LPOCNDSCPROC (+36, 4byte)  st.9 = 値  /  値 = st.9   (lpoke/lpeek も可)
; pvUserData : void* (+40, 4byte)  st.10 = 値  /  値 = st.10   (lpoke/lpeek も可)
; dwShareMode : DWORD (+44, 4byte)  st.11 = 値  /  値 = st.11   (lpoke/lpeek も可)
; dwPreferredProtocols : DWORD (+48, 4byte)  st.12 = 値  /  値 = st.12   (lpoke/lpeek も可)
; ※4byte境界の整数は添字 st.N(N=オフセット/4)で読み書き可。それ以外は peek/poke 系を使用。
; HSP3.7/3.8 は構造体機能が無いため、4byte整数の配列変数で操作します。(x64 レイアウト)
; OPENCARD_SEARCH_CRITERIAA サイズ: 96 バイト(x64)
dim st, 24    ; 4byte整数×24(構造体サイズ 96 / 4 切り上げ)
; dwStructSize : DWORD (+0, 4byte)  st.0 = 値  /  値 = st.0   (lpoke/lpeek も可)
; lpstrGroupNames : LPSTR (+8, 8byte)  qpoke st,8,値 / qpeek(st,8)  ※IronHSPのみ。3.7/3.8は lpoke st,8,下位 : lpoke st,12,上位
; nMaxGroupNames : DWORD (+16, 4byte)  st.4 = 値  /  値 = st.4   (lpoke/lpeek も可)
; rgguidInterfaces : GUID* (+24, 8byte)  varptr(st)+24 を基点に操作(8byte:入れ子/配列)
; cguidInterfaces : DWORD (+32, 4byte)  st.8 = 値  /  値 = st.8   (lpoke/lpeek も可)
; lpstrCardNames : LPSTR (+40, 8byte)  qpoke st,40,値 / qpeek(st,40)  ※IronHSPのみ。3.7/3.8は lpoke st,40,下位 : lpoke st,44,上位
; nMaxCardNames : DWORD (+48, 4byte)  st.12 = 値  /  値 = st.12   (lpoke/lpeek も可)
; lpfnCheck : LPOCNCHKPROC (+56, 8byte)  qpoke st,56,値 / qpeek(st,56)  ※IronHSPのみ。3.7/3.8は lpoke st,56,下位 : lpoke st,60,上位
; lpfnConnect : LPOCNCONNPROCA (+64, 8byte)  qpoke st,64,値 / qpeek(st,64)  ※IronHSPのみ。3.7/3.8は lpoke st,64,下位 : lpoke st,68,上位
; lpfnDisconnect : LPOCNDSCPROC (+72, 8byte)  qpoke st,72,値 / qpeek(st,72)  ※IronHSPのみ。3.7/3.8は lpoke st,72,下位 : lpoke st,76,上位
; pvUserData : void* (+80, 8byte)  qpoke st,80,値 / qpeek(st,80)  ※IronHSPのみ。3.7/3.8は lpoke st,80,下位 : lpoke st,84,上位
; dwShareMode : DWORD (+88, 4byte)  st.22 = 値  /  値 = st.22   (lpoke/lpeek も可)
; dwPreferredProtocols : DWORD (+92, 4byte)  st.23 = 値  /  値 = st.23   (lpoke/lpeek も可)
; ※4byte境界の整数は添字 st.N(N=オフセット/4)で読み書き可。それ以外は peek/poke 系を使用。
; IronHSP は NSTRUCT(構造体)をサポート。32bit/64bit どちらでも同じコードで動作します。
#defstruct global OPENCARD_SEARCH_CRITERIAA
    #field int dwStructSize
    #field intptr lpstrGroupNames
    #field int nMaxGroupNames
    #field intptr rgguidInterfaces
    #field int cguidInterfaces
    #field intptr lpstrCardNames
    #field int nMaxCardNames
    #field intptr lpfnCheck
    #field intptr lpfnConnect
    #field intptr lpfnDisconnect
    #field intptr pvUserData
    #field int dwShareMode
    #field int dwPreferredProtocols
#endstruct

stdim st, OPENCARD_SEARCH_CRITERIAA        ; NSTRUCT 変数を確保
st->dwStructSize = 100
mes "dwStructSize=" + st->dwStructSize