SCardListReadersA, fonction (winscard.h)
La fonction SCardListReaders
L’appelant fournit une liste de groupes de lecteurs et reçoit la liste des lecteurs dans les groupes nommés. Les noms de groupes non reconnus sont ignorés. Cette fonction retourne uniquement les lecteurs dans les groupes nommés 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 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 lecteurs n’est limitée à aucun contexte.
[in, optional] mszGroups
Noms des groupes de lecteurs définis pour 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 de cartes 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 pcchReaderset 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 multi-chaîne, y compris tous les caractères de fin null. Si la longueur de la mémoire tampon est spécifiée comme SCARD_AUTOALLOCATE, mszReaders est convertie en pointeur 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/la valeur | 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
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;
}
Note
L’en-tête winscard.h définit SCardListReaders 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 |