Funzione SCardListReadersW (winscard.h)

Articolo
11/20/2024

La funzione SCardListReaders fornisce l'elenco dei lettori all'interno di un set di gruppi di lettori 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 gestione risorse 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 lettori definiti nel 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 pcchReaderse restituisce un codice di operazione riuscita.

[in, out] pcchReaders

Lunghezza dei mszReaders buffer in caratteri. Questo parametro riceve la lunghezza effettiva della struttura a più stringhe, inclusi tutti i caratteri null. 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
esito positivo 0 (0x0)	SCARD_S_SUCCESS
Gruppo non contiene lettori 2148532270 (0x8010002E)	SCARD_E_NO_READERS_AVAILABLE
lettore specificato non è attualmente disponibile per l'uso 2148532247 (0x80100017)	SCARD_E_READER_UNAVAILABLE
Altro	Codice di errore. Per altre informazioni, vedere valori restituiti della smart card.

Osservazioni

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.

Esempi

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 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 XP [solo app desktop]
server minimo supportato	Windows Server 2003 [solo app desktop]
piattaforma di destinazione	Finestre
intestazione	winscard.h
libreria	Winscard.lib
dll	Winscard.dll

Vedere anche

SCardEstablishContext

SCardFreeMemory

SCardGetProviderId

SCardListCards

SCardListInterfaces

SCardListReaderGroups

Condividi tramite