Funzione SCardListReaderGroupsW (winscard.h)

Articolo
11/20/2024

La funzione SCardListReaderGroups fornisce l'elenco dei gruppi di lettura introdotti in precedenza nel sistema.

Sintassi

LONG SCardListReaderGroupsW(
  [in]      SCARDCONTEXT hContext,
  [out]     LPWSTR       mszGroups,
  [in, out] LPDWORD      pcchGroups
);

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 di gruppi di lettori non è limitata ad alcun contesto.

[out] mszGroups

Multi-stringa che elenca i gruppi di lettura definiti al sistema e disponibili per l'utente corrente nel terminale corrente. Se questo valore è NULL, SCardListReaderGroups ignora la lunghezza del buffer fornita in pcchGroups, scrive la lunghezza del buffer che sarebbe stato restituito se questo parametro non fosse stato null per pcchGroupse restituisce un codice di operazione riuscita.

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.

[in, out] pcchGroups

Lunghezza della mszGroups buffer in caratteri e riceve la lunghezza effettiva della struttura a più stringhe, inclusi tutti i caratteri null. Se la lunghezza del buffer viene specificata come SCARD_AUTOALLOCATE, mszGroups 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 restituito	Descrizione
esito positivo	SCARD_S_SUCCESS.
errore	Codice di errore. Per altre informazioni, vedere valori restituiti della smart card.

Osservazioni

Viene restituito un gruppo solo se contiene almeno un lettore . Questo include il gruppo SCard$DefaultReaders. Impossibile restituire il gruppo SCard$AllReaders, poiché esiste solo in modo implicito.

La funzione SCardListReaderGroups è 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 gruppi di lettori.

LPTSTR          pmszReaderGroups = NULL;
LPTSTR          pReaderGroup;
LONG            lReturn;
DWORD           cch = SCARD_AUTOALLOCATE;
    
// Retrieve the list the reader groups.
// hSC was set by a previous call to SCardEstablishContext.
lReturn = SCardListReaderGroups(hSC,
                                (LPTSTR)&pmszReaderGroups,
                                &cch );
if ( SCARD_S_SUCCESS != lReturn )
    printf("Failed SCardListReaderGroups\n");
else
{
    // Do something with the multi string of reader groups.
    // Output the values.
    // A double-null terminates the list of values.
    pReaderGroup = pmszReaderGroups;
    while ( '\0' != *pReaderGroup )
    {
        // Display the value.
        printf("%S\n", pReaderGroup );
        // Advance to the next value.
        pReaderGroup = pReaderGroup + wcslen((wchar_t *) pReaderGroup) + 1;
    }

    // Remember to free pmszReaderGroups by a call to SCardFreeMemory.
    // ...
}

Nota

L'intestazione winscard.h definisce SCardListReaderGroups 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

SCardListReaders

Condividi tramite