Funzione SCardListCardsA (winscard.h)

Articolo
11/20/2024

La funzione SCardListCards cerca il database di smart card e fornisce un elenco di schede denominate introdotte in precedenza nel sistema dall'utente.

Il chiamante specifica un stringa ATR, un set di identificatori di interfaccia (GUID) o entrambi. Se vengono fornite sia una stringa ATR che una matrice di identificatori, le schede restituite corrisponderanno alla stringa ATR fornita e supporteranno le interfacce specificate.

Sintassi

LONG SCardListCardsA(
  [in]           SCARDCONTEXT hContext,
  [in, optional] LPCBYTE      pbAtr,
  [in]           LPCGUID      rgquidInterfaces,
  [in]           DWORD        cguidInterfaceCount,
  [out]          CHAR         *mszCards,
  [in, out]      LPDWORD      pcchCards
);

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 delle schede non è limitata ad alcun contesto.

[in, optional] pbAtr

Indirizzo di una stringa ATR da confrontare con le schede note o NULL se non deve essere eseguita alcuna corrispondenza ATR.

[in] rgquidInterfaces

Matrice di identificatori (GUID) o null se non deve essere eseguita alcuna corrispondenza dell'interfaccia. Quando viene fornita una matrice, verrà restituito un nome di scheda solo se tutti gli identificatori specificati sono supportati dalla scheda.

[in] cguidInterfaceCount

Numero di voci nella matrice rgguidInterfaces. Se rgguidInterfaces è null, questo valore viene ignorato.

[out] mszCards

Stringa multipla che elenca le smart card trovate. Se questo valore è NULL, SCardListCardCards ignora la lunghezza del buffer fornita in pcchCards, restituendo la lunghezza del buffer che sarebbe stato restituito se questo parametro non fosse stato NULL per pcchCards e un codice di operazione riuscita.

[in, out] pcchCards

Lunghezza del buffer mszCards in caratteri. Riceve la lunghezza effettiva della struttura a più stringhe, inclusi tutti i caratteri null. Se la lunghezza del buffer viene specificata come SCARD_AUTOALLOCATE, mszCards viene convertita in un puntatore a un puntatore a un 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

Questa funzione non viene reindirizzata, ma la chiamata alla funzione quando all'interno di una sessione desktop remoto non verrà generato un errore. Significa solo che il risultato sarà dal computer remoto anziché dal computer locale.

Per restituire tutte le smart card introdotte nel sottosistema, impostare pbAtr e rgguidInterfaces su NULL.

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

La chiamata a questa funzione deve essere eseguita all'esterno di una transazione. Se un'applicazione avvia una transazione con la funzione di SCardBeginTransaction e quindi chiama questa funzione, reimposta il parametro hCard (di tipo SCARDHANDLE) della funzione SCardBeginTransaction.

Windows Server 2008 R2 e Windows 7: La chiamata di questa funzione all'interno di una transazione potrebbe causare la mancata risposta del computer.

Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: Non applicabile.

Esempi

L'esempio seguente mostra l'elenco delle smart card.

LPTSTR pmszCards = NULL;
LPTSTR pCard;
LONG lReturn;
DWORD cch = SCARD_AUTOALLOCATE;

// Retrieve the list of cards.
lReturn = SCardListCards(NULL,
                         NULL,
                         NULL,
                         NULL,
                         (LPTSTR)&pmszCards,
                         &cch );
if ( SCARD_S_SUCCESS != lReturn )
{
    printf("Failed SCardListCards\n");
    exit(1); // Or other appropriate error action
}
// Do something with the multi string of cards.
// Output the values.
// A double-null terminates the list of values.
pCard = pmszCards;
while ( '\0' != *pCard )
{
    // Display the value.
    printf("%S\n", pCard );
    // Advance to the next value.
    pCard = pCard + wcslen(pCard) + 1;
}

// Remember to free pmszCards (by calling SCardFreeMemory).
// ...

Nota

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

SCardListInterfaces

SCardListReaderGroups

SCardListReaders

Condividi tramite