ホーム › Security.Credentials › SCardTransmit

SCardTransmit

関数

スマートカードへAPDUを送信し応答を受信する。

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

シグネチャ

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

INT SCardTransmit(
    UINT_PTR hCard,
    SCARD_IO_REQUEST* pioSendPci,
    BYTE* pbSendBuffer,
    DWORD cbSendLength,
    SCARD_IO_REQUEST* pioRecvPci,   // optional
    BYTE* pbRecvBuffer,
    DWORD* pcbRecvLength
);

パラメーター

名前型方向説明

hCard UINT_PTR in SCardConnect 関数から返された参照値です。

pioSendPci

SCARD_IO_REQUEST*

命令のプロトコルヘッダー構造体へのポインターです。このバッファーは SCARD_IO_REQUEST 構造体の形式で、その後に固有のプロトコル制御情報 (PCI) が続きます。

T=0、T=1、および Raw プロトコルでは、PCI 構造体は一定です。smart card subsystem はグローバルな T=0、T=1、または Raw の PCI 構造体を提供しており、それぞれ SCARD_PCI_T0、SCARD_PCI_T1、SCARD_PCI_RAW というシンボルで参照できます。

pbSendBuffer

BYTE*

カードに書き込む実際のデータへのポインターです。

T=0 の場合、データパラメーターは次の構造体に従って pbSendBuffer が指すアドレスに配置されます。

struct {
    BYTE
        bCla,   // the instruction class
        bIns,   // the instruction code 
        bP1,    // parameter to the instruction
        bP2,    // parameter to the instruction
        bP3;    // size of I/O transfer
} CmdBytes;

カードに送信されるデータは、送信バッファーの直後に続ける必要があります。カードにデータを送信せず、かつ返されるデータも期待しない特殊なケースでは、bP3 は送信されません。

メンバー	意味
bCla	T=0 の命令クラスです。
bIns	T=0 命令クラス内の命令コードです。
bP1, bP2	命令コードを補完する参照コードです。
bP3	ISO 7816-4 のセクション 8.2.1 に従い、コマンド中に転送されるデータバイト数です。

cbSendLength

DWORD

pbSendBuffer パラメーターの長さ (バイト単位) です。

T=0 の場合、カードにデータを送信せず、かつ返されるデータも期待しない特殊なケースでは、この長さは bP3 メンバーが送信されないことを反映する必要があり、sizeof(CmdBytes) - sizeof(BYTE) とする必要があります。

pioRecvPci SCARD_IO_REQUEST* inoutoptional 命令のプロトコルヘッダー構造体へのポインターで、その後に使用中のプロトコルに固有の、返されるプロトコル制御情報 (PCI) を受け取るバッファーが続きます。PCI が返されない場合、このパラメーターは NULL にできます。

pbRecvBuffer

BYTE*

out

カードから返されるデータへのポインターです。

T=0 の場合、データの直後に SW1 および SW2 のステータスバイトが続きます。カードからデータが返されない場合、このバッファーには SW1 および SW2 のステータスバイトのみが格納されます。

pcbRecvLength

DWORD*

inout

pbRecvBuffer パラメーターの長さ (バイト単位) を渡し、スマートカードから実際に受信したバイト数を受け取ります。

SCardTransmit は SCARD_AUTOALLOCATE をサポートしていないため、この値を SCARD_AUTOALLOCATE にすることはできません。

T=0 の場合、SW1 および SW2 のステータスバイトを受け取るため、受信バッファーは少なくとも 2 バイトの長さが必要です。

戻り値の型: INT

公式ドキュメント

スマートカードにサービス要求を送信し、カードからデータが返されることを期待します。

戻り値

関数が smart card へのサービス要求の送信に成功した場合、戻り値は SCARD_S_SUCCESS です。

関数が失敗した場合は、エラーコードを返します。詳細については、Smart Card Return Values を参照してください。

解説(Remarks)

SCardTransmit 関数は、smart card および reader アクセス関数です。その他のアクセス関数については、Smart Card and Reader Access Functions を参照してください。

T=0 protocol の場合、返されるデータは SW1 および SW2 のステータスコードであり、その前に応答データが付くこともあります。以降の段落では、データの転送やコマンドの発行に使用される送信バッファーおよび受信バッファーについて説明します。

例

次の例は、スマートカードへのサービス要求の送信を示しています。

//  Transmit the request.
//  lReturn is of type LONG.
//  hCardHandle was set by a previous call to SCardConnect.
//  pbSend points to the buffer of bytes to send.
//  dwSend is the DWORD value for the number of bytes to send.
//  pbRecv points to the buffer for returned bytes.
//  dwRecv is the DWORD value for the number of returned bytes.
lReturn = SCardTransmit(hCardHandle,
                        SCARD_PCI_T0,
                        pbSend,
                        dwSend,
                        NULL,
                        pbRecv,
                        &dwRecv );
if ( SCARD_S_SUCCESS != lReturn )
{
    printf("Failed SCardTransmit\n");
    exit(1);   // or other appropriate error action
}

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

各言語での呼び出し定義

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

INT SCardTransmit(
    UINT_PTR hCard,
    SCARD_IO_REQUEST* pioSendPci,
    BYTE* pbSendBuffer,
    DWORD cbSendLength,
    SCARD_IO_REQUEST* pioRecvPci,   // optional
    BYTE* pbRecvBuffer,
    DWORD* pcbRecvLength
);

[DllImport("WinSCard.dll", ExactSpelling = true)]
static extern int SCardTransmit(
    UIntPtr hCard,   // UINT_PTR
    IntPtr pioSendPci,   // SCARD_IO_REQUEST*
    IntPtr pbSendBuffer,   // BYTE*
    uint cbSendLength,   // DWORD
    IntPtr pioRecvPci,   // SCARD_IO_REQUEST* optional, in/out
    IntPtr pbRecvBuffer,   // BYTE* out
    ref uint pcbRecvLength   // DWORD* in/out
);

<DllImport("WinSCard.dll", ExactSpelling:=True)>
Public Shared Function SCardTransmit(
    hCard As UIntPtr,   ' UINT_PTR
    pioSendPci As IntPtr,   ' SCARD_IO_REQUEST*
    pbSendBuffer As IntPtr,   ' BYTE*
    cbSendLength As UInteger,   ' DWORD
    pioRecvPci As IntPtr,   ' SCARD_IO_REQUEST* optional, in/out
    pbRecvBuffer As IntPtr,   ' BYTE* out
    ByRef pcbRecvLength As UInteger   ' DWORD* in/out
) As Integer
End Function

' hCard : UINT_PTR
' pioSendPci : SCARD_IO_REQUEST*
' pbSendBuffer : BYTE*
' cbSendLength : DWORD
' pioRecvPci : SCARD_IO_REQUEST* optional, in/out
' pbRecvBuffer : BYTE* out
' pcbRecvLength : DWORD* in/out
Declare PtrSafe Function SCardTransmit Lib "winscard" ( _
    ByVal hCard As LongPtr, _
    ByVal pioSendPci As LongPtr, _
    ByVal pbSendBuffer As LongPtr, _
    ByVal cbSendLength As Long, _
    ByVal pioRecvPci As LongPtr, _
    ByVal pbRecvBuffer As LongPtr, _
    ByRef pcbRecvLength As Long) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

SCardTransmit = ctypes.windll.winscard.SCardTransmit
SCardTransmit.restype = ctypes.c_int
SCardTransmit.argtypes = [
    ctypes.c_size_t,  # hCard : UINT_PTR
    ctypes.c_void_p,  # pioSendPci : SCARD_IO_REQUEST*
    ctypes.POINTER(ctypes.c_ubyte),  # pbSendBuffer : BYTE*
    wintypes.DWORD,  # cbSendLength : DWORD
    ctypes.c_void_p,  # pioRecvPci : SCARD_IO_REQUEST* optional, in/out
    ctypes.POINTER(ctypes.c_ubyte),  # pbRecvBuffer : BYTE* out
    ctypes.POINTER(wintypes.DWORD),  # pcbRecvLength : DWORD* in/out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('WinSCard.dll')
SCardTransmit = Fiddle::Function.new(
  lib['SCardTransmit'],
  [
    Fiddle::TYPE_UINTPTR_T,  # hCard : UINT_PTR
    Fiddle::TYPE_VOIDP,  # pioSendPci : SCARD_IO_REQUEST*
    Fiddle::TYPE_VOIDP,  # pbSendBuffer : BYTE*
    -Fiddle::TYPE_INT,  # cbSendLength : DWORD
    Fiddle::TYPE_VOIDP,  # pioRecvPci : SCARD_IO_REQUEST* optional, in/out
    Fiddle::TYPE_VOIDP,  # pbRecvBuffer : BYTE* out
    Fiddle::TYPE_VOIDP,  # pcbRecvLength : DWORD* in/out
  ],
  Fiddle::TYPE_INT)

#[link(name = "winscard")]
extern "system" {
    fn SCardTransmit(
        hCard: usize,  // UINT_PTR
        pioSendPci: *mut SCARD_IO_REQUEST,  // SCARD_IO_REQUEST*
        pbSendBuffer: *mut u8,  // BYTE*
        cbSendLength: u32,  // DWORD
        pioRecvPci: *mut SCARD_IO_REQUEST,  // SCARD_IO_REQUEST* optional, in/out
        pbRecvBuffer: *mut u8,  // BYTE* out
        pcbRecvLength: *mut u32  // DWORD* in/out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("WinSCard.dll")]
public static extern int SCardTransmit(UIntPtr hCard, IntPtr pioSendPci, IntPtr pbSendBuffer, uint cbSendLength, IntPtr pioRecvPci, IntPtr pbRecvBuffer, ref uint pcbRecvLength);
"@
$api = Add-Type -MemberDefinition $sig -Name 'WinSCard_SCardTransmit' -Namespace Win32 -PassThru
# $api::SCardTransmit(hCard, pioSendPci, pbSendBuffer, cbSendLength, pioRecvPci, pbRecvBuffer, pcbRecvLength)

#uselib "WinSCard.dll"
#func global SCardTransmit "SCardTransmit" sptr, sptr, sptr, sptr, sptr, sptr, sptr
; SCardTransmit hCard, varptr(pioSendPci), varptr(pbSendBuffer), cbSendLength, varptr(pioRecvPci), varptr(pbRecvBuffer), varptr(pcbRecvLength)   ; 戻り値は stat
; hCard : UINT_PTR -> "sptr"
; pioSendPci : SCARD_IO_REQUEST* -> "sptr"
; pbSendBuffer : BYTE* -> "sptr"
; cbSendLength : DWORD -> "sptr"
; pioRecvPci : SCARD_IO_REQUEST* optional, in/out -> "sptr"
; pbRecvBuffer : BYTE* out -> "sptr"
; pcbRecvLength : DWORD* in/out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "WinSCard.dll"
#cfunc global SCardTransmit "SCardTransmit" sptr, var, var, int, var, var, var
; res = SCardTransmit(hCard, pioSendPci, pbSendBuffer, cbSendLength, pioRecvPci, pbRecvBuffer, pcbRecvLength)
; hCard : UINT_PTR -> "sptr"
; pioSendPci : SCARD_IO_REQUEST* -> "var"
; pbSendBuffer : BYTE* -> "var"
; cbSendLength : DWORD -> "int"
; pioRecvPci : SCARD_IO_REQUEST* optional, in/out -> "var"
; pbRecvBuffer : BYTE* out -> "var"
; pcbRecvLength : DWORD* in/out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "WinSCard.dll"
#cfunc global SCardTransmit "SCardTransmit" sptr, sptr, sptr, int, sptr, sptr, sptr
; res = SCardTransmit(hCard, varptr(pioSendPci), varptr(pbSendBuffer), cbSendLength, varptr(pioRecvPci), varptr(pbRecvBuffer), varptr(pcbRecvLength))
; hCard : UINT_PTR -> "sptr"
; pioSendPci : SCARD_IO_REQUEST* -> "sptr"
; pbSendBuffer : BYTE* -> "sptr"
; cbSendLength : DWORD -> "int"
; pioRecvPci : SCARD_IO_REQUEST* optional, in/out -> "sptr"
; pbRecvBuffer : BYTE* out -> "sptr"
; pcbRecvLength : DWORD* in/out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。