SCardListCardsW, fonction (winscard.h)

Article
11/20/2024

La fonction SCardListCards recherche la base de données de cartes à puce et fournit une liste de cartes nommées introduites précédemment 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 SCardListCardsW(
  [in]           SCARDCONTEXT hContext,
  [in, optional] LPCBYTE      pbAtr,
  [in]           LPCGUID      rgquidInterfaces,
  [in]           DWORD        cguidInterfaceCount,
  [out]          WCHAR        *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 est défini sur 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 n’est à effectuer.

[in] rgquidInterfaces

Tableau d’identificateurs (GUID) ou NULL si aucune correspondance d’interface n’est 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 la carte.

[in] cguidInterfaceCount

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

[out] mszCards

Chaîne multiple 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 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 multi-chaîne, y compris tous les caractères de fin null. Si la longueur de la mémoire tampon est spécifiée en tant que SCARD_AUTOALLOCATE, mszCards est convertie en pointeur d’octet et reçoit l’adresse d’un bloc de mémoire contenant la structure à plusieurs chaînes. Ce bloc de mémoire doit être libéré avec SCardFreeMemory.

Valeur de retour

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

Retourner le code	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 les 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 : Appeler cette fonction au sein d’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).
// ...

Note

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.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows XP [applications de bureau uniquement]
serveur minimum pris en charge	Windows Server 2003 [applications de bureau uniquement]
plateforme cible	Windows
d’en-tête	winscard.h
bibliothèque	Winscard.lib
DLL	Winscard.dll