estructura SMARTCARD_EXTENSION (smclib.h)

Tanto el controlador de lector de tarjetas inteligentes como la biblioteca de controladores de tarjetas inteligentes usan la estructura SMARTCARD_EXTENSION para acceder a todas las demás estructuras de datos de tarjeta inteligente.

Sintaxis

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;

Miembros

Version

Indica la versión de esta estructura.

VendorAttr

Contiene información que identifica el controlador del lector, como el nombre del proveedor, el número de unidad y el número de serie.

ReaderFunction[16]

La línea del bloque de sintaxis debe leerse. NTSTATUS (*ReaderFunction[16])(PSMARTCARD_EXTENSION);

Puntero a una matriz de funciones de devolución de llamada para lectores. Las funciones de devolución de llamada que puede implementar un controlador de lector proporcionado por el proveedor. Un controlador de lector hace que estas funciones de devolución de llamada estén disponibles para la rutina de la biblioteca de tarjetas inteligentes, SmartcardDeviceControl, para llamar mediante el almacenamiento de punteros a ellas en la extensión del dispositivo de tarjeta 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 obtener más información, vea la sección Comentarios.

CardCapabilities

Contiene funcionalidades de la tarjeta inteligente insertada.

LastError

No se usa.

IoRequest

Estructura con los siguientes miembros:

IoRequest.Information

Contiene el número de bytes devueltos.

IoRequest.RequestBuffer

Puntero a los datos de la solicitud de E/S del usuario que se enviará a la tarjeta.

IoRequest.RequestBufferLength

Indica el número de bytes que se van a enviar a la tarjeta.

IoRequest.ReplyBuffer

Puntero al búfer que contiene los datos devueltos por la solicitud de E/S.

IoRequest.ReplyBufferLength

Indica el número de bytes de los datos devueltos por la solicitud de E/S.

MajorIoControlCode

Contiene el código de control de E/S principal.

MinorIoControlCode

Contiene el código de control de E/S secundario.

OsData

Contiene información específica del sistema operativo y del tipo de controlador.

ReaderCapabilities

Contiene las funcionalidades del lector de teclado.

ReaderExtension

Contiene datos específicos del lector de tarjetas inteligentes.

SmartcardReply

Contiene datos procedentes del lector.

SmartcardRequest

Contiene el comando actual y los datos que se envían a la tarjeta inteligente.

T0

Contiene los datos para su uso con el protocolo T=0.

T1

Contiene los datos que se usan con el protocolo T=1.

PerfInfo

Reserved[25 - sizeof(PPERF_INFO)]

Reservado para uso del sistema.

Comentarios

Esta estructura se pasa a todas las funciones de devolución de llamada.

Las funciones de devolución de llamada individuales se identifican mediante una serie de valores constantes que se deben usar como índices en la matriz ReaderFunction .

Índice	Descripción
RDF_ATR_PARSE	Opcional. La función de análisis de RDF_ATR_PARSE analiza una respuesta a restablecimiento (ATR) para la biblioteca de controladores de tarjeta inteligente cuando la biblioteca de controladores no puede reconocer o analizar la biblioteca de controladores de tarjeta inteligente.
RDF_CARD_EJECT	Opcional. RDF_CARD_EJECT función de devolución de llamada La función de devolución de llamada RDF_CARD_EJECT expulsa una tarjeta inteligente insertada del lector.
RDF_CARD_POWER	La función de devolución de llamada RDF_CARD_POWER restablece o desactiva una tarjeta inteligente insertada. Es obligatorio que los controladores de lector de tarjetas inteligentes implementen esta función de devolución de llamada. En la entrada, la estructura a la que apunta SmartcardExtension debe tener los siguientes valores de miembro: MajorIoControlCode Debe tener un valor de IOCTL_SMARTCARD_POWER. IoRequest.ReplyBufferLength Debe contener la longitud del búfer. MinorIoControlCode Debe tener uno de los siguientes códigos secundarios: SCARD_COLD_RESET Realiza un restablecimiento en frío de la tarjeta inteligente. SCARD_WARM_RESET Realiza un restablecimiento intermedio de la tarjeta inteligente. SCARD_POWER_DOWN Desactiva la alimentación de la tarjeta inteligente. En la salida, la estructura a la que apunta SmartcardExtension debe tener los siguientes valores: IoRequest.ReplyBuffer Recibe el ATR devuelto por la tarjeta inteligente. Además, debe transferir ATR a SmartcardExtension->CardCapabilities.ATR.Buffer para que la biblioteca pueda analizar el ATR. IoRequest.Information Recibe la longitud del ATR. CardCapabilities.ATR.Length Contiene la longitud del ATR.
RDF_CARD_TRACKING	La función de devolución de llamada RDF_CARD_TRACKING instala un controlador de eventos para realizar un seguimiento cada vez que se inserta o quita una tarjeta de un lector de tarjetas. Es obligatorio que los controladores de lector de tarjetas inteligentes implementen esta función de devolución de llamada. Al recibir una solicitud de IOCTL_SMARTCARD_IS_PRESENT , la biblioteca de controladores determina si la tarjeta inteligente ya está presente. Si la tarjeta inteligente está presente, la biblioteca de controladores completa la solicitud con un estado de STATUS_SUCCESS. Si no hay ninguna tarjeta inteligente presente, la biblioteca de controladores llama a la función de devolución de llamada de seguimiento de tarjetas inteligentes del controlador del lector y el controlador del lector comienza a buscar la tarjeta inteligente. Después de iniciar el seguimiento de tarjetas inteligentes, la biblioteca de controladores marca la solicitud como si tuviera un estado de STATUS_PENDING. La biblioteca de controladores completa la solicitud. Controladores de dispositivo WDM La biblioteca de controladores WDM correspondiente agrega un puntero a la solicitud en SmartcardExtension-OsData-NotificationIrp>>. El controlador del lector debe completar la solicitud tan pronto como detecte que se ha insertado o quitado una tarjeta inteligente. El controlador de lector completa la solicitud llamando a IoCompleteRequest, después de lo cual, el controlador de lector debe establecer el miembro NotificationIrp de SmartcardExtension -> OsData en NULL para informar a la biblioteca de controladores de que el controlador del lector puede aceptar más solicitudes de seguimiento de tarjetas inteligentes. Dado que esta llamada puede tener una duración indefinida y el autor de la llamada puede finalizar la solicitud antes de que se complete, es importante marcar este IRP como cancelable. 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 función de devolución de llamada RDF_IOCTL_VENDOR realiza operaciones IOCTL específicas del proveedor. Es opcional que los controladores de lector de tarjetas inteligentes implementen esta función de devolución de llamada. En la entrada, el autor de la llamada debe pasar los siguientes valores a la función : SmartcardExtension->MajorIoControlCode Contiene un código IOCTL específico del proveedor. Consulte la macro SCARD_CTL_CODE en Winsmcrd.h para obtener información sobre cómo definir un código IOCTL específico del proveedor. Tenga en cuenta que el código debe estar comprendido entre 2048 y 4095. SmartcardExtension->IoRequest.RequestBuffer Puntero al búfer de entrada del usuario. SmartcardExtension->IoRequest.RequestBufferLength Tamaño, en bytes, del búfer de entrada del usuario. SmartcardExtension->IoRequest.ReplyBuffer Puntero al búfer de salida del usuario. SmartcardExtension->IoRequest.ReplyBufferLength Tamaño, en bytes, del búfer de salida del usuario. SmartcardExtension->IoRequest.Information Valor proporcionado por la solicitud. Debe establecerse en el número de bytes devueltos. Al igual que con el resto de ICTLs, una aplicación en modo de usuario envía un IOCTL definido por el proveedor a un dispositivo de lector de tarjetas inteligentes llamando a la función DeviceIoControl . Sin embargo, cuando el IOCTL está definido por el proveedor, la aplicación debe abrir primero el dispositivo lector para el acceso "superpuesto" (es decir, asincrónico). La aplicación también debe definir una estructura SUPERPUESTA y pasarla al sistema en el último argumento de DeviceIoControl (la estructura SUPERPUESTA también se describe en la documentación de Windows SDK). Cuando el sistema operativo llama a la rutina de distribución del control de E/S del controlador, pasa una estructura DIOCPARAMETERS al controlador. El miembro lpoOverlapped de la estructura DIOCPARAMETERS contiene un puntero a la estructura SUPERPUESTA.
RDF_READER_SWALLOW	La función de devolución de llamada RDF_READER_SWALLOW realiza una ingestión mecánica, que es lo que sucede cuando la tarjeta inteligente se inserta completamente en el lector de tarjetas inteligentes. Es opcional que los controladores de lector de tarjetas inteligentes implementen esta función de devolución de llamada.
RDF_SET_PROTOCOL	La función de devolución de llamada RDF_SET_PROTOCOL selecciona un protocolo de transmisión para la tarjeta inteligente insertada. Los controladores de lector de tarjetas inteligentes deben implementar esta función de devolución de llamada. En la entrada, el autor de la llamada debe pasar los siguientes valores a la función : SmartcardExtension->MajorIoControlCode Contiene IOCTL_SMARTCARD_SET_PROTOCOL. SmartcardExtension->MinorIoControlCode Contiene un OR bit a bit de uno o varios protocolos que el autor de la llamada acepta. El controlador debe seleccionar un protocolo que admita la tarjeta inteligente insertada. Se recomienda que el protocolo T = 1 tenga prioridad sobre el protocolo T = 0. Valor Significado SCARD_PROTOCOL_RAW Selecciona el protocolo sin procesar. SCARD_PROTOCOL_T0 Selecciona el protocolo ISO T = 0. SCARD_PROTOCOL_T1 Selecciona el protocolo ISO T = 1.   SmartcardExtension->IoRequest.ReplyBufferLength Contiene la longitud del búfer de respuesta. SmartcardExtension->CardCapabilities.PtsData Contiene los parámetros necesarios para realizar la solicitud PTS. Para obtener más información, consulte PTS_DATA. La solicitud devuelve los valores siguientes: SmartcardExtension->IoRequest.ReplyBuffer Contiene el protocolo seleccionado. SmartcardExtension->IoRequest.Information Establezca en sizeof(ULONG). El autor de la llamada puede proporcionar una máscara de protocolos aceptables. La rutina de devolución de llamada del protocolo set del controlador selecciona uno de los protocolos de la máscara y devuelve el protocolo seleccionado en SmartcardExtension->IoRequest.ReplyBuffer.
RDF_TRANSMIT	La función de devolución de llamada RDF_TRANSMIT realiza transmisiones de datos. Los controladores de lector de tarjetas inteligentes deben implementar esta función de devolución de llamada. En la entrada, el autor de la llamada debe pasar los siguientes valores a la función : SmartcardExtension->MajorIoControlCode Contiene IOCTL_SMARTCARD_TRANSMIT. SmartcardExtension->IoRequest.RequestBuffer Puntero a una estructura de SCARD_IO_REQUEST seguida de los datos que se van a transmitir a la tarjeta. SmartcardExtension->IoRequest.RequestBufferLength Número de bytes que se van a transmitir a la tarjeta. SmartcardExtension->IoRequest.ReplyBufferLength Tamaño, en bytes, del búfer de respuesta. La solicitud devuelve los valores siguientes: SmartcardExtension->IoRequest.ReplyBuffer Puntero al búfer que recibe la estructura SCARD_IO_REQUEST, además del resultado de la tarjeta. SmartcardExtension->IoRequest.Information Recibe el número real de bytes devueltos por la tarjeta inteligente, además del tamaño de la estructura de SCARD_IO_REQUEST. Para obtener una definición de la estructura de SCARD_IO_REQUEST, consulte IOCTL_SMARTCARD_TRANSMIT. Cuando se llama a esta función, SmartcardExtension->IoRequest.RequestBuffer apunta a una estructura de SCARD_IO_REQUEST seguida de los datos que se van a transmitir. typedef struct _SCARD_IO_REQUEST{ DWORD dwProtocol; // Protocol identifier DWORD cbPciLength; // Protocol Control Information Length } SCARD_IO_REQUEST, *PSCARD_IO_REQUEST, *LPSCARD_IO_REQUEST; El miembro dwProtocol debe contener el identificador de protocolo devuelto por una llamada a IOCTL_SMARTCARD_SET_PROTOCOL. El miembro cbPciLength contiene el tamaño, en bytes, de la estructura SCARD_IO_REQUEST. El tamaño de esta estructura suele ser de 8 bytes. La estructura de SCARD_IO_REQUEST va seguida de los datos (protocolo) que se van a transmitir a la tarjeta. Dependiendo del protocolo que se va a usar para la transmisión, la biblioteca ofrece varias funciones de soporte técnico. Para obtener más información sobre estas funciones de compatibilidad, vea SmartcardT0Request (WDM) y SmartcardT1Request (WDM). RequestBuffer y ReplyBuffer apuntan al mismo búfer del sistema. Si usa la función de biblioteca SmartcardxxRequest y SmartcardxxReply, no sobrescribirá el búfer de entrada. Si no usa estas funciones, realice una copia de RequestBuffer antes de iniciar las transmisiones. Debe copiar la estructura de SCARD_IO_REQUEST en el parámetro ReplyBuffer , seguido de los datos recibidos de la tarjeta. De nuevo, si usa las funciones SmartcardxxRequest y SmartcardxxReply , la biblioteca copiará la estructura.

Requisitos

Requisito	Valor
Header	smclib.h (incluya Smclib.h)