SMARTCARD_EXTENSION 구조체(smclib.h)

아티클
02/07/2025

SMARTCARD_EXTENSION 구조는 스마트 카드 판독기 드라이버와 스마트 카드 드라이버 라이브러리 모두에서 다른 모든 스마트 카드 데이터 구조에 액세스하는 데 사용됩니다.

통사론

typedef struct _SMARTCARD_EXTENSION {
  ULONG                     Version;
  VENDOR_ATTR               VendorAttr;
  NTSTATUS(                 *ReaderFunction[16];
  SCARD_CARD_CAPABILITIES   CardCapabilities;
  ULONG                     LastError;
  struct {
    PULONG Information;
    PUCHAR RequestBuffer;
    ULONG  RequestBufferLength;
    PUCHAR ReplyBuffer;
    ULONG  ReplyBufferLength;
  } IoRequest;
  ULONG                     MajorIoControlCode;
  ULONG                     MinorIoControlCode;
  POS_DEP_DATA              OsData;
  SCARD_READER_CAPABILITIES ReaderCapabilities;
  PREADER_EXTENSION         ReaderExtension;
  SMARTCARD_REPLY           SmartcardReply;
  SMARTCARD_REQUEST         SmartcardRequest;
  T0_DATA                   T0;
  T1_DATA                   T1;
  PPERF_INFO                PerfInfo;
  ULONG                     Reserved[25 - sizeof(PPERF_INFO)];
} *PSMARTCARD_EXTENSION, SMARTCARD_EXTENSION;

회원

Version

이 구조체의 버전을 나타냅니다.

VendorAttr

공급업체 이름, 단위 번호 및 일련 번호와 같은 판독기 드라이버를 식별하는 정보를 포함합니다.

ReaderFunction[16]

구문 블록의 줄은 NTSTATUS (*ReaderFunction[16])(PSMARTCARD_EXTENSION); 읽어야 합니다.

판독기용 콜백 함수 배열에 대한 포인터입니다. 공급업체에서 제공하는 판독기 드라이버가 구현할 수 있는 콜백 함수입니다. 판독기 드라이버는 SmartcardDeviceControl 스마트 카드 라이브러리 루틴에 이러한 콜백 함수를 사용할 수 있도록 하여 스마트 카드 디바이스 확장에 포인터를 저장하여 호출합니다.

RDF_ATR_PARSE

RDF_CARD_EJECT

RDF_CARD_POWER

RDF_CARD_TRACKING

RDF_IOCTL_VENDOR

RDF_READER_SWALLOW

RDF_SET_PROTOCOL

RDF_TRANSMIT

자세한 내용은 비고를 참조하세요.

CardCapabilities

삽입된 스마트 카드의 기능을 포함합니다.

LastError

사용되지 않습니다.

IoRequest

다음 멤버가 있는 구조체:

IoRequest.Information

반환된 바이트 수를 포함합니다.

IoRequest.RequestBuffer

카드로 보낼 사용자의 I/O 요청에 있는 데이터에 대한 포인터입니다.

IoRequest.RequestBufferLength

카드로 보낼 바이트 수를 나타냅니다.

IoRequest.ReplyBuffer

I/O 요청에 의해 반환되는 데이터를 보유하는 버퍼에 대한 포인터입니다.

IoRequest.ReplyBufferLength

I/O 요청에 의해 반환되는 데이터의 바이트 수를 나타냅니다.

MajorIoControlCode

주요 I/O 컨트롤 코드를 포함합니다.

MinorIoControlCode

부 I/O 컨트롤 코드를 포함합니다.

OsData

운영 체제 및 드라이버 유형과 관련된 정보를 포함합니다.

ReaderCapabilities

키보드 판독기의 기능을 포함합니다.

ReaderExtension

스마트 카드 판독기 관련 데이터를 포함합니다.

SmartcardReply

판독기에서 가져온 데이터를 포함합니다.

SmartcardRequest

현재 명령과 스마트 카드로 전송되는 데이터를 포함합니다.

T0

T=0 프로토콜에 사용할 데이터를 포함합니다.

T1

T=1 프로토콜과 함께 사용되는 데이터를 포함합니다.

PerfInfo

Reserved[25 - sizeof(PPERF_INFO)]

시스템 사용을 위해 예약되어 있습니다.

발언

이 구조체는 모든 콜백 함수에 전달됩니다.

개별 콜백 함수는 ReaderFunction 배열의 인덱스로 사용해야 하는 일련의 상수 값으로 식별됩니다.

색인 묘사

RDF_ATR_PARSE 선택적. RDF_ATR_PARSE 구문 분석 함수는 드라이버 라이브러리가 스마트 카드 드라이버 라이브러리를 인식하거나 구문 분석할 수 없는 경우 스마트 카드 드라이버 라이브러리에 대한 ATR(응답 재설정)을 구문 분석합니다.

RDF_CARD_EJECT

선택적. RDF_CARD_EJECT 콜백 함수

RDF_CARD_EJECT 콜백 함수는 판독기에서 삽입된 스마트 카드를 배출합니다.

RDF_CARD_POWER

RDF_CARD_POWER 콜백 함수는 삽입된 스마트 카드를 다시 설정하거나 해제합니다. 스마트 카드 판독기 드라이버에서 이 콜백 함수를 구현해야 합니다.

입력에서 SmartcardExtension 가리키는 구조체에는 다음 멤버 값이 있어야 합니다.

MajorIoControlCode

값이 IOCTL_SMARTCARD_POWER.

IoRequest.ReplyBufferLength

버퍼의 길이를 포함해야 합니다.

minorIoControlCode

다음 부 코드 중 하나가 있어야 합니다.

SCARD_COLD_RESET: 스마트 카드의 콜드 재설정을 수행합니다.
SCARD_WARM_RESET: 스마트 카드의 웜 재설정을 수행합니다.
SCARD_POWER_DOWN: 스마트 카드 전원을 끕니다.

출력에서 SmartcardExtension 가리키는 구조에는 다음 값이 있어야 합니다.

IoRequest.ReplyBuffer: 스마트 카드에서 반환되는 ATR을 받습니다. 또한 라이브러리가 ATR을 구문 분석할 수 있도록 atR을 SmartcardExtension->CardCapabilities.ATR.Buffer 전송해야 합니다.
IoRequest.Information: ATR의 길이를 받습니다.
CardCapabilities.ATR.Length: ATR의 길이를 포함합니다.

RDF_CARD_TRACKING

RDF_CARD_TRACKING 콜백 함수는 카드 판독기에서 카드를 삽입하거나 제거할 때마다 추적하는 이벤트 처리기를 설치합니다. 스마트 카드 판독기 드라이버에서 이 콜백 함수를 구현해야 합니다.

IOCTL_SMARTCARD_IS_PRESENT 요청을 받으면 드라이버 라이브러리는 스마트 카드가 이미 있는지 확인합니다. 스마트 카드가 있는 경우 드라이버 라이브러리는 STATUS_SUCCESS 상태로 요청을 완료합니다. 스마트 카드가 없는 경우 드라이버 라이브러리는 판독기 드라이버의 스마트 카드 추적 콜백 함수를 호출하고 판독기 드라이버는 스마트 카드를 검색하기 시작합니다. 스마트 카드 추적을 시작한 후 드라이버 라이브러리는 요청을 STATUS_PENDING 상태로 표시합니다.

드라이버 라이브러리가 요청을 완료합니다.

WDM 디바이스 드라이버

해당 WDM 드라이버 라이브러리는 SmartcardExtension->OsData->NotificationIrp요청에 포인터를 추가합니다. 판독기 드라이버는 스마트 카드가 삽입되거나 제거된 것을 감지하는 즉시 요청을 완료해야 합니다. 판독기 드라이버는 IoCompleteRequest호출하여 요청을 완료합니다. 그 후 판독기 드라이버는 SmartcardExtension의 NotificationIrp 멤버를 설정해야 합니다.> OsDataNULL 다시 설정하여 판독기 드라이버가 추가 스마트 카드 추적 요청을 수락할 수 있음을 드라이버 라이브러리에 알릴 수 있습니다.

이 호출은 무기한 기간을 가질 수 있으며 호출자가 완료되기 전에 요청을 종료할 수 있으므로 이 IRP를 취소 가능으로 표시하는 것이 중요합니다.

MyDriverCardSupervision(
SmartcardExtension, 
OtherParameters)
//
//    This function is called whenever the card status changes
//    For example, the card has been inserted or the card has been removed
//
{
    if (SmartcardExtension->OsData->NotificationOverlappedData != NULL){

        SmartcardCompleteCardTracking(SmartcardExtension);
    }
    //
    // Do additional tasks
    //
}

RDF_IOCTL_VENDOR

RDF_IOCTL_VENDOR 콜백 함수는 공급업체별 IOCTL 작업을 수행합니다. 스마트 카드 판독기 드라이버에서 이 콜백 함수를 구현하는 것은 선택 사항입니다.

입력에서 호출자는 함수에 다음 값을 전달해야 합니다.

SmartcardExtension->MajorIoControlCode: 공급업체별 IOCTL 코드를 포함합니다. 공급업체별 IOCTL 코드를 정의하는 방법에 대한 자세한 내용은 Winsmcrd.h 매크로 SCARD_CTL_CODE 참조하세요. 코드는 2048년에서 4095년 사이여야 합니다.
SmartcardExtension->IoRequest.RequestBuffer: 사용자의 입력 버퍼에 대한 포인터입니다.
SmartcardExtension->IoRequest.RequestBufferLength: 사용자 입력 버퍼의 크기(바이트)입니다.
SmartcardExtension->IoRequest.ReplyBuffer: 사용자의 출력 버퍼에 대한 포인터입니다.
SmartcardExtension->IoRequest.ReplyBufferLength: 사용자 출력 버퍼의 크기(바이트)입니다.
SmartcardExtension->IoRequest.Information: 요청에서 제공하는 값입니다. 반환된 바이트 수로 설정해야 합니다.

다른 모든 IOCTL과 마찬가지로 사용자 모드 애플리케이션은 DeviceIoControl 함수를 호출하여 공급업체에서 정의한 IOCTL을 스마트 카드 판독기 디바이스로 디스패치합니다. 그러나 IOCTL이 공급업체에 정의된 경우 애플리케이션은 먼저 "겹침"(즉, 비동기) 액세스를 위해 판독기 디바이스를 열어야 합니다. 또한 애플리케이션은 OVERLAPPED 구조를 정의하고 DeviceIoControl 마지막 인수에서 시스템에 전달해야 합니다(OVERLAPPED 구조는 Windows SDK 설명서에도 설명되어 있습니다.). 운영 체제가 드라이버의 I/O 컨트롤 디스패치 루틴을 호출하면 DIOCPARAMETERS 구조체를 드라이버에 전달합니다. DIOCPARAMETERS 구조체의 lpoOverlapped 멤버에는 OVERLAPPED 구조체에 대한 포인터가 포함되어 있습니다.

RDF_READER_SWALLOW RDF_READER_SWALLOW 콜백 함수는 스마트 카드 판독기에 스마트 카드를 완전히 삽입할 때 발생하는 기계적 제비 기능을 수행합니다. 스마트 카드 판독기 드라이버에서 이 콜백 함수를 구현하는 것은 선택 사항입니다.

RDF_SET_PROTOCOL

RDF_SET_PROTOCOL 콜백 함수는 삽입된 스마트 카드에 대한 전송 프로토콜을 선택합니다. 스마트 카드 판독기 드라이버는 이 콜백 함수를 구현해야 합니다.

입력에서 호출자는 함수에 다음 값을 전달해야 합니다.

SmartcardExtension->MajorIoControlCode

IOCTL_SMARTCARD_SET_PROTOCOL포함합니다.

SmartcardExtension->MinorIoControlCode

호출자가 허용하는 것보다 하나 이상의 프로토콜의 비트 OR을 포함합니다. 드라이버는 삽입된 스마트 카드에서 지원하는 프로토콜을 선택해야 합니다. T = 1 프로토콜이 T = 0 프로토콜보다 우선적으로 적용되는 것이 좋습니다.

값	의미
SCARD_PROTOCOL_RAW	원시 프로토콜을 선택합니다.
SCARD_PROTOCOL_T0	ISO T = 0 프로토콜을 선택합니다.
SCARD_PROTOCOL_T1	ISO T = 1 프로토콜을 선택합니다.

SmartcardExtension->IoRequest.ReplyBufferLength

회신 버퍼의 길이를 포함합니다.

SmartcardExtension->CardCapabilities.PtsData

PTS 요청을 수행하는 데 필요한 매개 변수를 포함합니다. 자세한 내용은 PTS_DATA참조하세요.

요청은 다음 값을 반환합니다.

SmartcardExtension->IoRequest.ReplyBuffer: 선택한 프로토콜을 포함합니다.
SmartcardExtension->IoRequest.Information: ULONG(sizeof)으로 설정합니다.

호출자는 허용되는 프로토콜의 마스크를 제공할 수 있습니다. 드라이버의 설정된 프로토콜 콜백 루틴은 마스크의 프로토콜 중 하나를 선택하고 SmartcardExtension->IoRequest.ReplyBuffer선택한 프로토콜을 반환합니다.

RDF_TRANSMIT

RDF_TRANSMIT 콜백 함수는 데이터 전송을 수행합니다. 스마트 카드 판독기 드라이버는 이 콜백 함수를 구현해야 합니다.

입력에서 호출자는 함수에 다음 값을 전달해야 합니다.

SmartcardExtension->MajorIoControlCode: IOCTL_SMARTCARD_TRANSMIT포함합니다.
SmartcardExtension->IoRequest.RequestBuffer: SCARD_IO_REQUEST 구조체에 대한 포인터와 카드로 전송할 데이터가 뒤따릅니다.
SmartcardExtension->IoRequest.RequestBufferLength: 카드로 전송할 바이트 수입니다.
SmartcardExtension->IoRequest.ReplyBufferLength: 회신 버퍼의 크기(바이트)입니다.

요청은 다음 값을 반환합니다.

SmartcardExtension->IoRequest.ReplyBuffer: SCARD_IO_REQUEST 구조를 수신하는 버퍼에 대한 포인터와 카드의 결과입니다.
SmartcardExtension->IoRequest.Information: 스마트 카드에서 반환된 실제 바이트 수와 SCARD_IO_REQUEST 구조체의 크기를 받습니다. SCARD_IO_REQUEST 구조체에 대한 정의는 IOCTL_SMARTCARD_TRANSMIT 참조하세요.

이 함수가 호출되면 smartcardExtension->IoRequest.RequestBuffer SCARD_IO_REQUEST 구조와 전송할 데이터를 가리킵니다.

typedef struct _SCARD_IO_REQUEST{
  DWORD  dwProtocol;   // Protocol identifier
  DWORD  cbPciLength;  // Protocol Control Information Length
} SCARD_IO_REQUEST, *PSCARD_IO_REQUEST, *LPSCARD_IO_REQUEST;

dwProtocol 멤버는 IOCTL_SMARTCARD_SET_PROTOCOL 호출에 의해 반환되는 프로토콜 식별자를 포함해야 합니다.

cbPciLength 멤버는 SCARD_IO_REQUEST 구조체의 크기(바이트)를 포함합니다. 이 구조체의 크기는 일반적으로 8바이트입니다.

SCARD_IO_REQUEST 구조 뒤에 카드로 전송할 (프로토콜) 데이터가 잇습니다. 전송에 사용할 프로토콜에 따라 라이브러리는 몇 가지 지원 기능을 제공합니다. 이러한 지원 함수에 대한 자세한 내용은 WDM(SmartcardT0Request) 및 WDM(SmartcardT1Request)을 참조하세요.

RequestBuffer 및 ReplyBuffer는 동일한 시스템 버퍼를 가리킬 있습니다. SmartcardxxRequest 라이브러리 함수를 사용하고 SmartcardxxReply 경우 입력 버퍼를 덮어쓰지 않습니다. 이러한 함수를 사용하지 않는 경우 전송을 시작하기 전에 RequestBuffer 복사본을 만듭니다.

SCARD_IO_REQUEST 구조를 ReplyBuffer 매개 변수에 복사한 다음 카드에서 받은 데이터를 복사해야 합니다. 다시 SmartcardxxRequest 사용하고 SmartcardxxReply 함수를 경우 라이브러리에서 구조를 복사합니다.

요구 사항

요구	값
헤더	smclib.h(Smclib.h 포함)

다음을 통해 공유

SMARTCARD_EXTENSION 구조체(smclib.h)

통사론

회원

발언

요구 사항

피드백

추가 리소스