Función SCardListReadersA (winscard.h)

Artículo
08/27/2023

La función SCardListReaders proporciona la lista de lectores dentro de un conjunto de grupos de lectores con nombre, lo que elimina los duplicados.

El autor de la llamada proporciona una lista de grupos de lectores y recibe la lista de lectores dentro de los grupos con nombre. Se omiten los nombres de grupo no reconocidos. Esta función solo devuelve lectores dentro de los grupos con nombre que están conectados actualmente al sistema y que están disponibles para su uso.

Sintaxis

LONG SCardListReadersA(
  [in]           SCARDCONTEXT hContext,
  [in, optional] LPCSTR       mszGroups,
  [out]          LPSTR        mszReaders,
  [in, out]      LPDWORD      pcchReaders
);

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 lectores no se limita a ningún contexto.

[in, optional] mszGroups

Nombres de los grupos de lectores definidos en el sistema, como una cadena múltiple. Use un valor NULL para enumerar todos los lectores del sistema (es decir, el grupo SCard$AllReaders).

Valor	Significado
SCARD_ALL_READERS TEXT("SCard$AllReaders\000")	Grupo usado cuando no se proporciona ningún nombre de grupo al enumerar lectores. Devuelve una lista de todos los lectores, independientemente de en qué grupo o grupos se encuentren los lectores.
SCARD_DEFAULT_READERS TEXT("SCard$DefaultReaders\000")	Grupo predeterminado al que se agregan todos los lectores cuando se introducen en el sistema.
SCARD_LOCAL_READERS TEXT("SCard$LocalReaders\000")	Valor heredado sin usar. Se trata de un grupo administrado internamente que no se puede modificar mediante ninguna API de grupo de lectores. Está pensado para usarse solo para la enumeración.
SCARD_SYSTEM_READERS TEXT("SCard$SystemReaders\000")	Valor heredado sin usar. Se trata de un grupo administrado internamente que no se puede modificar mediante ninguna API de grupo de lectores. Está pensado para usarse solo para la enumeración.

[out] mszReaders

Cadena múltiple que enumera los lectores de tarjetas dentro de los grupos de lectores proporcionados. Si este valor es NULL, SCardListReaders omite la longitud del búfer proporcionada en pcchReaders, escribe la longitud del búfer que se habría devuelto si este parámetro no hubiera sido NULL para pcchReaders y devuelve un código correcto.

[in, out] pcchReaders

Longitud del búfer mszReaders en caracteres. Este parámetro 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, mszReaders 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 se produce un error.

Código o valor devuelto	Descripción
Success 0 (0x0)	SCARD_S_SUCCESS
El grupo no contiene lectores 2148532270 (0x8010002E)	SCARD_E_NO_READERS_AVAILABLE
El lector especificado no está disponible actualmente para su uso 2148532247 (0x80100017)	SCARD_E_READER_UNAVAILABLE
Otros	Código de error. Para obtener más información, consulte Valores devueltos de tarjeta inteligente.

Comentarios

La función SCardListReaders 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.

Ejemplos

En el ejemplo siguiente se muestra cómo enumerar los lectores.

LPTSTR          pmszReaders = NULL;
LPTSTR          pReader;
LONG            lReturn, lReturn2;
DWORD           cch = SCARD_AUTOALLOCATE;

// Retrieve the list the readers.
// hSC was set by a previous call to SCardEstablishContext.
lReturn = SCardListReaders(hSC,
                           NULL,
                           (LPTSTR)&pmszReaders,
                           &cch );
switch( lReturn )
{
    case SCARD_E_NO_READERS_AVAILABLE:
        printf("Reader is not in groups.\n");
        // Take appropriate action.
        // ...
        break;

    case SCARD_S_SUCCESS:
        // Do something with the multi string of readers.
        // Output the values.
        // A double-null terminates the list of values.
        pReader = pmszReaders;
        while ( '\0' != *pReader )
        {
            // Display the value.
            printf("Reader: %S\n", pReader );
            // Advance to the next value.
            pReader = pReader + wcslen((wchar_t *)pReader) + 1;
        }
        // Free the memory.
        lReturn2 = SCardFreeMemory( hSC,
                                   pmszReaders );
        if ( SCARD_S_SUCCESS != lReturn2 )
            printf("Failed SCardFreeMemory\n");
        break;

default:
        printf("Failed SCardListReaders\n");
        // Take appropriate action.
        // ...
        break;
}

Nota

El encabezado winscard.h define SCardListReaders 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