Fonction SCardConnectA (winscard.h)

Article
08/27/2023

La fonction SCardConnect établit une connexion (à l’aide d’un contexte resource manager spécifique) entre l’application appelante et un carte intelligent contenu par un lecteur spécifique. Si aucune carte n’existe dans le lecteur spécifié, une erreur est retournée.

Syntaxe

LONG SCardConnectA(
  [in]  SCARDCONTEXT  hContext,
  [in]  LPCSTR        szReader,
  [in]  DWORD         dwShareMode,
  [in]  DWORD         dwPreferredProtocols,
  [out] LPSCARDHANDLE phCard,
  [out] LPDWORD       pdwActiveProtocol
);

Paramètres

[in] hContext

Handle qui identifie le contexte resource manager. Le contexte resource manager est défini par un appel précédent à SCardEstablishContext.

[in] szReader

Nom du lecteur qui contient le carte cible.

[in] dwShareMode

Indicateur qui indique si d’autres applications peuvent former des connexions à l’carte.

Valeur	Signification
SCARD_SHARE_SHARED	Cette application est prête à partager le carte avec d’autres applications.
SCARD_SHARE_EXCLUSIVE	Cette application n’est pas prête à partager le carte avec d’autres applications.
SCARD_SHARE_DIRECT	Cette application alloue le lecteur pour son utilisation privée et le contrôlera directement. Aucune autre application n’y est autorisée.

[in] dwPreferredProtocols

Masque de bits des protocoles acceptables pour la connexion. Les valeurs possibles peuvent être combinées à l’opération OR .

Valeur	Signification
SCARD_PROTOCOL_T0	T=0 est un protocole acceptable.
SCARD_PROTOCOL_T1	T=1 est un protocole acceptable.
0	Ce paramètre peut être égal à zéro uniquement si dwShareMode est défini sur SCARD_SHARE_DIRECT. Dans ce cas, aucune négociation de protocole n’est effectuée par les pilotes tant qu’une directive de contrôle IOCTL_SMARTCARD_SET_PROTOCOL n’est pas envoyée avec SCardControl.

[out] phCard

Handle qui identifie la connexion au carte intelligent dans le lecteur désigné.

[out] pdwActiveProtocol

Indicateur qui indique le protocole actif établi.

Valeur	Signification
SCARD_PROTOCOL_T0	T=0 est le protocole actif.
SCARD_PROTOCOL_T1	T=1 est le protocole actif.
SCARD_PROTOCOL_UNDEFINED	SCARD_SHARE_DIRECT a été spécifié, de sorte qu’aucune négociation de protocole n’a eu lieu. Il est possible qu’il n’y ait aucune carte dans le lecteur.

Valeur retournée

Cette fonction retourne des valeurs différentes selon qu’elle réussit ou échoue.

Code de retour	Description
Success	SCARD_S_SUCCESS.
Échec	Code d'erreur. Pour plus d’informations, consultez Valeurs de retour de carte à puce.
SCARD_E_NOT_READY	Le lecteur n’a pas pu se connecter au carte.

Remarques

La fonction SCardConnect est une fonction d’accès carte et lecteur intelligente. Pour plus d’informations sur d’autres fonctions d’accès, consultez Fonctions d’accès par carte à puce et lecteur.

Exemples

L’exemple suivant crée une connexion à un lecteur. L’exemple suppose que hContext est un handle valide de type SCARDCONTEXT reçu d’un appel précédent à SCardEstablishContext.

SCARDHANDLE     hCardHandle;
LONG            lReturn;
DWORD           dwAP;

lReturn = SCardConnect( hContext, 
                        (LPCTSTR)"Rainbow Technologies SCR3531 0",
                        SCARD_SHARE_SHARED,
                        SCARD_PROTOCOL_T0 | SCARD_PROTOCOL_T1,
                        &hCardHandle,
                        &dwAP );
if ( SCARD_S_SUCCESS != lReturn )
{
    printf("Failed SCardConnect\n");
    exit(1);  // Or other appropriate action.
}

// Use the connection.
// Display the active protocol.
switch ( dwAP )
{
    case SCARD_PROTOCOL_T0:
        printf("Active protocol T0\n"); 
        break;

    case SCARD_PROTOCOL_T1:
        printf("Active protocol T1\n"); 
        break;

    case SCARD_PROTOCOL_UNDEFINED:
    default:
        printf("Active protocol unnegotiated or unknown\n"); 
        break;
}

// Remember to disconnect (by calling SCardDisconnect).
// ...

Notes

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