Funzione SCardListCardsA (winscard.h)

Articolo
03/13/2024

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

Il chiamante specifica una 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 corrispondono alla stringa ATR fornita e supportano 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 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 schede non è limitata a alcun contesto.

[in, optional] pbAtr

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

[in] rgquidInterfaces

Matrice di identificatori (GUID) o NULL se non viene 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, SCardListCards 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 riuscito.

[in, out] pcchCards

Lunghezza del buffer mszCards in caratteri. 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, mszCards viene convertita 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

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 SCardListCardCards è 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 di questa funzione deve essere eseguita all'esterno di una transazione. Se un'applicazione inizia una transazione con la funzione 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 comportare la mancata risposta del computer.

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

Esempio

Nell'esempio seguente viene illustrato 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 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