Función SCardListCardsA (winscard.h)

Artículo
08/27/2023

La función SCardListCards busca en la base de datos de tarjetas inteligentes y proporciona una lista de tarjetas con nombre introducidas previamente en el sistema por el usuario.

El autor de la llamada especifica una cadena ATR, un conjunto de identificadores de interfaz (GUID) o ambos. Si se proporciona una cadena ATR y una matriz de identificadores, las tarjetas devueltas coincidirán con la cadena ATR proporcionada y admitirán las interfaces especificadas.

Sintaxis

LONG SCardListCardsA(
  [in]           SCARDCONTEXT hContext,
  [in, optional] LPCBYTE      pbAtr,
  [in]           LPCGUID      rgquidInterfaces,
  [in]           DWORD        cguidInterfaceCount,
  [out]          CHAR         *mszCards,
  [in, out]      LPDWORD      pcchCards
);

Parámetros

[in] hContext

Identificador que identifica el contexto del administrador de recursos para la consulta. El contexto del administrador de recursos se puede establecer mediante una llamada anterior a SCardEstablishContext.

Si este parámetro se establece en NULL, la búsqueda de tarjetas no se limita a ningún contexto.

[in, optional] pbAtr

Dirección de una cadena ATR que se va a comparar con las tarjetas conocidas o NULL si no se va a realizar ninguna coincidencia de ATR.

[in] rgquidInterfaces

Matriz de identificadores (GUID) o NULL si no se va a realizar ninguna coincidencia de interfaz. Cuando se proporciona una matriz, solo se devolverá un nombre de tarjeta si la tarjeta admite todos los identificadores especificados.

[in] cguidInterfaceCount

Número de entradas de la matriz rgguidInterfaces . Si rgguidInterfaces es NULL, este valor se omite.

[out] mszCards

Cadena múltiple que enumera las tarjetas inteligentes encontradas . Si este valor es NULL, SCardListCards omite la longitud del búfer proporcionada en pcchCards, devolviendo la longitud del búfer que se habría devuelto si este parámetro no hubiera sido NULL para pcchCards y un código correcto.

[in, out] pcchCards

Longitud del búfer mszCards en caracteres. Recibe la longitud real de la estructura de varias cadenas, incluidos todos los caracteres NULL finales. Si la longitud del búfer se especifica como SCARD_AUTOALLOCATE, mszCards 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. Este bloque de memoria debe desasignarse con SCardFreeMemory.

Valor devuelto

Esta función devuelve valores diferentes en función de si se realiza correctamente o no.

Código devuelto	Descripción
Success	SCARD_S_SUCCESS.
Error	Código de error. Para obtener más información, consulte Valores devueltos de tarjeta inteligente.

Comentarios

Esta función no se redirige, pero llamar a la función cuando se encuentra dentro de una sesión de Escritorio remoto no producirá un error. Solo significa que el resultado será del equipo remoto en lugar del equipo local.

Para devolver todas las tarjetas inteligentes introducidas en el subsistema, establezca pbAtr y rgguidInterfaces en NULL.

La función SCardListCards es una función de consulta de base de datos. Para obtener más información sobre otras funciones de consulta de base de datos, consulte Funciones de consulta de base de datos de tarjeta inteligente.

Llamar a esta función debe realizarse fuera de una transacción. Si una aplicación inicia una transacción con la función SCardBeginTransaction y, a continuación, llama a esta función, restablece el parámetro hCard (de tipo SCARDHANDLE) de la función SCardBeginTransaction .

Windows Server 2008 R2 y Windows 7: Llamar a esta función dentro de una transacción podría provocar que el equipo deje de responder.

Windows Server 2008, Windows Vista, Windows Server 2003 y Windows XP: No aplicable.

Ejemplos

En el ejemplo siguiente se muestra la lista de las tarjetas inteligentes.

LPTSTR pmszCards = NULL;
LPTSTR pCard;
LONG lReturn;
DWORD cch = SCARD_AUTOALLOCATE;

// Retrieve the list of cards.
lReturn = SCardListCards(NULL,
                         NULL,
                         NULL,
                         NULL,
                         (LPTSTR)&pmszCards,
                         &cch );
if ( SCARD_S_SUCCESS != lReturn )
{
    printf("Failed SCardListCards\n");
    exit(1); // Or other appropriate error action
}
// Do something with the multi string of cards.
// Output the values.
// A double-null terminates the list of values.
pCard = pmszCards;
while ( '\0' != *pCard )
{
    // Display the value.
    printf("%S\n", pCard );
    // Advance to the next value.
    pCard = pCard + wcslen(pCard) + 1;
}

// Remember to free pmszCards (by calling SCardFreeMemory).
// ...

Nota

El encabezado winscard.h define SCardListCards como un 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 neutro de codificación con código que no es neutral de codificación puede provocar discrepancias que dan lugar a errores de compilación o en 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