SCardListCardsA, fonction (winscard.h)

Article
03/13/2024

La fonction SCardListCards recherche la base de données smart carte et fournit une liste de cartes nommées introduites précédemment dans le système par l’utilisateur.

L’appelant spécifie une chaîne ATR, un ensemble d’identificateurs d’interface (GUID) ou les deux. Si une chaîne ATR et un tableau d’identificateurs sont fournis, les cartes retournées correspondent à la chaîne ATR fournie et prennent en charge les interfaces spécifiées.

Syntaxe

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

Paramètres

[in] hContext

Handle qui identifie le contexte resource manager pour la requête. Le contexte resource manager peut être défini par un appel précédent à SCardEstablishContext.

Si ce paramètre a la valeur NULL, la recherche de cartes n’est limitée à aucun contexte.

[in, optional] pbAtr

Adresse d’une chaîne ATR à comparer aux cartes connues, ou NULL si aucune correspondance ATR ne doit être effectuée.

[in] rgquidInterfaces

Tableau d’identificateurs (GUID) ou NULL si aucune correspondance d’interface ne doit être effectuée. Lorsqu’un tableau est fourni, un nom de carte est retourné uniquement si tous les identificateurs spécifiés sont pris en charge par le carte.

[in] cguidInterfaceCount

Nombre d’entrées dans le tableau rgguidInterfaces . Si rgguidInterfaces a la valeur NULL, cette valeur est ignorée.

[out] mszCards

Multi-chaîne qui répertorie les cartes à puce trouvées . Si cette valeur est NULL, SCardListCards ignore la longueur de la mémoire tampon fournie dans pcchCards, renvoyant la longueur de la mémoire tampon qui aurait été retournée si ce paramètre n’avait pas été NULL pour pcchCards et un code de réussite.

[in, out] pcchCards

Longueur de la mémoire tampon mszCards en caractères. Reçoit la longueur réelle de la structure à chaînes multiples, y compris tous les caractères null de fin. Si la longueur de la mémoire tampon est spécifiée en tant que SCARD_AUTOALLOCATE, mszCards est converti en pointeur vers un pointeur d’octet et reçoit l’adresse d’un bloc de mémoire contenant la structure multi-chaîne. Ce bloc de mémoire doit être libéré avec SCardFreeMemory.

Valeur retournée

Cette fonction retourne des valeurs différentes selon qu’elle réussit ou échoue.

Code de retour	Description
Success	SCARD_S_SUCCESS.
Échec	Code d'erreur. Pour plus d’informations, consultez Valeurs de retour de carte à puce.

Remarques

Cette fonction n’est pas redirigée, mais l’appel de la fonction à l’intérieur d’une session Bureau à distance n’entraîne pas d’erreur. Cela signifie uniquement que le résultat provient de l’ordinateur distant au lieu de l’ordinateur local.

Pour retourner toutes les cartes à puce introduites dans le sous-système, définissez pbAtr et rgguidInterfaces sur NULL.

La fonction SCardListCards est une fonction de requête de base de données. Pour plus d’informations sur d’autres fonctions de requête de base de données, consultez Fonctions de requête de base de données de carte à puce.

L’appel de cette fonction doit être effectué en dehors d’une transaction. Si une application commence une transaction avec la fonction SCardBeginTransaction , puis appelle cette fonction, elle réinitialise le paramètre hCard (de type SCARDHANDLE) de la fonction SCardBeginTransaction .

Windows Server 2008 R2 et Windows 7 : L’appel de cette fonction dans une transaction peut entraîner la non-réponse de votre ordinateur.

Windows Server 2008, Windows Vista, Windows Server 2003 et Windows XP : Non applicable.

Exemples

L’exemple suivant montre la liste des cartes à puce.

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).
// ...

Notes

L’en-tête winscard.h définit SCardListCards comme alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	winscard.h
Bibliothèque	Winscard.lib
DLL	Winscard.dll