Funzione SCardListReaderGroupsA (winscard.h)

Articolo
03/13/2024

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

Sintassi

LONG SCardListReaderGroupsA(
  [in]      SCARDCONTEXT hContext,
  [out]     LPSTR        mszGroups,
  [in, out] LPDWORD      pcchGroups
);

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

[out] mszGroups

Stringa multipla che elenca i gruppi di lettura definiti nel 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 stata restituita se questo parametro non era stato NULL a pcchGroups e restituisce un codice di esito positivo.

Valore	Significato
SCARD_ALL_READERS TEXT("SCard$AllReaders\000")	Gruppo usato quando non viene fornito 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 usato 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 usato solo per l'enumerazione.

[in, out] pcchGroups

Lunghezza del buffer mszGroups in caratteri e 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, mszGroups viene convertito in un puntatore a un puntatore a un puntatore di 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
Success	SCARD_S_SUCCESS.
Operazioni non riuscite	Codice di errore. Per altre informazioni, vedere Valori restituiti smart card.

Commenti

Viene restituito un gruppo solo se contiene almeno un lettore. 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.

Esempio

Nell'esempio seguente viene illustrato 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 preprocessore UNICODE. La combinazione dell'utilizzo dell'alias di codifica neutrale con il codice che non è neutrale dalla codifica può causare errori di corrispondenza che causano errori di compilazione o runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzione.

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