ホーム › Security.Credentials › SCardControl

SCardControl

関数

スマートカードリーダーへ直接制御コマンドを送る。

DLLWinSCard.dll呼出規約winapi対応OSWindows XP 以降

シグネチャ

// WinSCard.dll
#include <windows.h>

INT SCardControl(
    UINT_PTR hCard,
    DWORD dwControlCode,
    const void* lpInBuffer,
    DWORD cbInBufferSize,
    void* lpOutBuffer,
    DWORD cbOutBufferSize,
    DWORD* lpBytesReturned
);

パラメーター

名前	型	方向	説明
hCard	UINT_PTR	in	SCardConnect から返された参照値。
dwControlCode	DWORD	in	操作の制御コード。この値は実行する特定の操作を識別します。
lpInBuffer	void*	in	操作の実行に必要なデータを格納するバッファーへのポインター。dwControlCode パラメーターが入力データを必要としない操作を指定する場合、このパラメーターは NULL にできます。
cbInBufferSize	DWORD	in	lpInBuffer が指すバッファーのサイズ(バイト単位)。
lpOutBuffer	void*	out	操作の出力データを受け取るバッファーへのポインター。dwControlCode パラメーターが出力データを生成しない操作を指定する場合、このパラメーターは NULL にできます。
cbOutBufferSize	DWORD	in	lpOutBuffer が指すバッファーのサイズ(バイト単位)。
lpBytesReturned	DWORD*	out	lpOutBuffer が指すバッファーに格納されたデータのサイズ(バイト単位)を受け取る DWORD へのポインター。

戻り値の型: INT

公式ドキュメント

リーダーを直接制御できます。SCardConnect の呼び出しが成功した後、SCardDisconnect の呼び出しが成功する前であれば、いつでも呼び出すことができます。

戻り値

この関数は、成功するか失敗するかに応じて異なる値を返します。

戻り値	説明
成功	SCARD_S_SUCCESS。
失敗	エラーコード。詳細については、 Smart Card Return Values を参照してください。

解説(Remarks)

SCardControl 関数はカードへの直接アクセス関数です。その他の直接アクセス関数の詳細については、 Direct Card Access Functions を参照してください。

例

次の例は制御コードを発行します。この例では、hCardHandle が以前の SCardConnect 呼び出しから受け取った有効なハンドルであり、dwControlCode が事前に有効な制御コードで初期化された DWORD 型の変数であることを前提としています。この特定の制御コードは入力データを必要とせず、出力データも想定していません。


lReturn = SCardControl( hCardHandle,
                        dwControlCode,
                        NULL,
                        0,
                        NULL,
                        0,
                        0 );
if ( SCARD_S_SUCCESS != lReturn )
    printf("Failed SCardControl\n");

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

各言語での呼び出し定義

// WinSCard.dll
#include <windows.h>

INT SCardControl(
    UINT_PTR hCard,
    DWORD dwControlCode,
    const void* lpInBuffer,
    DWORD cbInBufferSize,
    void* lpOutBuffer,
    DWORD cbOutBufferSize,
    DWORD* lpBytesReturned
);

[DllImport("WinSCard.dll", ExactSpelling = true)]
static extern int SCardControl(
    UIntPtr hCard,   // UINT_PTR
    uint dwControlCode,   // DWORD
    IntPtr lpInBuffer,   // void*
    uint cbInBufferSize,   // DWORD
    IntPtr lpOutBuffer,   // void* out
    uint cbOutBufferSize,   // DWORD
    out uint lpBytesReturned   // DWORD* out
);

<DllImport("WinSCard.dll", ExactSpelling:=True)>
Public Shared Function SCardControl(
    hCard As UIntPtr,   ' UINT_PTR
    dwControlCode As UInteger,   ' DWORD
    lpInBuffer As IntPtr,   ' void*
    cbInBufferSize As UInteger,   ' DWORD
    lpOutBuffer As IntPtr,   ' void* out
    cbOutBufferSize As UInteger,   ' DWORD
    <Out> ByRef lpBytesReturned As UInteger   ' DWORD* out
) As Integer
End Function

' hCard : UINT_PTR
' dwControlCode : DWORD
' lpInBuffer : void*
' cbInBufferSize : DWORD
' lpOutBuffer : void* out
' cbOutBufferSize : DWORD
' lpBytesReturned : DWORD* out
Declare PtrSafe Function SCardControl Lib "winscard" ( _
    ByVal hCard As LongPtr, _
    ByVal dwControlCode As Long, _
    ByVal lpInBuffer As LongPtr, _
    ByVal cbInBufferSize As Long, _
    ByVal lpOutBuffer As LongPtr, _
    ByVal cbOutBufferSize As Long, _
    ByRef lpBytesReturned As Long) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

SCardControl = ctypes.windll.winscard.SCardControl
SCardControl.restype = ctypes.c_int
SCardControl.argtypes = [
    ctypes.c_size_t,  # hCard : UINT_PTR
    wintypes.DWORD,  # dwControlCode : DWORD
    ctypes.POINTER(None),  # lpInBuffer : void*
    wintypes.DWORD,  # cbInBufferSize : DWORD
    ctypes.POINTER(None),  # lpOutBuffer : void* out
    wintypes.DWORD,  # cbOutBufferSize : DWORD
    ctypes.POINTER(wintypes.DWORD),  # lpBytesReturned : DWORD* out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('WinSCard.dll')
SCardControl = Fiddle::Function.new(
  lib['SCardControl'],
  [
    Fiddle::TYPE_UINTPTR_T,  # hCard : UINT_PTR
    -Fiddle::TYPE_INT,  # dwControlCode : DWORD
    Fiddle::TYPE_VOIDP,  # lpInBuffer : void*
    -Fiddle::TYPE_INT,  # cbInBufferSize : DWORD
    Fiddle::TYPE_VOIDP,  # lpOutBuffer : void* out
    -Fiddle::TYPE_INT,  # cbOutBufferSize : DWORD
    Fiddle::TYPE_VOIDP,  # lpBytesReturned : DWORD* out
  ],
  Fiddle::TYPE_INT)

#[link(name = "winscard")]
extern "system" {
    fn SCardControl(
        hCard: usize,  // UINT_PTR
        dwControlCode: u32,  // DWORD
        lpInBuffer: *const (),  // void*
        cbInBufferSize: u32,  // DWORD
        lpOutBuffer: *mut (),  // void* out
        cbOutBufferSize: u32,  // DWORD
        lpBytesReturned: *mut u32  // DWORD* out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("WinSCard.dll")]
public static extern int SCardControl(UIntPtr hCard, uint dwControlCode, IntPtr lpInBuffer, uint cbInBufferSize, IntPtr lpOutBuffer, uint cbOutBufferSize, out uint lpBytesReturned);
"@
$api = Add-Type -MemberDefinition $sig -Name 'WinSCard_SCardControl' -Namespace Win32 -PassThru
# $api::SCardControl(hCard, dwControlCode, lpInBuffer, cbInBufferSize, lpOutBuffer, cbOutBufferSize, lpBytesReturned)

#uselib "WinSCard.dll"
#func global SCardControl "SCardControl" sptr, sptr, sptr, sptr, sptr, sptr, sptr
; SCardControl hCard, dwControlCode, lpInBuffer, cbInBufferSize, lpOutBuffer, cbOutBufferSize, varptr(lpBytesReturned)   ; 戻り値は stat
; hCard : UINT_PTR -> "sptr"
; dwControlCode : DWORD -> "sptr"
; lpInBuffer : void* -> "sptr"
; cbInBufferSize : DWORD -> "sptr"
; lpOutBuffer : void* out -> "sptr"
; cbOutBufferSize : DWORD -> "sptr"
; lpBytesReturned : DWORD* out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "WinSCard.dll"
#cfunc global SCardControl "SCardControl" sptr, int, sptr, int, sptr, int, var
; res = SCardControl(hCard, dwControlCode, lpInBuffer, cbInBufferSize, lpOutBuffer, cbOutBufferSize, lpBytesReturned)
; hCard : UINT_PTR -> "sptr"
; dwControlCode : DWORD -> "int"
; lpInBuffer : void* -> "sptr"
; cbInBufferSize : DWORD -> "int"
; lpOutBuffer : void* out -> "sptr"
; cbOutBufferSize : DWORD -> "int"
; lpBytesReturned : DWORD* out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "WinSCard.dll"
#cfunc global SCardControl "SCardControl" sptr, int, sptr, int, sptr, int, sptr
; res = SCardControl(hCard, dwControlCode, lpInBuffer, cbInBufferSize, lpOutBuffer, cbOutBufferSize, varptr(lpBytesReturned))
; hCard : UINT_PTR -> "sptr"
; dwControlCode : DWORD -> "int"
; lpInBuffer : void* -> "sptr"
; cbInBufferSize : DWORD -> "int"
; lpOutBuffer : void* out -> "sptr"
; cbOutBufferSize : DWORD -> "int"
; lpBytesReturned : DWORD* out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。