Fonction SCardStatusA (winscard.h)

Article
08/27/2023

La fonction SCardStatus fournit la status actuelle d’un carte intelligent dans un lecteur. Vous pouvez l’appeler à tout moment après un appel réussi à SCardConnect et avant un appel réussi à SCardDisconnect. Cela n’affecte pas l’état du lecteur ou du pilote de lecteur.

Syntaxe

LONG SCardStatusA(
  [in]                SCARDHANDLE hCard,
  [out]               LPSTR       mszReaderNames,
  [in, out, optional] LPDWORD     pcchReaderLen,
  [out, optional]     LPDWORD     pdwState,
  [out, optional]     LPDWORD     pdwProtocol,
  [out]               LPBYTE      pbAtr,
  [in, out, optional] LPDWORD     pcbAtrLen
);

Paramètres

[in] hCard

Valeur de référence retournée par SCardConnect.

[out] mszReaderNames

Liste des noms d’affichage (chaîne multiple) par lesquels le lecteur actuellement connecté est connu.

[in, out, optional] pcchReaderLen

Lors de l’entrée, indique la longueur de la mémoire tampon szReaderName .

À la sortie, reçoit la longueur réelle (en caractères) de la liste des noms de lecteur, y compris le caractère NULL de fin. Si cette longueur de mémoire tampon est spécifiée en tant que SCARD_AUTOALLOCATE, szReaderName est converti en pointeur vers un pointeur d’octet et reçoit l’adresse d’un bloc de mémoire qui contient la structure à chaînes multiples.

[out, optional] pdwState

État actuel de la carte intelligente dans le lecteur. En cas de réussite, il reçoit l’un des indicateurs d’état suivants.

Valeur	Signification
SCARD_ABSENT	Il n’y a aucune carte dans le lecteur.
SCARD_PRESENT	Il existe un carte dans le lecteur, mais il n’a pas été déplacé en position pour utilisation.
SCARD_SWALLOWED	Il existe un carte dans le lecteur en position d’utilisation. Le carte n’est pas alimenté.
SCARD_POWERED	L’alimentation est fournie au carte, mais le pilote du lecteur ne connaît pas le mode du carte.
SCARD_NEGOTIABLE	Le carte a été réinitialisé et attend les négociations PTS.
SCARD_SPECIFIC	Le carte a été réinitialisé et des protocoles de communication spécifiques ont été établis.

[out, optional] pdwProtocol

Protocole actuel, le cas échéant. La valeur retournée n’est significative que si la valeur de pdwState retournée est SCARD_SPECIFICMODE.

Valeur	Signification
SCARD_PROTOCOL_RAW	Le protocole de transfert brut est en cours d’utilisation.
SCARD_PROTOCOL_T0	Le protocole ISO 7816/3 T=0 est en cours d’utilisation.
SCARD_PROTOCOL_T1	Le protocole T = 1 ISO 7816/3 est en cours d’utilisation.

[out] pbAtr

Pointeur vers une mémoire tampon de 32 octets qui reçoit la chaîne ATR du carte actuellement inséré, si disponible.

[in, out, optional] pcbAtrLen

En entrée, fournit la longueur de la mémoire tampon pbAtr . À la sortie, reçoit le nombre d’octets dans la chaîne ATR (32 octets maximum). Si cette longueur de mémoire tampon est spécifiée en tant que SCARD_AUTOALLOCATE, pbAtr est converti en pointeur vers un pointeur d’octet et reçoit l’adresse d’un bloc de mémoire qui contient la structure à chaînes multiples.

Valeur retournée

Si la fonction fournit correctement la status actuelle d’un carte intelligent dans un lecteur, la valeur de retour est SCARD_S_SUCCESS.

Si la fonction échoue, elle retourne un code d'erreur. Pour plus d’informations, consultez Valeurs de retour de carte à puce.

Remarques

La fonction SCardStatus est une fonction d’accès carte et lecteur intelligente. Pour plus d’informations sur d’autres fonctions d’accès, consultez Smart Card and Reader Access Functions.

Exemples

L’exemple suivant montre comment déterminer l’état du carte intelligent.

WCHAR           szReader[200];
DWORD           cch = 200;
BYTE            bAttr[32];
DWORD           cByte = 32;
DWORD           dwState, dwProtocol;
LONG            lReturn;

// Determine the status.
// hCardHandle was set by an earlier call to SCardConnect.
lReturn = SCardStatus(hCardHandle,
                      szReader,
                      &cch,
                      &dwState,
                      &dwProtocol,
                      (LPBYTE)&bAttr,
                      &cByte); 

if ( SCARD_S_SUCCESS != lReturn )
{
    printf("Failed SCardStatus\n");
    exit(1);     // or other appropriate action
}

// Examine retrieved status elements.
// Look at the reader name and card state.
printf("%S\n", szReader );
switch ( dwState )
{
    case SCARD_ABSENT:
        printf("Card absent.\n");
        break;
    case SCARD_PRESENT:
        printf("Card present.\n");
        break;
    case SCARD_SWALLOWED:
        printf("Card swallowed.\n");
        break;
    case SCARD_POWERED:
        printf("Card has power.\n");
        break;
    case SCARD_NEGOTIABLE:
        printf("Card reset and waiting PTS negotiation.\n");
        break;
    case SCARD_SPECIFIC:
        printf("Card has specific communication protocols set.\n");
        break;
    default:
        printf("Unknown or unexpected card state.\n");
        break;
}

Notes

L’en-tête winscard.h définit SCardStatus comme un 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.

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

Voir aussi

SCardConnect

SCardDisconnect

Partager via