Función SCardListReadersA (winscard.h)
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).
[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 |
---|---|
|
SCARD_S_SUCCESS |
|
SCARD_E_NO_READERS_AVAILABLE |
|
SCARD_E_READER_UNAVAILABLE |
|
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 |