SCardListCardsA, fonction (winscard.h)
La fonction
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 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 |
---|---|
|
SCARD_S_SUCCESS. |
|
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
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 |