Función SCardListCardsA (winscard.h)

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.

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).
// ...

Requisitos

Consulte también

SCardEstablishContext

SCardFreeMemory

SCardGetProviderId

SCardListInterfaces

SCardListReaderGroups

SCardListReaders