SCardListReadersA, fonction (winscard.h)

Article
08/27/2023

La fonction SCardListReaders fournit la liste des lecteurs au sein d’un ensemble de groupes de lecteurs nommés, éliminant ainsi les doublons.

L’appelant fournit une liste de groupes de lecteurs et reçoit la liste des lecteurs au sein des groupes nommés. Les noms de groupes non reconnus sont ignorés. Cette fonction retourne uniquement les lecteurs au sein des groupes nommés qui sont actuellement attachés au système et disponibles pour une utilisation.

Syntaxe

LONG SCardListReadersA(
  [in]           SCARDCONTEXT hContext,
  [in, optional] LPCSTR       mszGroups,
  [out]          LPSTR        mszReaders,
  [in, out]      LPDWORD      pcchReaders
);

Paramètres

[in] hContext

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

Si ce paramètre est défini sur NULL, la recherche de lecteurs n’est limitée à aucun contexte.

[in, optional] mszGroups

Noms des groupes de lecteurs définis sur le système, sous forme de chaînes multiples. Utilisez une valeur NULL pour répertorier tous les lecteurs du système (autrement dit, le groupe SCard$AllReaders).

Valeur	Signification
SCARD_ALL_READERS TEXT(« SCard$AllReaders\000 »)	Groupe utilisé lorsqu’aucun nom de groupe n’est fourni lors de la liste des lecteurs. Retourne une liste de tous les lecteurs, quel que soit le groupe ou les groupes dans qui se trouvent les lecteurs.
SCARD_DEFAULT_READERS TEXT(« SCard$DefaultReaders\000 »)	Groupe par défaut auquel tous les lecteurs sont ajoutés lors de leur introduction dans le système.
SCARD_LOCAL_READERS TEXT(« SCard$LocalReaders\000 »)	Valeur héritée inutilisée. Il s’agit d’un groupe géré en interne qui ne peut pas être modifié à l’aide des API de groupe de lecteurs. Il est destiné à être utilisé pour l’énumération uniquement.
SCARD_SYSTEM_READERS TEXT(« SCard$SystemReaders\000 »)	Valeur héritée inutilisée. Il s’agit d’un groupe géré en interne qui ne peut pas être modifié à l’aide des API de groupe de lecteurs. Il est destiné à être utilisé pour l’énumération uniquement.

[out] mszReaders

Chaîne multiple qui répertorie les lecteurs carte dans les groupes de lecteurs fournis. Si cette valeur est NULL, SCardListReaders ignore la longueur de la mémoire tampon fournie dans pcchReaders, écrit la longueur de la mémoire tampon qui aurait été retournée si ce paramètre n’avait pas été NULL pour pcchReaders et retourne un code de réussite.

[in, out] pcchReaders

Longueur de la mémoire tampon mszReaders en caractères. Ce paramètre 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, mszReaders est converti en pointeur vers un pointeur d’octets 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 retournée

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

Code/valeur de retour	Description
Success 0 (0x0)	SCARD_S_SUCCESS
Le groupe ne contient aucun lecteur 2148532270 (0x8010002E)	SCARD_E_NO_READERS_AVAILABLE
Le lecteur spécifié n’est actuellement pas disponible pour une utilisation 2148532247 (0x80100017)	SCARD_E_READER_UNAVAILABLE
Autres	Code d'erreur. Pour plus d’informations, consultez Valeurs de retour de carte à puce.

Remarques

La fonction SCardListReaders 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.

Exemples

L’exemple suivant montre la liste des lecteurs.

LPTSTR          pmszReaders = NULL;
LPTSTR          pReader;
LONG            lReturn, lReturn2;
DWORD           cch = SCARD_AUTOALLOCATE;

// Retrieve the list the readers.
// hSC was set by a previous call to SCardEstablishContext.
lReturn = SCardListReaders(hSC,
                           NULL,
                           (LPTSTR)&pmszReaders,
                           &cch );
switch( lReturn )
{
    case SCARD_E_NO_READERS_AVAILABLE:
        printf("Reader is not in groups.\n");
        // Take appropriate action.
        // ...
        break;

    case SCARD_S_SUCCESS:
        // Do something with the multi string of readers.
        // Output the values.
        // A double-null terminates the list of values.
        pReader = pmszReaders;
        while ( '\0' != *pReader )
        {
            // Display the value.
            printf("Reader: %S\n", pReader );
            // Advance to the next value.
            pReader = pReader + wcslen((wchar_t *)pReader) + 1;
        }
        // Free the memory.
        lReturn2 = SCardFreeMemory( hSC,
                                   pmszReaders );
        if ( SCARD_S_SUCCESS != lReturn2 )
            printf("Failed SCardFreeMemory\n");
        break;

default:
        printf("Failed SCardListReaders\n");
        // Take appropriate action.
        // ...
        break;
}

Notes

L’en-tête winscard.h définit SCardListReaders en tant qu’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. La combinaison 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