SCardListReadersA, fonction (winscard.h)
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).
[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 |
---|---|
|
SCARD_S_SUCCESS |
|
SCARD_E_NO_READERS_AVAILABLE |
|
SCARD_E_READER_UNAVAILABLE |
|
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 |