SCardStatusW, fonction (winscard.h)

Article
11/20/2024

La fonction SCardStatus fournit l’état actuel d’un de carte à puce dans unlecteur . Vous pouvez l’appeler à tout moment après un appel réussi à SCardConnect et avant d’appeler correctement SCardDisconnect. Il n’affecte pas l’état du lecteur ou du pilote de lecteur .

Syntaxe

LONG SCardStatusW(
  [in]                SCARDHANDLE hCard,
  [out]               LPWSTR      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 lesquelles le lecteur actuellement connecté est connu.

[in, out, optional] pcchReaderLen

En entrée, fournit la longueur de la mémoire tampon szReaderName.

En sortie, reçoit la longueur réelle (en caractères) de la liste de noms du lecteur, y compris le caractère de fin NULL. Si cette longueur de mémoire tampon est spécifiée comme SCARD_AUTOALLOCATE, szReaderName est convertie en pointeur d’octet et reçoit l’adresse d’un bloc de mémoire contenant la structure à plusieurs chaînes.

[out, optional] pdwState

État actuel de la carte à puce 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 pas de carte dans le lecteur.
SCARD_PRESENT	Il existe une carte dans le lecteur, mais elle n’a pas été déplacée en position d’utilisation.
SCARD_SWALLOWED	Il existe une carte dans le lecteur en position d’utilisation. La carte n’est pas alimentée.
SCARD_POWERED	La puissance est fournie à la carte, mais le pilote du lecteur n’est pas conscient du mode de la carte.
SCARD_NEGOTIABLE	La carte a été réinitialisée et attend la négociation PTS.
SCARD_SPECIFIC	La carte a été réinitialisée 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 retournée de pdwState est SCARD_SPECIFIC.

Valeur	Signification
SCARD_PROTOCOL_RAW	Le protocole Raw Transfer est en cours d’utilisation.
SCARD_PROTOCOL_T0	Le protocole ISO 7816/3 T=0 est utilisé.
SCARD_PROTOCOL_T1	Le protocole ISO 7816/3 T=1 est utilisé.

[out] pbAtr

Pointeur vers une mémoire tampon de 32 octets qui reçoit la chaîne ATR de la carte actuellement insérée, le cas échéant.

[in, out, optional] pcbAtrLen

Lors de l’entrée, fournit la longueur de la mémoire tampon pbAtr. En 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 comme SCARD_AUTOALLOCATE, pbAtr est convertie en pointeur d’octet et reçoit l’adresse d’un bloc de mémoire contenant la structure à plusieurs chaînes.

Valeur de retour

Si la fonction fournit correctement l’état actuel d’une carte à puce 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 de carte à puce et fonction d’accès lecteur. Pour plus d’informations sur les autres fonctions d’accès, consultez fonctions d’accès à puce et lecteur.

Exemples

L’exemple suivant montre comment déterminer l’état de la carte à puce.

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;
}

Note

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

Voir aussi

SCardConnect

SCardDisconnect

Partager via