Función SCardListReadersWithDeviceInstanceIdA (winscard.h)

La función SCardListReadersWithDeviceInstanceId obtiene la lista de lectores que han proporcionado un identificador de instancia de dispositivo. Esta función no afecta al estado del lector.

Sintaxis

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

Parámetros

[in] hContext

Identificador que identifica el contexto del administrador de recursos para la consulta. Puede establecer el contexto del administrador de recursos mediante una llamada anterior a la función SCardEstablishContext . Este parámetro no puede ser NULL.

[in] szDeviceInstanceId

Id. de instancia de dispositivo del lector. Puede obtener este valor llamando a la función SCardGetReaderDeviceInstanceId con el nombre del lector o llamando a la función SetupDiGetDeviceInstanceId desde el DDK.

[out, optional] mszReaders

Cadena múltiple que contiene los lectores de tarjetas inteligentes dentro del identificador de instancia de dispositivo proporcionado. Si este valor es NULL, la función omite la longitud del búfer proporcionada en el parámetro 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, en caracteres, del búfer mszReaders . Este parámetro recibe la longitud real de la estructura de varias cadenas, incluidos todos los caracteres NULOs de terminación. Si la longitud del búfer se especifica como SCARD_AUTOALLOCATE, mszReaders 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. Cuando haya terminado de usar esta memoria, desasignóla mediante la función 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

Esta función no se redirige. Llamar a la función SCardListReadersWithDeviceInstanceId cuando se produce un error en una sesión de Escritorio remoto con el código de error SCARD_E_READER_UNAVAILABLE.

Ejemplos

szDeviceInstanceIdcchReaderNameLONG     lReturn, lReturn2;

LPTSTR   pmszReaders = NULL;
LPTSTR   pReader = NULL;WCHAR
DWORD    cchReaderName = SCARD_AUTOALLOCATE;

// Retrieve the reader’s name from it’s device instance ID
// hContext was set by a previous call to SCardEstablishContext. 

// szDeviceInstanceId was obtained by calling SetupDiGetDeviceInstanceId
lReturn = SCardListReadersWithDeviceInstanceId (hContext,
                         szDeviceInstanceId,
                         (LPTSTR)&pmszReaders,
                         &cchReaderName);

switch( lReturn )
{
    case SCARD_E_NO_READERS_AVAILABLE:
        printf("No readers have the provided device instance ID.\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( hContext,
                                   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 SCardListReadersWithDeviceInstanceId 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

Cliente mínimo compatible	Windows 8 [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2012 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	winscard.h