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

Identificador 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 de DDK.

[out, optional] mszReaders

Una 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 se hubiera NULL para pcchReadersy devuelve un código correcto.

[in, out] pcchReaders

Longitud, en caracteres, del búfer de 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, desasignela 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
correcto	SCARD_S_SUCCESS.
error de	Un código de error. Para obtener más información, consulte valores devueltos de tarjeta inteligente.

Observaciones

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 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 8 [solo aplicaciones de escritorio]
servidor mínimo admitido	Windows Server 2012 [solo aplicaciones de escritorio]
de la plataforma de destino de	Windows
encabezado de	winscard.h