SCardConnectW, fonction (winscard.h)

Article
11/20/2024

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

Syntaxe

LONG SCardConnectW(
  [in]  SCARDCONTEXT  hContext,
  [in]  LPCWSTR       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 la carte cible.

[in] dwShareMode

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

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

[in] dwPreferredProtocols

Masque de bits des protocoles acceptables pour la connexion. Les valeurs possibles peuvent être combinées avec 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 jusqu’à ce qu’une directive de contrôle IOCTL_SMARTCARD_SET_PROTOCOL soit envoyée avec SCardControl.

[out] phCard

Handle qui identifie la connexion au carte à puce 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 pas de carte dans le lecteur.

Valeur de retour

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

Retourner le code	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 à la carte.

Remarques

La fonction SCardConnect 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 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).
// ...

Note

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

SCardControl

SCardDisconnect

SCardEstablishContext

SCardReconnect

Partager via