SCardListReadersWithDeviceInstanceIdA function (winscard.h)

The SCardListReadersWithDeviceInstanceId function gets the list of readers that have provided a device instance identifier. This function does not affect the state of the reader.

Syntax

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

Parameters

[in] hContext

Handle that identifies the resource manager context for the query. You can set the resource manager context by a previous call to the SCardEstablishContext function. This parameter cannot be NULL.

[in] szDeviceInstanceId

Device instance ID of the reader. You can get this value by calling the SCardGetReaderDeviceInstanceId function with the reader name or by calling the SetupDiGetDeviceInstanceId function from the DDK.

[out, optional] mszReaders

A multi-string that contain the smart card readers within the supplied device instance identifier. If this value is NULL, then the function ignores the buffer length supplied in the pcchReaders parameter, writes the length of the buffer that would have been returned if this parameter had not been NULL to pcchReaders, and returns a success code.

[in, out] pcchReaders

The length, in characters, of the mszReaders buffer. This parameter receives the actual length of the multiple-string structure, including all terminating null characters. If the buffer length is specified as SCARD_AUTOALLOCATE, then mszReaders is converted to a pointer to a byte pointer, and receives the address of a block of memory that contains the multiple-string structure. When you have finished using this memory, deallocated it by using the SCardFreeMemory function.

Return value

This function returns different values depending on whether it succeeds or fails.

Remarks

This function is not redirected. Calling the SCardListReadersWithDeviceInstanceId function when inside a Remote Desktop session fails with the SCARD_E_READER_UNAVAILABLE error code.

Examples

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;

Requirements