Función SCardListReaderGroupsA (winscard.h)

Artículo
03/08/2023

La función SCardListReaderGroups proporciona la lista de grupos de lectores que se han introducido anteriormente en el sistema.

Sintaxis

LONG SCardListReaderGroupsA(
  [in]      SCARDCONTEXT hContext,
  [out]     LPSTR        mszGroups,
  [in, out] LPDWORD      pcchGroups
);

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

[out] mszGroups

Cadena múltiple que muestra los grupos de lectores definidos en el sistema y disponibles para el usuario actual en el terminal actual. Si este valor es NULL, SCardListReaderGroups omite la longitud del búfer proporcionada en pcchGroups, escribe la longitud del búfer que se habría devuelto si este parámetro no hubiera sido NULL para pcchGroups y devuelve un código correcto.

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.

[in, out] pcchGroups

Longitud del búfer mszGroups en caracteres y 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, mszGroups 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

Solo se devuelve un grupo si contiene al menos un lector. Esto incluye el grupo SCard$DefaultReaders. No se puede devolver el grupo SCard$AllReaders , ya que solo existe implícitamente.

La función SCardListReaderGroups 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 grupos de lectores.

LPTSTR          pmszReaderGroups = NULL;
LPTSTR          pReaderGroup;
LONG            lReturn;
DWORD           cch = SCARD_AUTOALLOCATE;
    
// Retrieve the list the reader groups.
// hSC was set by a previous call to SCardEstablishContext.
lReturn = SCardListReaderGroups(hSC,
                                (LPTSTR)&pmszReaderGroups,
                                &cch );
if ( SCARD_S_SUCCESS != lReturn )
    printf("Failed SCardListReaderGroups\n");
else
{
    // Do something with the multi string of reader groups.
    // Output the values.
    // A double-null terminates the list of values.
    pReaderGroup = pmszReaderGroups;
    while ( '\0' != *pReaderGroup )
    {
        // Display the value.
        printf("%S\n", pReaderGroup );
        // Advance to the next value.
        pReaderGroup = pReaderGroup + wcslen((wchar_t *) pReaderGroup) + 1;
    }

    // Remember to free pmszReaderGroups by a call to SCardFreeMemory.
    // ...
}

Nota

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