Función SCardListCardsA (winscard.h)

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

El autor de la llamada especifica un 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 de contexto del administrador de recursos de 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 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, se omite este valor.

[out] mszCards

Cadena múltiple que enumera las tarjetas inteligentes encontrado. 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 se hubiera NULL a pcchCards y un código correcto.

[in, out] pcchCards

Longitud del mszCards búfer en caracteres. Recibe la longitud real de la estructura de varias cadenas, incluidos todos los caracteres finales null. Si la longitud del búfer se especifica como SCARD_AUTOALLOCATE, mszCards 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. 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
correcto	SCARD_S_SUCCESS.
error de	Un código de error. Para obtener más información, consulte valores devueltos de tarjeta inteligente.

Observaciones

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 de .

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 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

SCardEstablishContext

SCardFreeMemory

SCardGetProviderId

SCardListInterfaces

SCardListReaderGroups

SCardListReaders