Función SCardStatusA (winscard.h)

  • Artículo

La función SCardStatus proporciona el estado actual de una tarjeta inteligente en un lector. 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 del controlador lector o lector.

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 la que se conoce el lector conectado actualmente.

[in, out, optional] pcchReaderLen

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

En la salida, recibe la longitud real (en caracteres) de la lista de nombres del lector, incluido el carácter NULL final. Si esta longitud del búfer se especifica como SCARD_AUTOALLOCATE, szReaderName se convierte en un puntero a un puntero de byte 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 el lector en posición de uso. La tarjeta no está encendida.
SCARD_POWERED
 La alimentación se proporciona a la tarjeta, pero el controlador 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 la tarjeta insertada actualmente, si está disponible.

[in, out, optional] pcbAtrLen

En la entrada, proporciona la longitud del búfer 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 byte 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 en un lector, el valor devuelto se SCARD_S_SUCCESS.

Si la función presenta un error, devuelve un código de error. Para obtener más información, consulte Valores devueltos de tarjeta inteligente.

Comentarios

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

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 Convenciones para prototipos de función.

Requisitos

Requisito Value
Cliente mínimo compatible Windows XP [solo aplicaciones de escritorio]
Servidor mínimo compatible Windows Server 2003 [solo aplicaciones de escritorio]
Plataforma de destino Windows
Encabezado winscard.h
Library Winscard.lib
Archivo DLL Winscard.dll

Consulte también

SCardConnect

SCardDisconnect