Función SCardListReaderGroupsA (winscard.h)

Artículo
11/20/2024

La función SCardListReaderGroups proporciona la lista de grupos de lectores de 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 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 grupos de lectores no se limita a ningún contexto.

[out] mszGroups

Cadena múltiple que enumera 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 se hubiera null para pcchGroupsy 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 del grupo o grupos en los que se encuentran 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 mszGroups búfer en caracteres y 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, mszGroups 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

Solo se devuelve un grupo si contiene al menos un lector de . 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 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

SCardListCards

SCardListInterfaces

SCardListReaders

Compartir a través de