SMARTCARD_EXTENSION structure (smclib.h)

La structure SMARTCARD_EXTENSION est utilisée par le pilote de lecteur de carte intelligent et la bibliothèque de pilotes smart carte pour accéder à toutes les autres structures de données de carte intelligentes.

Syntaxe

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;

Membres

Version

Indique la version de cette structure.

VendorAttr

Contient des informations qui identifient le pilote de lecteur, telles que le nom du fournisseur, le numéro d’unité et le numéro de série.

ReaderFunction[16]

La ligne du bloc de syntaxe doit être lue NTSTATUS (*ReaderFunction[16])(PSMARTCARD_EXTENSION);

Pointeur vers un tableau de fonctions de rappel pour les lecteurs. Fonctions de rappel qu’un pilote de lecteur fourni par le fournisseur peut implémenter. Un pilote de lecteur rend ces fonctions de rappel disponibles pour la routine de bibliothèque smart carte, SmartcardDeviceControl, à appeler en stockant des pointeurs vers ces fonctions dans l’extension de périphérique smart carte.

RDF_ATR_PARSE

RDF_CARD_EJECT

RDF_CARD_POWER

RDF_CARD_TRACKING

RDF_IOCTL_VENDOR

RDF_READER_SWALLOW

RDF_SET_PROTOCOL

RDF_TRANSMIT

Pour plus d'informations, consultez la section Notes.

CardCapabilities

Contient les fonctionnalités du carte intelligent inséré.

LastError

Non utilisé.

IoRequest

Structure avec les membres suivants :

IoRequest.Information

Contient le nombre d’octets retournés.

IoRequest.RequestBuffer

Pointeur vers les données dans la demande d’E/S de l’utilisateur à envoyer au carte.

IoRequest.RequestBufferLength

Indique le nombre d’octets à envoyer à l’carte.

IoRequest.ReplyBuffer

Pointeur vers la mémoire tampon qui contient les données retournées par la demande d’E/S.

IoRequest.ReplyBufferLength

Indique le nombre d’octets des données retournées par la demande d’E/S.

MajorIoControlCode

Contient le code de contrôle d’E/S principal.

MinorIoControlCode

Contient le code de contrôle d’E/S secondaire.

OsData

Contient des informations spécifiques au système d’exploitation et au type de pilote.

ReaderCapabilities

Contient les fonctionnalités du lecteur clavier.

ReaderExtension

Contient des données spécifiques au lecteur smart carte.

SmartcardReply

Contient des données provenant du lecteur.

SmartcardRequest

Contient la commande active et les données envoyées au carte intelligent.

T0

Contient les données à utiliser avec le protocole T=0.

T1

Contient les données utilisées avec le protocole T=1.

PerfInfo

Reserved[25 - sizeof(PPERF_INFO)]

Réservé pour le système.

Remarques

Cette structure est passée à toutes les fonctions de rappel.

Les fonctions de rappel individuelles sont identifiées par une série de valeurs constantes qui doivent être utilisées comme index dans le tableau ReaderFunction .

Index	Description
RDF_ATR_PARSE	facultatif. La fonction d’analyse RDF_ATR_PARSE analyse une réponse à la réinitialisation (ATR) pour la bibliothèque de pilotes smart carte lorsque la bibliothèque de pilotes ne parvient pas à reconnaître ou à analyser la bibliothèque de pilotes smart carte.
RDF_CARD_EJECT	facultatif. RDF_CARD_EJECT fonction de rappel La fonction de rappel RDF_CARD_EJECT éjecte un carte intelligent inséré du lecteur.
RDF_CARD_POWER	La fonction de rappel RDF_CARD_POWER réinitialise ou désactive un carte intelligent inséré. Il est obligatoire pour les pilotes de lecteur smart carte d’implémenter cette fonction de rappel. Lors de l’entrée, la structure pointée par SmartcardExtension doit avoir les valeurs de membre suivantes : MajorIoControlCode Doit avoir la valeur IOCTL_SMARTCARD_POWER. IoRequest.ReplyBufferLength Doit contenir la longueur de la mémoire tampon. MinorIoControlCode Doit avoir l’un des codes mineurs suivants : SCARD_COLD_RESET Effectue une réinitialisation à froid de la carte intelligente. SCARD_WARM_RESET Effectue une réinitialisation à chaud de la carte intelligente. SCARD_POWER_DOWN Désactive l’alimentation carte intelligente. Lors de la sortie, la structure pointée par SmartcardExtension doit avoir les valeurs suivantes : IoRequest.ReplyBuffer Reçoit l’ATR retourné par le carte intelligent. En outre, vous devez transférer l’ATR vers SmartcardExtension->CardCapabilities.ATR.Buffer afin que la bibliothèque puisse analyser l’ATR. IoRequest.Information Reçoit la longueur de l’ATR. CardCapabilities.ATR.Length Contient la longueur de l’ATR.
RDF_CARD_TRACKING	La fonction de rappel RDF_CARD_TRACKING installe un gestionnaire d’événements pour effectuer le suivi chaque fois qu’un carte est inséré ou supprimé d’un lecteur carte. Il est obligatoire pour les pilotes de lecteur smart carte d’implémenter cette fonction de rappel. Lors de la réception d’une demande de IOCTL_SMARTCARD_IS_PRESENT, la bibliothèque de pilotes détermine si le carte intelligent est déjà présent. Si le carte intelligent est présent, la bibliothèque de pilotes termine la requête avec un status de STATUS_SUCCESS. Si aucune carte intelligente n’est présente, la bibliothèque de pilotes appelle la fonction de rappel de suivi intelligente carte du pilote lecteur, et le pilote de lecteur commence à rechercher le carte intelligent. Après avoir lancé le suivi carte intelligent, la bibliothèque de pilotes marque la requête comme ayant un status de STATUS_PENDING. La bibliothèque de pilotes termine la requête. Pilotes de périphérique WDM La bibliothèque de pilotes WDM correspondante ajoute un pointeur à la requête dans SmartcardExtension-OsData-NotificationIrp>>. Le pilote de lecteur doit terminer la demande dès qu’il détecte qu’un carte intelligent a été inséré ou supprimé. Le pilote de lecteur termine la demande en appelant IoCompleteRequest, après quoi, le pilote de lecteur doit définir le membre NotificationIrp de SmartcardExtension -> OsData sur NULL pour informer la bibliothèque de pilotes que le pilote de lecteur peut accepter d’autres demandes de suivi de carte intelligentes. Étant donné que cet appel peut avoir une durée indéfinie et que l’appelant peut terminer la demande avant qu’elle ne soit terminée, il est important de marquer ce IRP comme annulable. 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 fonction de rappel RDF_IOCTL_VENDOR effectue des opérations IOCTL spécifiques au fournisseur. Il est facultatif pour les pilotes de lecteur smart carte d’implémenter cette fonction de rappel. Lors de l’entrée, l’appelant doit passer les valeurs suivantes à la fonction : SmartcardExtension->MajorIoControlCode Contient un code IOCTL spécifique au fournisseur. Reportez-vous à la macro SCARD_CTL_CODE dans Winsmcrd.h pour plus d’informations sur la définition d’un code IOCTL spécifique au fournisseur. Notez que le code doit être compris entre 2048 et 4095. SmartcardExtension->IoRequest.RequestBuffer Pointeur vers la mémoire tampon d’entrée de l’utilisateur. SmartcardExtension->IoRequest.RequestBufferLength Taille, en octets, de la mémoire tampon d’entrée de l’utilisateur. SmartcardExtension->IoRequest.ReplyBuffer Pointeur vers la mémoire tampon de sortie de l’utilisateur. SmartcardExtension->IoRequest.ReplyBufferLength Taille, en octets, de la mémoire tampon de sortie de l’utilisateur. SmartcardExtension->IoRequest.Information Valeur fournie par la requête. Doit être défini sur le nombre d’octets retournés. Comme pour tous les autres IOCTL, une application en mode utilisateur distribue un IOCTL défini par le fournisseur à un lecteur de carte intelligent en appelant la fonction DeviceIoControl. Toutefois, lorsque l’IOCTL est défini par le fournisseur, l’application doit d’abord ouvrir l’appareil de lecture pour un accès « superposé » (c’est-à-dire asynchrone). L’application doit également définir une structure OVERLAPPED et la transmettre au système dans le dernier argument de DeviceIoControl (la structure OVERLAPPED est également décrite dans la documentation SDK Windows.). Lorsque le système d’exploitation appelle la routine de répartition des contrôles d’E/S du pilote, il transmet une structure DIOCPARAMETERS au pilote. Le membre lpoOverlapped de la structure DIOCPARAMETERS contient un pointeur vers la structure CHEVAUCHEMENT.
RDF_READER_SWALLOW	La fonction de rappel RDF_READER_SWALLOW effectue une hirondelle mécanique, ce qui se produit lorsque le carte intelligent est entièrement inséré dans le lecteur de carte intelligent. Il est facultatif pour les pilotes de lecteur smart carte d’implémenter cette fonction de rappel.
RDF_SET_PROTOCOL	La fonction de rappel RDF_SET_PROTOCOL sélectionne un protocole de transmission pour le carte intelligent inséré. Les pilotes de lecteur smart carte doivent implémenter cette fonction de rappel. Lors de l’entrée, l’appelant doit passer les valeurs suivantes à la fonction : SmartcardExtension->MajorIoControlCode Contient IOCTL_SMARTCARD_SET_PROTOCOL. SmartcardExtension->MinorIoControlCode Contient un or au niveau du bit d’un ou de plusieurs protocoles acceptés par l’appelant. Le pilote doit sélectionner un protocole que l’carte intelligente insérée prend en charge. Nous recommandons que le protocole T = 1 soit prioritaire sur le protocole T = 0. Valeur Signification SCARD_PROTOCOL_RAW Sélectionne le protocole brut. SCARD_PROTOCOL_T0 Sélectionne le protocole ISO T = 0. SCARD_PROTOCOL_T1 Sélectionne le protocole ISO T = 1.   SmartcardExtension->IoRequest.ReplyBufferLength Contient la longueur de la mémoire tampon de réponse. SmartcardExtension->CardCapabilities.PtsData Contient les paramètres requis pour effectuer la requête PTS. Pour plus d’informations, consultez PTS_DATA. La requête retourne les valeurs suivantes : SmartcardExtension->IoRequest.ReplyBuffer Contient le protocole sélectionné. SmartcardExtension->IoRequest.Information Défini sur sizeof(ULONG). L’appelant peut fournir un masque de protocoles acceptables. La routine de rappel de protocole défini par le pilote sélectionne l’un des protocoles dans le masque et retourne le protocole sélectionné dans SmartcardExtension->IoRequest.ReplyBuffer.
RDF_TRANSMIT	La fonction de rappel RDF_TRANSMIT effectue des transmissions de données. Les pilotes de lecteur smart carte doivent implémenter cette fonction de rappel. Lors de l’entrée, l’appelant doit passer les valeurs suivantes à la fonction : SmartcardExtension->MajorIoControlCode Contient IOCTL_SMARTCARD_TRANSMIT. SmartcardExtension->IoRequest.RequestBuffer Pointeur vers une structure de SCARD_IO_REQUEST suivie de données à transmettre au carte. SmartcardExtension->IoRequest.RequestBufferLength Nombre d’octets à transmettre au carte. SmartcardExtension->IoRequest.ReplyBufferLength Taille, en octets, de la mémoire tampon de réponse. La requête retourne les valeurs suivantes : SmartcardExtension->IoRequest.ReplyBuffer Pointeur vers la mémoire tampon qui reçoit la structure SCARD_IO_REQUEST, plus le résultat de la carte. SmartcardExtension->IoRequest.Information Reçoit le nombre réel d’octets retournés par le carte intelligent, plus la taille de la structure SCARD_IO_REQUEST. Pour obtenir une définition de la structure SCARD_IO_REQUEST, consultez IOCTL_SMARTCARD_TRANSMIT. Lorsque cette fonction est appelée, SmartcardExtension->IoRequest.RequestBuffer pointe vers une structure SCARD_IO_REQUEST suivie des données à transmettre. typedef struct _SCARD_IO_REQUEST{ DWORD dwProtocol; // Protocol identifier DWORD cbPciLength; // Protocol Control Information Length } SCARD_IO_REQUEST, *PSCARD_IO_REQUEST, *LPSCARD_IO_REQUEST; Le membre dwProtocol doit contenir l’identificateur de protocole retourné par un appel à IOCTL_SMARTCARD_SET_PROTOCOL. Le membre cbPciLength contient la taille, en octets, de la structure SCARD_IO_REQUEST. La taille de cette structure est généralement de 8 octets. La structure SCARD_IO_REQUEST est suivie de données (protocole) à transmettre au carte. Selon le protocole à utiliser pour la transmission, la bibliothèque offre plusieurs fonctions de support. Pour plus d’informations sur ces fonctions de prise en charge, consultez SmartcardT0Request (WDM) et SmartcardT1Request (WDM). RequestBuffer et ReplyBuffer pointent vers la même mémoire tampon système. Si vous utilisez les fonctions de bibliothèque SmartcardxxRequest et SmartcardxxReply, vous ne remplacerez pas la mémoire tampon d’entrée. Si vous n’utilisez pas ces fonctions, effectuez une copie de RequestBuffer avant de commencer les transmissions. Vous devez copier la structure SCARD_IO_REQUEST dans le paramètre ReplyBuffer, suivi des données reçues du carte. Là encore, si vous utilisez les fonctions SmartcardxxRequest et SmartcardxxReply , la bibliothèque copie la structure pour vous.

Configuration requise

Condition requise	Valeur
En-tête	smclib.h (inclure Smclib.h)