Funzione SCardListReadersW (winscard.h)

Articolo
08/27/2023

La funzione SCardListReaders fornisce l'elenco dei lettori all'interno di un set di gruppi di lettura denominati, eliminando i duplicati.

Il chiamante fornisce un elenco di gruppi di lettori e riceve l'elenco dei lettori all'interno dei gruppi denominati. I nomi dei gruppi non riconosciuti vengono ignorati. Questa funzione restituisce solo i lettori all'interno dei gruppi denominati attualmente collegati al sistema e disponibili per l'uso.

Sintassi

LONG SCardListReadersW(
  [in]           SCARDCONTEXT hContext,
  [in, optional] LPCWSTR      mszGroups,
  [out]          LPWSTR       mszReaders,
  [in, out]      LPDWORD      pcchReaders
);

Parametri

[in] hContext

Handle che identifica il contesto di Resource Manager per la query. Il contesto di Resource Manager può essere impostato da una chiamata precedente a SCardEstablishContext.

Se questo parametro è impostato su NULL, la ricerca dei lettori non è limitata ad alcun contesto.

[in, optional] mszGroups

Nomi dei gruppi di lettura definiti al sistema, come stringa multipla. Usare un valore NULL per elencare tutti i lettori del sistema , ovvero il gruppo SCard$AllReaders.

Valore	Significato
SCARD_ALL_READERS TEXT("SCard$AllReaders\000")	Gruppo utilizzato quando non viene specificato alcun nome di gruppo quando si elencano i lettori. Restituisce un elenco di tutti i lettori, indipendentemente dal gruppo o dai gruppi in cui si trovano i lettori.
SCARD_DEFAULT_READERS TEXT("SCard$DefaultReaders\000")	Gruppo predefinito a cui vengono aggiunti tutti i lettori quando vengono introdotti nel sistema.
SCARD_LOCAL_READERS TEXT("SCard$LocalReaders\000")	Valore legacy inutilizzato. Si tratta di un gruppo gestito internamente che non può essere modificato usando le API del gruppo di lettura. Deve essere usata solo per l'enumerazione.
SCARD_SYSTEM_READERS TEXT("SCard$SystemReaders\000")	Valore legacy inutilizzato. Si tratta di un gruppo gestito internamente che non può essere modificato usando le API del gruppo di lettura. Deve essere usata solo per l'enumerazione.

[out] mszReaders

Stringa multipla che elenca i lettori di schede all'interno dei gruppi di lettori forniti. Se questo valore è NULL, SCardListReaders ignora la lunghezza del buffer fornita in pcchReaders, scrive la lunghezza del buffer che sarebbe stato restituito se questo parametro non fosse stato NULL in pcchReaders e restituisce un codice di operazione riuscita.

[in, out] pcchReaders

Lunghezza del buffer mszReaders in caratteri. Questo parametro riceve la lunghezza effettiva della struttura a più stringhe, inclusi tutti i caratteri Null finali. 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. Questo blocco di memoria deve essere deallocato con SCardFreeMemory.

Valore restituito

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

Codice/valore restituito	Descrizione
Success 0 (0x0)	SCARD_S_SUCCESS
Il gruppo non contiene lettori 2148532270 (0x8010002E)	SCARD_E_NO_READERS_AVAILABLE
Il lettore specificato non è attualmente disponibile per l'uso 2148532247 (0x80100017)	SCARD_E_READER_UNAVAILABLE
Altri	Codice di errore. Per altre informazioni, vedere Valori restituiti della smart card.

Commenti

La funzione SCardListReaders è una funzione di query di database. Per altre informazioni su altre funzioni di query di database, vedere Funzioni di query del database smart card.

Esempio

L'esempio seguente mostra l'elenco dei lettori.

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

L'intestazione winscard.h definisce SCardListReaders 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 che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [solo app desktop]
Server minimo supportato	Windows Server 2003 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	winscard.h
Libreria	Winscard.lib
DLL	Winscard.dll