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

OPENCARDNAME_EXW

構造体
サイズx64: 128 バイト / x86: 72 バイト

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

フィールド

フィールドサイズx64x86説明
dwStructSizeDWORD4+0+0構造体の長さ (バイト単位)。このメンバーの値は NULL であってはなりません。
hSCardContextUINT_PTR8/4+8+4スマート カード リソース マネージャー との通信に使用するコンテキストです。 SCardEstablishContext を呼び出して リソース マネージャー コンテキスト を設定し、 SCardReleaseContext を呼び出して解放します。このメンバーの値は NULL であってはなりません。
hwndOwnerHWND8/4+16+8ダイアログ ボックスを所有するウィンドウです。このメンバーには任意の有効なウィンドウ ハンドルを指定できます。また、デスクトップを既定として使用する場合は NULL を指定できます。
dwFlagsDWORD4+24+12

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

意味
SC_DLG_MINIMAL_UI
呼び出し元アプリケーションが検索しているカードが見つからず、リーダーで使用できない場合にのみ、ダイアログ ボックスを表示します。これにより、カードを検索し、(内部のダイアログ ボックス機構またはユーザーのコールバック関数によって) 接続して、呼び出し元アプリケーションに返すことができます。
SC_DLG_NO_UI
検索結果に関係なく、Select Card ユーザー インターフェイス (UI) を表示しないように強制します。
SC_DLG_FORCE_UI
検索結果に関係なく、Select Card UI を強制的に表示します。
lpstrTitleLPWSTR8/4+32+16ダイアログ ボックスのタイトル バーに表示する文字列へのポインターです。このメンバーが NULL の場合、システムは既定のタイトル "Select Card:" を使用します。
lpstrSearchDescLPWSTR8/4+40+20スマート カード の挿入を促すプロンプトとしてユーザーに表示する文字列へのポインターです。このメンバーが NULL の場合、システムは既定のテキスト "Please insert a smart card" を使用します。
hIconHICON8/4+48+24アイコン (32 x 32 ピクセル) のハンドルです。ダイアログ ボックスに表示するベンダー固有のアイコンを指定できます。この値が NULL の場合は、汎用のスマート カード リーダーのアイコンが表示されます。
pOpenCardSearchCriteriaOPENCARD_SEARCH_CRITERIAW*8/4+56+28使用する OPENCARD_SEARCH_CRITERIA 構造体へのポインターです。使用しない場合は NULL を指定します。
lpfnConnectLPOCNCONNPROCW8/4+64+32

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

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

Connect(
  hSCardContext,  // パラメーター ブロックで渡されたカード コンテキスト
  szReader,       // リーダーの名前
  mszCards,       // リーダー内に存在し得るカード名を格納する
                  //  複数文字列
  pvUserData      // パラメーター ブロックで渡されたユーザー データへのポインター
);
pvUserDatavoid*8/4+72+36ユーザー データへの void ポインターです。このポインターは Connect ルーチンで呼び出し元に渡されます。
dwShareModeDWORD4+80+40lpfnConnectNULL でない場合、dwShareMode メンバーと dwPreferredProtocols メンバーは無視されます。lpfnConnectNULLdwShareMode が 0 以外の場合は、dwShareModedwPreferredProtocolsdwShareMode パラメーターおよび dwPreferredProtocols パラメーターとして使用して、 SCardConnect への内部呼び出しが行われます。接続に成功すると、hCardHandle には SCardConnect が返したハンドルが設定されます。lpfnConnectNULLdwShareMode が 0 の場合、hCardHandle には NULL が設定されます。
dwPreferredProtocolsDWORD4+84+44dwShareMode で説明されている内部接続に使用されます。
lpstrRdrLPWSTR8/4+88+48カードが見つかった場合、lpstrRdr バッファーには、そのカードが挿入されているリーダーの名前が格納されます。バッファーは 256 文字以上の長さである必要があります。
nMaxRdrDWORD4+96+52lpstrRdr が指すバッファーのサイズ。バイト単位 (ANSI 版) または文字単位 (Unicode 版) です。バッファーが小さすぎてリーダー情報を格納できない場合、 SCardUIDlgSelectCardSCARD_E_NO_MEMORY と、lpstrRdr が指すバッファーに必要なサイズを返します。
lpstrCardLPWSTR8/4+104+56カードが見つかった場合、lpstrCard バッファーには、見つかったカードの名前が格納されます。バッファーは 256 文字以上の長さである必要があります。
nMaxCardDWORD4+112+60lpstrCard が指すバッファーのサイズ。バイト単位 (ANSI 版) または文字単位 (Unicode 版) です。バッファーが小さすぎてカード情報を格納できない場合、 SCardUIDlgSelectCardSCARD_E_NO_MEMORY と、必要なバッファーのサイズを nMaxCard に返します。
dwActiveProtocolDWORD4+116+64ダイアログ ボックスがカードに接続したときに実際に使用されているプロトコルです。
hCardHandleUINT_PTR8/4+120+68接続されたカードのハンドルです (内部のダイアログ ボックスによる接続、または lpfnConnect コールバックのいずれかによるもの)。

公式ドキュメント

OPENCARDNAME_EX 構造体は、 SCardUIDlgSelectCard 関数がスマート カードの Select Card ダイアログ ボックスを初期化するために使用する情報を格納します。

解説(Remarks)

メモ

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

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

各言語での定義

#include <windows.h>

// OPENCARDNAME_EXW  (x64 128 / x86 72 バイト)
typedef struct OPENCARDNAME_EXW {
    DWORD dwStructSize;
    UINT_PTR hSCardContext;
    HWND hwndOwner;
    DWORD dwFlags;
    LPWSTR lpstrTitle;
    LPWSTR lpstrSearchDesc;
    HICON hIcon;
    OPENCARD_SEARCH_CRITERIAW* pOpenCardSearchCriteria;
    LPOCNCONNPROCW lpfnConnect;
    void* pvUserData;
    DWORD dwShareMode;
    DWORD dwPreferredProtocols;
    LPWSTR lpstrRdr;
    DWORD nMaxRdr;
    LPWSTR lpstrCard;
    DWORD nMaxCard;
    DWORD dwActiveProtocol;
    UINT_PTR hCardHandle;
} OPENCARDNAME_EXW;
using System;
using System.Runtime.InteropServices;

[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
public struct OPENCARDNAME_EXW
{
    public uint dwStructSize;
    public UIntPtr hSCardContext;
    public IntPtr hwndOwner;
    public uint dwFlags;
    public IntPtr lpstrTitle;
    public IntPtr lpstrSearchDesc;
    public IntPtr hIcon;
    public IntPtr pOpenCardSearchCriteria;
    public IntPtr lpfnConnect;
    public IntPtr pvUserData;
    public uint dwShareMode;
    public uint dwPreferredProtocols;
    public IntPtr lpstrRdr;
    public uint nMaxRdr;
    public IntPtr lpstrCard;
    public uint nMaxCard;
    public uint dwActiveProtocol;
    public UIntPtr hCardHandle;
}
Imports System.Runtime.InteropServices

<StructLayout(LayoutKind.Sequential, CharSet:=CharSet.Unicode)>
Public Structure OPENCARDNAME_EXW
    Public dwStructSize As UInteger
    Public hSCardContext As UIntPtr
    Public hwndOwner As IntPtr
    Public dwFlags As UInteger
    Public lpstrTitle As IntPtr
    Public lpstrSearchDesc As IntPtr
    Public hIcon As IntPtr
    Public pOpenCardSearchCriteria As IntPtr
    Public lpfnConnect As IntPtr
    Public pvUserData As IntPtr
    Public dwShareMode As UInteger
    Public dwPreferredProtocols As UInteger
    Public lpstrRdr As IntPtr
    Public nMaxRdr As UInteger
    Public lpstrCard As IntPtr
    Public nMaxCard As UInteger
    Public dwActiveProtocol As UInteger
    Public hCardHandle As UIntPtr
End Structure
import ctypes
from ctypes import wintypes

class OPENCARDNAME_EXW(ctypes.Structure):
    _fields_ = [
        ("dwStructSize", wintypes.DWORD),
        ("hSCardContext", ctypes.c_size_t),
        ("hwndOwner", ctypes.c_void_p),
        ("dwFlags", wintypes.DWORD),
        ("lpstrTitle", ctypes.c_void_p),
        ("lpstrSearchDesc", ctypes.c_void_p),
        ("hIcon", ctypes.c_void_p),
        ("pOpenCardSearchCriteria", ctypes.c_void_p),
        ("lpfnConnect", ctypes.c_void_p),
        ("pvUserData", ctypes.c_void_p),
        ("dwShareMode", wintypes.DWORD),
        ("dwPreferredProtocols", wintypes.DWORD),
        ("lpstrRdr", ctypes.c_void_p),
        ("nMaxRdr", wintypes.DWORD),
        ("lpstrCard", ctypes.c_void_p),
        ("nMaxCard", wintypes.DWORD),
        ("dwActiveProtocol", wintypes.DWORD),
        ("hCardHandle", ctypes.c_size_t),
    ]
#[repr(C)]
pub struct OPENCARDNAME_EXW {
    pub dwStructSize: u32,
    pub hSCardContext: usize,
    pub hwndOwner: *mut core::ffi::c_void,
    pub dwFlags: u32,
    pub lpstrTitle: *mut core::ffi::c_void,
    pub lpstrSearchDesc: *mut core::ffi::c_void,
    pub hIcon: *mut core::ffi::c_void,
    pub pOpenCardSearchCriteria: *mut core::ffi::c_void,
    pub lpfnConnect: *mut core::ffi::c_void,
    pub pvUserData: *mut core::ffi::c_void,
    pub dwShareMode: u32,
    pub dwPreferredProtocols: u32,
    pub lpstrRdr: *mut core::ffi::c_void,
    pub nMaxRdr: u32,
    pub lpstrCard: *mut core::ffi::c_void,
    pub nMaxCard: u32,
    pub dwActiveProtocol: u32,
    pub hCardHandle: usize,
}
import "golang.org/x/sys/windows"

type OPENCARDNAME_EXW struct {
	dwStructSize uint32
	hSCardContext uintptr
	hwndOwner uintptr
	dwFlags uint32
	lpstrTitle uintptr
	lpstrSearchDesc uintptr
	hIcon uintptr
	pOpenCardSearchCriteria uintptr
	lpfnConnect uintptr
	pvUserData uintptr
	dwShareMode uint32
	dwPreferredProtocols uint32
	lpstrRdr uintptr
	nMaxRdr uint32
	lpstrCard uintptr
	nMaxCard uint32
	dwActiveProtocol uint32
	hCardHandle uintptr
}
type
  OPENCARDNAME_EXW = record
    dwStructSize: DWORD;
    hSCardContext: NativeUInt;
    hwndOwner: Pointer;
    dwFlags: DWORD;
    lpstrTitle: Pointer;
    lpstrSearchDesc: Pointer;
    hIcon: Pointer;
    pOpenCardSearchCriteria: Pointer;
    lpfnConnect: Pointer;
    pvUserData: Pointer;
    dwShareMode: DWORD;
    dwPreferredProtocols: DWORD;
    lpstrRdr: Pointer;
    nMaxRdr: DWORD;
    lpstrCard: Pointer;
    nMaxCard: DWORD;
    dwActiveProtocol: DWORD;
    hCardHandle: NativeUInt;
  end;
const OPENCARDNAME_EXW = extern struct {
    dwStructSize: u32,
    hSCardContext: usize,
    hwndOwner: ?*anyopaque,
    dwFlags: u32,
    lpstrTitle: ?*anyopaque,
    lpstrSearchDesc: ?*anyopaque,
    hIcon: ?*anyopaque,
    pOpenCardSearchCriteria: ?*anyopaque,
    lpfnConnect: ?*anyopaque,
    pvUserData: ?*anyopaque,
    dwShareMode: u32,
    dwPreferredProtocols: u32,
    lpstrRdr: ?*anyopaque,
    nMaxRdr: u32,
    lpstrCard: ?*anyopaque,
    nMaxCard: u32,
    dwActiveProtocol: u32,
    hCardHandle: usize,
};
type
  OPENCARDNAME_EXW {.bycopy.} = object
    dwStructSize: uint32
    hSCardContext: uint
    hwndOwner: pointer
    dwFlags: uint32
    lpstrTitle: pointer
    lpstrSearchDesc: pointer
    hIcon: pointer
    pOpenCardSearchCriteria: pointer
    lpfnConnect: pointer
    pvUserData: pointer
    dwShareMode: uint32
    dwPreferredProtocols: uint32
    lpstrRdr: pointer
    nMaxRdr: uint32
    lpstrCard: pointer
    nMaxCard: uint32
    dwActiveProtocol: uint32
    hCardHandle: uint
struct OPENCARDNAME_EXW
{
    uint dwStructSize;
    size_t hSCardContext;
    void* hwndOwner;
    uint dwFlags;
    void* lpstrTitle;
    void* lpstrSearchDesc;
    void* hIcon;
    void* pOpenCardSearchCriteria;
    void* lpfnConnect;
    void* pvUserData;
    uint dwShareMode;
    uint dwPreferredProtocols;
    void* lpstrRdr;
    uint nMaxRdr;
    void* lpstrCard;
    uint nMaxCard;
    uint dwActiveProtocol;
    size_t hCardHandle;
}

HSP用 定義

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

; HSP3.7/3.8 は構造体機能が無いため、4byte整数の配列変数で操作します。(x86 レイアウト)
; OPENCARDNAME_EXW サイズ: 72 バイト(x86)
dim st, 18    ; 4byte整数×18(構造体サイズ 72 / 4 切り上げ)
; dwStructSize : DWORD (+0, 4byte)  st.0 = 値  /  値 = st.0   (lpoke/lpeek も可)
; hSCardContext : UINT_PTR (+4, 4byte)  st.1 = 値  /  値 = st.1   (lpoke/lpeek も可)
; hwndOwner : HWND (+8, 4byte)  st.2 = 値  /  値 = st.2   (lpoke/lpeek も可)
; dwFlags : DWORD (+12, 4byte)  st.3 = 値  /  値 = st.3   (lpoke/lpeek も可)
; lpstrTitle : LPWSTR (+16, 4byte)  st.4 = 値  /  値 = st.4   (lpoke/lpeek も可)
; lpstrSearchDesc : LPWSTR (+20, 4byte)  st.5 = 値  /  値 = st.5   (lpoke/lpeek も可)
; hIcon : HICON (+24, 4byte)  st.6 = 値  /  値 = st.6   (lpoke/lpeek も可)
; pOpenCardSearchCriteria : OPENCARD_SEARCH_CRITERIAW* (+28, 4byte)  varptr(st)+28 を基点に操作(4byte:入れ子/配列)
; lpfnConnect : LPOCNCONNPROCW (+32, 4byte)  st.8 = 値  /  値 = st.8   (lpoke/lpeek も可)
; pvUserData : void* (+36, 4byte)  st.9 = 値  /  値 = st.9   (lpoke/lpeek も可)
; dwShareMode : DWORD (+40, 4byte)  st.10 = 値  /  値 = st.10   (lpoke/lpeek も可)
; dwPreferredProtocols : DWORD (+44, 4byte)  st.11 = 値  /  値 = st.11   (lpoke/lpeek も可)
; lpstrRdr : LPWSTR (+48, 4byte)  st.12 = 値  /  値 = st.12   (lpoke/lpeek も可)
; nMaxRdr : DWORD (+52, 4byte)  st.13 = 値  /  値 = st.13   (lpoke/lpeek も可)
; lpstrCard : LPWSTR (+56, 4byte)  st.14 = 値  /  値 = st.14   (lpoke/lpeek も可)
; nMaxCard : DWORD (+60, 4byte)  st.15 = 値  /  値 = st.15   (lpoke/lpeek も可)
; dwActiveProtocol : DWORD (+64, 4byte)  st.16 = 値  /  値 = st.16   (lpoke/lpeek も可)
; hCardHandle : UINT_PTR (+68, 4byte)  st.17 = 値  /  値 = st.17   (lpoke/lpeek も可)
; ※4byte境界の整数は添字 st.N(N=オフセット/4)で読み書き可。それ以外は peek/poke 系を使用。
; HSP3.7/3.8 は構造体機能が無いため、4byte整数の配列変数で操作します。(x64 レイアウト)
; OPENCARDNAME_EXW サイズ: 128 バイト(x64)
dim st, 32    ; 4byte整数×32(構造体サイズ 128 / 4 切り上げ)
; dwStructSize : DWORD (+0, 4byte)  st.0 = 値  /  値 = st.0   (lpoke/lpeek も可)
; hSCardContext : UINT_PTR (+8, 8byte)  qpoke st,8,値 / qpeek(st,8)  ※IronHSPのみ。3.7/3.8は lpoke st,8,下位 : lpoke st,12,上位
; hwndOwner : HWND (+16, 8byte)  qpoke st,16,値 / qpeek(st,16)  ※IronHSPのみ。3.7/3.8は lpoke st,16,下位 : lpoke st,20,上位
; dwFlags : DWORD (+24, 4byte)  st.6 = 値  /  値 = st.6   (lpoke/lpeek も可)
; lpstrTitle : LPWSTR (+32, 8byte)  qpoke st,32,値 / qpeek(st,32)  ※IronHSPのみ。3.7/3.8は lpoke st,32,下位 : lpoke st,36,上位
; lpstrSearchDesc : LPWSTR (+40, 8byte)  qpoke st,40,値 / qpeek(st,40)  ※IronHSPのみ。3.7/3.8は lpoke st,40,下位 : lpoke st,44,上位
; hIcon : HICON (+48, 8byte)  qpoke st,48,値 / qpeek(st,48)  ※IronHSPのみ。3.7/3.8は lpoke st,48,下位 : lpoke st,52,上位
; pOpenCardSearchCriteria : OPENCARD_SEARCH_CRITERIAW* (+56, 8byte)  varptr(st)+56 を基点に操作(8byte:入れ子/配列)
; lpfnConnect : LPOCNCONNPROCW (+64, 8byte)  qpoke st,64,値 / qpeek(st,64)  ※IronHSPのみ。3.7/3.8は lpoke st,64,下位 : lpoke st,68,上位
; pvUserData : void* (+72, 8byte)  qpoke st,72,値 / qpeek(st,72)  ※IronHSPのみ。3.7/3.8は lpoke st,72,下位 : lpoke st,76,上位
; dwShareMode : DWORD (+80, 4byte)  st.20 = 値  /  値 = st.20   (lpoke/lpeek も可)
; dwPreferredProtocols : DWORD (+84, 4byte)  st.21 = 値  /  値 = st.21   (lpoke/lpeek も可)
; lpstrRdr : LPWSTR (+88, 8byte)  qpoke st,88,値 / qpeek(st,88)  ※IronHSPのみ。3.7/3.8は lpoke st,88,下位 : lpoke st,92,上位
; nMaxRdr : DWORD (+96, 4byte)  st.24 = 値  /  値 = st.24   (lpoke/lpeek も可)
; lpstrCard : LPWSTR (+104, 8byte)  qpoke st,104,値 / qpeek(st,104)  ※IronHSPのみ。3.7/3.8は lpoke st,104,下位 : lpoke st,108,上位
; nMaxCard : DWORD (+112, 4byte)  st.28 = 値  /  値 = st.28   (lpoke/lpeek も可)
; dwActiveProtocol : DWORD (+116, 4byte)  st.29 = 値  /  値 = st.29   (lpoke/lpeek も可)
; hCardHandle : UINT_PTR (+120, 8byte)  qpoke st,120,値 / qpeek(st,120)  ※IronHSPのみ。3.7/3.8は lpoke st,120,下位 : lpoke st,124,上位
; ※4byte境界の整数は添字 st.N(N=オフセット/4)で読み書き可。それ以外は peek/poke 系を使用。
; IronHSP は NSTRUCT(構造体)をサポート。32bit/64bit どちらでも同じコードで動作します。
#defstruct global OPENCARDNAME_EXW
    #field int dwStructSize
    #field intptr hSCardContext
    #field intptr hwndOwner
    #field int dwFlags
    #field intptr lpstrTitle
    #field intptr lpstrSearchDesc
    #field intptr hIcon
    #field intptr pOpenCardSearchCriteria
    #field intptr lpfnConnect
    #field intptr pvUserData
    #field int dwShareMode
    #field int dwPreferredProtocols
    #field intptr lpstrRdr
    #field int nMaxRdr
    #field intptr lpstrCard
    #field int nMaxCard
    #field int dwActiveProtocol
    #field intptr hCardHandle
#endstruct

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