Funzione SCardListReadersWithDeviceInstanceIdA (winscard.h)

Articolo
11/20/2024

La funzione SCardListReadersWithDeviceInstanceId ottiene l'elenco dei lettori che hanno fornito un identificatore di istanza del dispositivo. Questa funzione non influisce sullo stato del lettore.

Sintassi

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

Parametri

[in] hContext

Handle che identifica il contesto di Resource Manager per la query. È possibile impostare il contesto di Resource Manager tramite una chiamata precedente alla funzione SCardEstablishContext. Questo parametro non può essere NULL.

[in] szDeviceInstanceId

ID istanza del dispositivo del lettore. È possibile ottenere questo valore chiamando la funzione SCardGetReaderDeviceInstanceId con il nome del lettore o chiamando la funzione SetupDiGetDeviceInstanceId dalla DDK.

[out, optional] mszReaders

Stringa multipla che contiene i lettori di smart card all'interno dell'identificatore dell'istanza del dispositivo fornito. Se questo valore è NULL, la funzione ignora la lunghezza del buffer fornita nel parametro pcchReaders, scrive la lunghezza del buffer che sarebbe stato restituito se questo parametro non fosse stato NULL in pcchReaderse restituisce un codice di operazione riuscita.

[in, out] pcchReaders

Lunghezza, in caratteri, del buffer mszReaders . Questo parametro riceve la lunghezza effettiva della struttura a più stringhe, inclusi tutti i caratteri Null di terminazione. Se la lunghezza del buffer viene specificata come SCARD_AUTOALLOCATE, mszReaders viene convertita in un puntatore a un puntatore a byte e riceve l'indirizzo di un blocco di memoria contenente la struttura a più stringhe. Al termine dell'utilizzo di questa memoria, deallocato tramite la funzione SCardFreeMemory.

Valore restituito

Questa funzione restituisce valori diversi a seconda che abbia esito positivo o negativo.

Codice restituito	Descrizione
esito positivo	SCARD_S_SUCCESS.
errore	Codice di errore. Per altre informazioni, vedere valori restituiti della smart card.

Osservazioni

Questa funzione non viene reindirizzata. Chiamando la funzione SCardListReadersWithDeviceInstanceId quando all'interno di una sessione di Desktop remoto si verifica un errore con il codice di errore SCARD_E_READER_UNAVAILABLE.

Esempi


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

L'intestazione winscard.h definisce SCardListReadersWithDeviceInstanceId come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows 8 [solo app desktop]
server minimo supportato	Windows Server 2012 [solo app desktop]
piattaforma di destinazione	Finestre
intestazione	winscard.h

Condividi tramite