Compartilhar via

estrutura SMARTCARD_EXTENSION (smclib.h)

  • Artigo

A estrutura SMARTCARD_EXTENSION é usada pelo driver de leitor de cartão inteligente e pela biblioteca de driver de cartão inteligente para acessar todas as outras estruturas de dados de cartão inteligentes.

Sintaxe

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;

Membros

Version

Indica a versão dessa estrutura.

VendorAttr

Contém informações que identificam o driver de leitor, como o nome do fornecedor, o número de unidade e o número de série.

ReaderFunction[16]

A linha no bloco de sintaxe deve ser lida NTSTATUS (*ReaderFunction[16])(PSMARTCARD_EXTENSION);

Um ponteiro para uma matriz de funções de retorno de chamada para leitores. As funções de retorno de chamada que um driver de leitor fornecido pelo fornecedor pode implementar. Um driver de leitor disponibiliza essas funções de retorno de chamada para a rotina de biblioteca de cartão inteligente, SmartcardDeviceControl, para chamar armazenando ponteiros para elas na extensão de dispositivo de cartão inteligente.

RDF_ATR_PARSE
RDF_CARD_EJECT
RDF_CARD_POWER
RDF_CARD_TRACKING
RDF_IOCTL_VENDOR
RDF_READER_SWALLOW
RDF_SET_PROTOCOL
RDF_TRANSMIT
Para obter mais informações, consulte Comentários.

CardCapabilities

Contém recursos da cartão inteligente inserida.

LastError

Não usado.

IoRequest

Uma estrutura com os seguintes membros:

IoRequest.Information

Contém o número de bytes retornados.

IoRequest.RequestBuffer

Um ponteiro para os dados na solicitação de E/S do usuário a serem enviados para o cartão.

IoRequest.RequestBufferLength

Indica o número de bytes a serem enviados para o cartão.

IoRequest.ReplyBuffer

Um ponteiro para o buffer que contém os dados retornados pela solicitação de E/S.

IoRequest.ReplyBufferLength

Indica o número de bytes dos dados retornados pela solicitação de E/S.

MajorIoControlCode

Contém o código de controle de E/S principal.

MinorIoControlCode

Contém o código de controle de E/S secundário.

OsData

Contém informações específicas do sistema operacional e do tipo de driver.

ReaderCapabilities

Contém os recursos do leitor de teclado.

ReaderExtension

Contém dados específicos do leitor de cartão inteligente.

SmartcardReply

Contém dados provenientes do leitor.

SmartcardRequest

Contém o comando atual e os dados enviados para a cartão inteligente.

T0

Contém os dados para uso com o protocolo T=0.

T1

Contém os dados usados com o protocolo T=1.

PerfInfo

Reserved[25 - sizeof(PPERF_INFO)]

Reservado para uso do sistema.

Comentários

Essa estrutura é passada para todas as funções de retorno de chamada.

As funções de retorno de chamada individuais são identificadas por uma série de valores constantes que devem ser usados como índices na matriz ReaderFunction .

Índice Descrição
RDF_ATR_PARSE Opcional. A função RDF_ATR_PARSE analisa uma ATR (resposta para redefinição) para a biblioteca de driver de cartão inteligente quando a biblioteca de driver não consegue reconhecer ou analisar a biblioteca de driver de cartão inteligente.
RDF_CARD_EJECT Opcional. função de retorno de chamada RDF_CARD_EJECT

A função de retorno de chamada RDF_CARD_EJECT ejeta uma cartão inteligente inserida do leitor.
RDF_CARD_POWER A função de retorno de chamada RDF_CARD_POWER redefine ou desativa uma cartão inteligente inserida. É obrigatório que drivers de leitor de cartão inteligentes implementem essa função de retorno de chamada.

Na entrada, a estrutura apontada por SmartcardExtension deve ter os seguintes valores de membro:

MajorIoControlCode
Deve ter um valor de IOCTL_SMARTCARD_POWER.
IoRequest.ReplyBufferLength
Deve conter o comprimento do buffer.
MinorIoControlCode
Deve ter um dos seguintes códigos secundários:
SCARD_COLD_RESET
Executa uma redefinição a frio do cartão inteligente.
SCARD_WARM_RESET
Executa uma redefinição quente do cartão inteligente.
SCARD_POWER_DOWN
Desativa a energia de cartão inteligente.
Na saída, a estrutura apontada por SmartcardExtension deve ter os seguintes valores:
IoRequest.ReplyBuffer
Recebe o ATR retornado pela cartão inteligente. Além disso, você deve transferir o ATR para SmartcardExtension->CardCapabilities.ATR.Buffer para que a biblioteca possa analisar o ATR.
IoRequest.Information
Recebe o comprimento do ATR.
CardCapabilities.ATR.Length
Contém o comprimento do ATR.
RDF_CARD_TRACKING A função de retorno de chamada RDF_CARD_TRACKING instala um manipulador de eventos para acompanhar sempre que uma cartão é inserida ou removida de um leitor de cartão. É obrigatório que drivers de leitor de cartão inteligentes implementem essa função de retorno de chamada.

Ao receber uma solicitação de IOCTL_SMARTCARD_IS_PRESENT, a biblioteca de driver determina se a cartão inteligente já está presente. Se a cartão inteligente estiver presente, a biblioteca de driver concluirá a solicitação com uma status de STATUS_SUCCESS. Se não houver nenhum cartão inteligente presente, a biblioteca de driver chamará a função de retorno de chamada de rastreamento de cartão inteligente do driver de leitor e o driver de leitor começará a procurar a cartão inteligente. Depois de iniciar o rastreamento de cartão inteligente, a biblioteca de driver marca a solicitação como tendo uma status de STATUS_PENDING.

A biblioteca de driver conclui a solicitação.

Drivers de dispositivo WDM

A biblioteca de driver WDM correspondente adiciona um ponteiro à solicitação em SmartcardExtension-OsData-NotificationIrp>>. O driver de leitor deve concluir a solicitação assim que detectar que uma cartão inteligente foi inserida ou removida. O driver de leitor conclui a solicitação chamando IoCompleteRequest, depois disso, o driver de leitor deve definir o membro NotificationIrp de SmartcardExtension –> OsData de volta para NULL para informar à biblioteca de driver que o driver de leitor pode aceitar mais solicitações de rastreamento de cartão inteligentes.

Como essa chamada pode ter uma duração indefinida e o chamador pode encerrar a solicitação antes de ser concluída, é importante marcar esse IRP como cancelável.

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 A função de retorno de chamada RDF_IOCTL_VENDOR executa operações IOCTL específicas do fornecedor. É opcional que drivers de leitor de cartão inteligentes implementem essa função de retorno de chamada.

Na entrada, o chamador deve passar os seguintes valores para a função:

SmartcardExtension->MajorIoControlCode
Contém um código IOCTL específico do fornecedor. Consulte a macro SCARD_CTL_CODE em Winsmcrd.h para obter informações sobre como definir um código IOCTL específico do fornecedor. Observe que o código deve estar entre 2048 e 4095.
SmartcardExtension->IoRequest.RequestBuffer
Um ponteiro para o buffer de entrada do usuário.
SmartcardExtension->IoRequest.RequestBufferLength
O tamanho, em bytes, do buffer de entrada do usuário.
SmartcardExtension->IoRequest.ReplyBuffer
Um ponteiro para o buffer de saída do usuário.
SmartcardExtension->IoRequest.ReplyBufferLength
O tamanho, em bytes, do buffer de saída do usuário.
SmartcardExtension->IoRequest.Information
O valor fornecido pela solicitação. Deve ser definido como o número de bytes retornados.
Assim como acontece com todas as outras IOCTLs, um aplicativo de modo de usuário envia um IOCTL definido pelo fornecedor para um dispositivo de leitor de cartão inteligente chamando a função DeviceIoControl. No entanto, quando o IOCTL é definido pelo fornecedor, o aplicativo deve primeiro abrir o dispositivo leitor para acesso "sobreposto" (ou seja, assíncrono). O aplicativo também deve definir uma estrutura OVERLAPPED e passá-la para o sistema no último argumento de DeviceIoControl (a estrutura OVERLAPPED também é descrita na documentação do SDK do Windows.). Quando o sistema operacional chama a rotina de expedição de controle de E/S do driver, ele passa uma estrutura DIOCPARAMETERS para o driver. O membro lpoOverlapped da estrutura DIOCPARAMETERS contém um ponteiro para a estrutura OVERLAPPED.
RDF_READER_SWALLOW A função de retorno de chamada RDF_READER_SWALLOW executa uma andorinha mecânica, que é o que acontece quando o cartão inteligente é totalmente inserido no leitor de cartão inteligente. É opcional que drivers de leitor de cartão inteligentes implementem essa função de retorno de chamada.
RDF_SET_PROTOCOL A função de retorno de chamada RDF_SET_PROTOCOL seleciona um protocolo de transmissão para o cartão inteligente inserido. Os drivers de leitor de cartão inteligente devem implementar essa função de retorno de chamada.

Na entrada, o chamador deve passar os seguintes valores para a função:

SmartcardExtension->MajorIoControlCode
Contém IOCTL_SMARTCARD_SET_PROTOCOL.
SmartcardExtension->MinorIoControlCode
Contém um OR bit a bit de um ou mais protocolos do que o chamador aceita. O driver deve selecionar um protocolo ao qual o cartão inteligente inserido dá suporte. Recomendamos que o protocolo T = 1 tenha precedência sobre o protocolo T = 0.
Valor Significado
SCARD_PROTOCOL_RAW Seleciona o protocolo bruto.
SCARD_PROTOCOL_T0 Seleciona o protocolo ISO T = 0.
SCARD_PROTOCOL_T1 Seleciona o protocolo ISO T = 1.
 
SmartcardExtension->IoRequest.ReplyBufferLength
Contém o comprimento do buffer de resposta.
SmartcardExtension->CardCapabilities.PtsData
Contém os parâmetros necessários para executar a solicitação PTS. Para obter mais informações, consulte PTS_DATA.
A solicitação retorna os seguintes valores:
SmartcardExtension->IoRequest.ReplyBuffer
Contém o protocolo selecionado.
SmartcardExtension->IoRequest.Information
Defina como sizeof(ULONG).
O chamador pode fornecer uma máscara de protocolos aceitáveis. A rotina de retorno de chamada de protocolo definido do driver seleciona um dos protocolos na máscara e retorna o protocolo selecionado em SmartcardExtension->IoRequest.ReplyBuffer.
RDF_TRANSMIT A função de retorno de chamada RDF_TRANSMIT executa transmissões de dados. Os drivers de leitor de cartão inteligente devem implementar essa função de retorno de chamada.

Na entrada, o chamador deve passar os seguintes valores para a função:

SmartcardExtension->MajorIoControlCode
Contém IOCTL_SMARTCARD_TRANSMIT.
SmartcardExtension->IoRequest.RequestBuffer
Um ponteiro para uma estrutura SCARD_IO_REQUEST seguida por dados a serem transmitidos para o cartão.
SmartcardExtension->IoRequest.RequestBufferLength
O número de bytes a serem transmitidos para o cartão.
SmartcardExtension->IoRequest.ReplyBufferLength
O tamanho, em bytes, do buffer de resposta.
A solicitação retorna os seguintes valores:
SmartcardExtension->IoRequest.ReplyBuffer
Um ponteiro para o buffer que recebe a estrutura SCARD_IO_REQUEST, além do resultado do cartão.
SmartcardExtension->IoRequest.Information
Recebe o número real de bytes retornados pelo cartão inteligente, além do tamanho da estrutura de SCARD_IO_REQUEST. Para obter uma definição da estrutura de SCARD_IO_REQUEST, consulte IOCTL_SMARTCARD_TRANSMIT.
Quando essa função é chamada, SmartcardExtension->IoRequest.RequestBuffer aponta para uma estrutura SCARD_IO_REQUEST seguida pelos dados a serem transmitidos. 
typedef struct _SCARD_IO_REQUEST{
  DWORD  dwProtocol;   // Protocol identifier
  DWORD  cbPciLength;  // Protocol Control Information Length
} SCARD_IO_REQUEST, *PSCARD_IO_REQUEST, *LPSCARD_IO_REQUEST;

O membro dwProtocol deve conter o identificador de protocolo retornado por uma chamada para IOCTL_SMARTCARD_SET_PROTOCOL.

O membro cbPciLength contém o tamanho, em bytes, da estrutura SCARD_IO_REQUEST. O tamanho dessa estrutura geralmente é de 8 bytes.

A estrutura SCARD_IO_REQUEST é seguida por dados (protocolo) a serem transmitidos para o cartão. Dependendo do protocolo a ser usado para a transmissão, a biblioteca oferece várias funções de suporte. Para obter mais informações sobre essas funções de suporte, consulte SmartcardT0Request (WDM) e SmartcardT1Request (WDM).

RequestBuffer e ReplyBuffer apontam para o mesmo buffer do sistema. Se você usar a função de biblioteca SmartcardxxRequest e SmartcardxxReply, não substituirá o buffer de entrada. Se você não usar essas funções, faça uma cópia do RequestBuffer antes de iniciar as transmissões.

Você deve copiar a estrutura SCARD_IO_REQUEST para o parâmetro ReplyBuffer, seguido pelos dados recebidos do cartão. Novamente, se você usar as funções SmartcardxxRequest e SmartcardxxReply , a biblioteca copiará a estrutura para você.

Requisitos

Requisito Valor
Cabeçalho smclib.h (inclua Smclib.h)