Función SCardStatusA (winscard.h)

Artículo
11/20/2024

La función SCardStatus proporciona el estado actual de una tarjeta inteligente en un lector de . Puede llamarlo en cualquier momento después de una llamada correcta a SCardConnect y antes de una llamada correcta a SCardDisconnect. No afecta al estado de del controlador lector o lector de .

Sintaxis

LONG SCardStatusA(
  [in]                SCARDHANDLE hCard,
  [out]               LPSTR       mszReaderNames,
  [in, out, optional] LPDWORD     pcchReaderLen,
  [out, optional]     LPDWORD     pdwState,
  [out, optional]     LPDWORD     pdwProtocol,
  [out]               LPBYTE      pbAtr,
  [in, out, optional] LPDWORD     pcbAtrLen
);

Parámetros

[in] hCard

Valor de referencia devuelto de SCardConnect.

[out] mszReaderNames

Lista de nombres para mostrar (varias cadenas) por las que se conoce el lector conectado actualmente.

[in, out, optional] pcchReaderLen

En la entrada, proporciona la longitud del búfer de szReaderName.

En la salida, recibe la longitud real (en caracteres) de la lista de nombres del lector, incluido el carácter final NULL. Si esta longitud del búfer se especifica como SCARD_AUTOALLOCATE, szReaderName se convierte en un puntero a un puntero de bytes y recibe la dirección de un bloque de memoria que contiene la estructura de varias cadenas.

[out, optional] pdwState

Estado actual de la tarjeta inteligente en el lector. Tras el éxito, recibe uno de los siguientes indicadores de estado.

Valor	Significado
SCARD_ABSENT	No hay ninguna tarjeta en el lector.
SCARD_PRESENT	Hay una tarjeta en el lector, pero no se ha movido a la posición para su uso.
SCARD_SWALLOWED	Hay una tarjeta en la posición del lector para su uso. La tarjeta no está encendida.
SCARD_POWERED	La alimentación se proporciona a la tarjeta, pero el controlador del lector no es consciente del modo de la tarjeta.
SCARD_NEGOTIABLE	La tarjeta se ha restablecido y está esperando la negociación ptS.
SCARD_SPECIFIC	La tarjeta se ha restablecido y se han establecido protocolos de comunicación específicos.

[out, optional] pdwProtocol

Protocolo actual, si existe. El valor devuelto solo es significativo si el valor devuelto de pdwState es SCARD_SPECIFICMODE.

Valor	Significado
SCARD_PROTOCOL_RAW	El protocolo de transferencia sin procesar está en uso.
SCARD_PROTOCOL_T0	El protocolo ISO 7816/3 T=0 está en uso.
SCARD_PROTOCOL_T1	El protocolo ISO 7816/3 T=1 está en uso.

[out] pbAtr

Puntero a un búfer de 32 bytes que recibe la cadena ATR de de la tarjeta insertada actualmente, si está disponible.

[in, out, optional] pcbAtrLen

En la entrada, proporciona la longitud del búfer de pbAtr. En la salida, recibe el número de bytes en la cadena ATR (máximo de 32 bytes). Si esta longitud del búfer se especifica como SCARD_AUTOALLOCATE, pbAtr se convierte en un puntero a un puntero de bytes y recibe la dirección de un bloque de memoria que contiene la estructura de varias cadenas.

Valor devuelto

Si la función proporciona correctamente el estado actual de una tarjeta inteligente de en un lector de , se SCARD_S_SUCCESS el valor devuelto.

Si se produce un error en la función, devuelve un código de error. Para obtener más información, consulte valores devueltos de tarjeta inteligente.

Observaciones

La función SCardStatus es un de tarjeta inteligente y función de acceso de lector. Para obtener información sobre otras funciones de acceso, consulte funciones de acceso de lector y tarjeta inteligente.

Ejemplos

En el ejemplo siguiente se muestra cómo determinar el estado de la tarjeta inteligente.

WCHAR           szReader[200];
DWORD           cch = 200;
BYTE            bAttr[32];
DWORD           cByte = 32;
DWORD           dwState, dwProtocol;
LONG            lReturn;

// Determine the status.
// hCardHandle was set by an earlier call to SCardConnect.
lReturn = SCardStatus(hCardHandle,
                      szReader,
                      &cch,
                      &dwState,
                      &dwProtocol,
                      (LPBYTE)&bAttr,
                      &cByte); 

if ( SCARD_S_SUCCESS != lReturn )
{
    printf("Failed SCardStatus\n");
    exit(1);     // or other appropriate action
}

// Examine retrieved status elements.
// Look at the reader name and card state.
printf("%S\n", szReader );
switch ( dwState )
{
    case SCARD_ABSENT:
        printf("Card absent.\n");
        break;
    case SCARD_PRESENT:
        printf("Card present.\n");
        break;
    case SCARD_SWALLOWED:
        printf("Card swallowed.\n");
        break;
    case SCARD_POWERED:
        printf("Card has power.\n");
        break;
    case SCARD_NEGOTIABLE:
        printf("Card reset and waiting PTS negotiation.\n");
        break;
    case SCARD_SPECIFIC:
        printf("Card has specific communication protocols set.\n");
        break;
    default:
        printf("Unknown or unexpected card state.\n");
        break;
}

Nota

El encabezado winscard.h define SCardStatus como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Conventions for Function Prototypes.

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows XP [solo aplicaciones de escritorio]
servidor mínimo admitido	Windows Server 2003 [solo aplicaciones de escritorio]
de la plataforma de destino de	Windows
encabezado de	winscard.h
biblioteca de	Winscard.lib
DLL de	Winscard.dll

Consulte también

SCardConnect

SCardDisconnect

Compartir a través de