Condividi tramite

struttura SMARTCARD_EXTENSION (smclib.h)

  • Articolo

La struttura SMARTCARD_EXTENSION viene usata sia dal driver del lettore di smart card che dalla libreria di driver smart card per accedere a tutte le altre strutture di dati di smart card.

Sintassi

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;

Membri

Version

Indica la versione di questa struttura.

VendorAttr

Contiene informazioni che identificano il driver del lettore, ad esempio il nome del fornitore, il numero di unità e il numero di serie.

ReaderFunction[16]

La riga nel blocco di sintassi deve leggere NTSTATUS (*ReaderFunction[16])(PSMARTCARD_EXTENSION);

Puntatore a una matrice di funzioni di callback per i lettori. Le funzioni di callback che un driver lettore fornito dal fornitore può implementare. Un driver lettore rende disponibili queste funzioni di callback per la routine della libreria di smart card, SmartcardDeviceControl, per chiamare archiviando i puntatori nelle estensioni del dispositivo smart card.

RDF_ATR_PARSE
RDF_CARD_EJECT
RDF_CARD_POWER
RDF_CARD_TRACKING
RDF_IOCTL_VENDOR
RDF_READER_SWALLOW
RDF_SET_PROTOCOL
RDF_TRANSMIT
Per altre informazioni, vedere Osservazioni.

CardCapabilities

Contiene le funzionalità della smart card inserita.

LastError

Non utilizzato.

IoRequest

Struttura con i membri seguenti:

IoRequest.Information

Contiene il numero di byte restituiti.

IoRequest.RequestBuffer

Puntatore ai dati nella richiesta di I/O dell'utente da inviare alla scheda.

IoRequest.RequestBufferLength

Indica il numero di byte da inviare alla scheda.

IoRequest.ReplyBuffer

Puntatore al buffer che contiene i dati restituiti dalla richiesta di I/O.

IoRequest.ReplyBufferLength

Indica il numero di byte dei dati restituiti dalla richiesta di I/O.

MajorIoControlCode

Contiene il codice di controllo di I/O principale.

MinorIoControlCode

Contiene il codice di controllo di I/O secondario.

OsData

Contiene informazioni specifiche per il sistema operativo e il tipo di driver.

ReaderCapabilities

Contiene le funzionalità del lettore di tastiera.

ReaderExtension

Contiene dati specifici del lettore di smart card.

SmartcardReply

Contiene dati provenienti dal lettore.

SmartcardRequest

Contiene il comando corrente e i dati inviati alla smart card.

T0

Contiene i dati da usare con il protocollo T=0.

T1

Contiene i dati usati con il protocollo T=1.

PerfInfo

Reserved[25 - sizeof(PPERF_INFO)]

Riservato per l'uso del sistema.

Osservazioni

Questa struttura viene passata a tutte le funzioni di callback.

Le singole funzioni di callback sono identificate da una serie di valori costanti che devono essere usati come indici nella matrice ReaderFunction.

Indice Descrizione
RDF_ATR_PARSE Opzionale. La funzione di analisi di RDF_ATR_PARSE analizza una risposta a reimpostazione (ATR) per la libreria di driver di smart card quando la libreria di driver non è in grado di riconoscere o analizzare la libreria di driver di smart card.
RDF_CARD_EJECT Opzionale. RDF_CARD_EJECT funzione di callback

La funzione di callback RDF_CARD_EJECT espelle una smart card inserita dal lettore.
RDF_CARD_POWER La funzione di callback RDF_CARD_POWER reimposta o disattiva una smart card inserita. È obbligatorio che i driver del lettore di smart card implementino questa funzione di callback.

In caso di input, la struttura a cui punta SmartcardExtension deve avere i valori membro seguenti:

MajorIoControlCode
Deve avere un valore di IOCTL_SMARTCARD_POWER.
IoRequest.ReplyBufferLength
Deve contenere la lunghezza del buffer.
MinorIoControlCode
Deve avere uno dei codici secondari seguenti:
SCARD_COLD_RESET
Esegue un ripristino a freddo della smart card.
SCARD_WARM_RESET
Esegue una reimpostazione ad accesso frequente della smart card.
SCARD_POWER_DOWN
Disattiva l'alimentazione della smart card.
Nell'output, la struttura a cui punta SmartcardExtension deve avere i valori seguenti:
IoRequest.ReplyBuffer
Riceve l'ATR restituito dalla smart card. Inoltre, è necessario trasferire ATR a SmartcardExtension->CardCapabilities.ATR.Buffer in modo che la libreria possa analizzare ATR.
IoRequest.Information
Riceve la lunghezza di ATR.
CardCapabilities.ATR.Length
Contiene la lunghezza di ATR.
RDF_CARD_TRACKING La funzione di callback RDF_CARD_TRACKING installa un gestore eventi per tenere traccia ogni volta che una scheda viene inserita o rimossa da un lettore di schede. È obbligatorio che i driver del lettore di smart card implementino questa funzione di callback.

Quando si riceve una richiesta di IOCTL_SMARTCARD_IS_PRESENT, la libreria driver determina se la smart card è già presente. Se la smart card è presente, la libreria driver completa la richiesta con lo stato STATUS_SUCCESS. Se non è presente alcuna smart card, la libreria driver chiama la funzione di callback di rilevamento smart card del driver lettore e il driver lettore inizia a cercare la smart card. Dopo l'avvio del rilevamento delle smart card, la libreria driver contrassegna la richiesta come stato di STATUS_PENDING.

La libreria driver completa la richiesta.

driver di dispositivo WDM

La libreria di driver WDM corrispondente aggiunge un puntatore alla richiesta in SmartcardExtension->OsData->NotificationIrp. Il driver del lettore deve completare la richiesta non appena rileva che una smart card è stata inserita o rimossa. Il driver lettore completa la richiesta chiamando IoCompleteRequest, dopo di che, il driver lettore deve impostare il NotificationIrp membro di SmartcardExtension -> OsData a NULL per informare la libreria driver che il driver lettore può accettare ulteriori richieste di rilevamento delle smart card.

Poiché questa chiamata può avere una durata illimitata e il chiamante può terminare la richiesta prima del completamento, è importante contrassegnare questo IRP come annullabile.

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 La funzione di callback RDF_IOCTL_VENDOR esegue operazioni IOCTL specifiche del fornitore. È facoltativo per i driver del lettore di smart card implementare questa funzione di callback.

All'input, il chiamante deve passare i valori seguenti alla funzione:

SmartcardExtension->MajorIoControlCode
Contiene un codice IOCTL specifico del fornitore. Per informazioni su come definire un codice IOCTL specifico del fornitore, vedere la macro SCARD_CTL_CODE in Winsmcrd.h. Si noti che il codice deve essere compreso tra 2048 e 4095.
SmartcardExtension->IoRequest.RequestBuffer
Puntatore al buffer di input dell'utente.
SmartcardExtension->IoRequest.RequestBufferLength
Dimensioni, in byte, del buffer di input dell'utente.
SmartcardExtension->IoRequest.ReplyBuffer
Puntatore al buffer di output dell'utente.
SmartcardExtension->IoRequest.ReplyBufferLength
Dimensioni, in byte, del buffer di output dell'utente.
SmartcardExtension->IoRequest.Information
Valore fornito dalla richiesta. Deve essere impostato sul numero di byte restituiti.
Come per tutti gli altri IOCTL, un'applicazione in modalità utente invia un IOCTL definito dal fornitore a un dispositivo lettore di smart card chiamando la funzione DeviceIoControl. Quando l'IOCTL è definito dal fornitore, tuttavia, l'applicazione deve prima aprire il dispositivo lettore per l'accesso "sovrapposto", ovvero asincrono. L'applicazione deve anche definire una struttura OVERLAPPED e passarla al sistema nell'ultimo argomento di DeviceIoControl (la struttura OVERLAPPED è descritta anche nella documentazione di Windows SDK). Quando il sistema operativo chiama la routine di invio del controllo I/O del driver, passa una struttura DIOCPARAMETERS al driver. Il membro lpoOverlapped della struttura DIOCPARAMETERS contiene un puntatore alla struttura OVERLAPPED.
RDF_READER_SWALLOW La funzione di callback RDF_READER_SWALLOW esegue una rondine meccanica, che si verifica quando la smart card viene inserita completamente nel lettore di smart card. È facoltativo per i driver del lettore di smart card implementare questa funzione di callback.
RDF_SET_PROTOCOL La funzione di callback RDF_SET_PROTOCOL seleziona un protocollo di trasmissione per la smart card inserita. I driver del lettore di smart card devono implementare questa funzione di callback.

All'input, il chiamante deve passare i valori seguenti alla funzione:

SmartcardExtension->MajorIoControlCode
Contiene IOCTL_SMARTCARD_SET_PROTOCOL.
SmartcardExtension->MinorIoControlCode
Contiene un OR bit per bit di uno o più protocolli accettati dal chiamante. Il driver deve selezionare un protocollo supportato dalla smart card inserita. È consigliabile che il protocollo T = 1 sia preceduto dal protocollo T = 0.
Valore Significato
SCARD_PROTOCOL_RAW Seleziona il protocollo non elaborato.
SCARD_PROTOCOL_T0 Seleziona il protocollo ISO T = 0.
SCARD_PROTOCOL_T1 Seleziona il protocollo ISO T = 1.
 
SmartcardExtension->IoRequest.ReplyBufferLength
Contiene la lunghezza del buffer di risposta.
SmartcardExtension->CardCapabilities.PtsData
Contiene i parametri necessari per eseguire la richiesta PTS. Per altre informazioni, vedere PTS_DATA.
La richiesta restituisce i valori seguenti:
SmartcardExtension->IoRequest.ReplyBuffer
Contiene il protocollo selezionato.
SmartcardExtension->IoRequest.Information
Impostare su sizeof(ULONG).
Il chiamante può fornire una maschera di protocolli accettabili. La routine di callback del protocollo impostato del driver seleziona uno dei protocolli nella maschera e restituisce il protocollo selezionato in SmartcardExtension->IoRequest.ReplyBuffer.
RDF_TRANSMIT La funzione di callback RDF_TRANSMIT esegue trasmissioni di dati. I driver del lettore di smart card devono implementare questa funzione di callback.

All'input, il chiamante deve passare i valori seguenti alla funzione:

SmartcardExtension->MajorIoControlCode
Contiene IOCTL_SMARTCARD_TRANSMIT.
SmartcardExtension->IoRequest.RequestBuffer
Puntatore a una struttura SCARD_IO_REQUEST seguita dai dati da trasmettere alla scheda.
SmartcardExtension->IoRequest.RequestBufferLength
Numero di byte da trasmettere alla scheda.
SmartcardExtension->IoRequest.ReplyBufferLength
Dimensione, in byte, del buffer di risposta.
La richiesta restituisce i valori seguenti:
SmartcardExtension->IoRequest.ReplyBuffer
Puntatore al buffer che riceve la struttura SCARD_IO_REQUEST, più il risultato della scheda.
SmartcardExtension->IoRequest.Information
Riceve il numero effettivo di byte restituiti dalla smart card, oltre alle dimensioni della struttura SCARD_IO_REQUEST. Per una definizione della struttura SCARD_IO_REQUEST, vedere IOCTL_SMARTCARD_TRANSMIT.
Quando questa funzione viene chiamata, SmartcardExtension->IoRequest.RequestBuffer punta a una struttura SCARD_IO_REQUEST seguita dai dati da trasmettere. 
typedef struct _SCARD_IO_REQUEST{
  DWORD  dwProtocol;   // Protocol identifier
  DWORD  cbPciLength;  // Protocol Control Information Length
} SCARD_IO_REQUEST, *PSCARD_IO_REQUEST, *LPSCARD_IO_REQUEST;

Il membro dwProtocol deve contenere l'identificatore del protocollo restituito da una chiamata a IOCTL_SMARTCARD_SET_PROTOCOL.

Il membro cbPciLength contiene le dimensioni, in byte, della struttura SCARD_IO_REQUEST. Le dimensioni di questa struttura sono in genere di 8 byte.

La struttura SCARD_IO_REQUEST è seguita da dati (protocollo) da trasmettere alla scheda. A seconda del protocollo da usare per la trasmissione, la libreria offre diverse funzioni di supporto. Per altre informazioni su queste funzioni di supporto, vedere SmartcardT0Request (WDM) e SmartcardT1Request (WDM).

RequestBuffer e ReplyBuffer puntano allo stesso buffer di sistema. Se si usa la funzione di libreria smartcardxxRequest e SmartcardxxReply, non si sovrascriverà il buffer di input. Se non si usano queste funzioni, creare una copia del RequestBuffer prima di avviare le trasmissioni.

È necessario copiare la struttura SCARD_IO_REQUEST nel parametro ReplyBuffer, seguito dai dati ricevuti dalla scheda. Anche in questo caso, se si utilizza la SmartcardxxRequest e funzioni SmartcardxxReply, la libreria copierà la struttura.

Fabbisogno

Requisito Valore
intestazione smclib.h (include Smclib.h)