STRUCTURE OPENCARDNAMEW (winscard.h)

Article
03/06/2024

La structure OPENCARDNAME contient les informations que la fonction GetOpenCardName utilise pour initialiser une carte intelligente boîte de dialogue Sélectionner une carte. Il est recommandé d’appeler SCardUIDlgSelectCard avec OPENCARDNAME_EX plutôt que d’appeler GetOpenCardName avec OPENCARDNAME. OPENCARDNAME est fourni pour la compatibilité descendante.

Syntaxe

typedef struct {
  DWORD          dwStructSize;
  HWND           hwndOwner;
  SCARDCONTEXT   hSCardContext;
  LPWSTR         lpstrGroupNames;
  DWORD          nMaxGroupNames;
  LPWSTR         lpstrCardNames;
  DWORD          nMaxCardNames;
  LPCGUID        rgguidInterfaces;
  DWORD          cguidInterfaces;
  LPWSTR         lpstrRdr;
  DWORD          nMaxRdr;
  LPWSTR         lpstrCard;
  DWORD          nMaxCard;
  LPCWSTR        lpstrTitle;
  DWORD          dwFlags;
  LPVOID         pvUserData;
  DWORD          dwShareMode;
  DWORD          dwPreferredProtocols;
  DWORD          dwActiveProtocol;
  LPOCNCONNPROCW lpfnConnect;
  LPOCNCHKPROC   lpfnCheck;
  LPOCNDSCPROC   lpfnDisconnect;
  SCARDHANDLE    hCardHandle;
} OPENCARDNAMEW, *POPENCARDNAMEW, *LPOPENCARDNAMEW;

Membres

dwStructSize

Spécifie la longueur, en octets, de la structure. Ce membre ne doit pas avoir la valeur NULL.

hwndOwner

Fenêtre qui possède la boîte de dialogue. Ce membre peut être n’importe quel handle de fenêtre valide, ou il peut être NULL pour la valeur par défaut du bureau.

hSCardContext

Contexte utilisé pour la communication avec le gestionnaire smart carte resource. Appelez SCardEstablishContext pour définir le contexte resource manager et SCardReleaseContext pour le libérer. Ce membre ne doit pas avoir la valeur NULL.

lpstrGroupNames

Pointeur vers une mémoire tampon qui contient des chaînes de nom de groupe terminées par null. La dernière chaîne de la mémoire tampon doit être terminée par deux caractères null. Chaque chaîne est le nom d’un groupe de cartes à inclure dans la recherche. Si lpstrGroupNames a la valeur NULL, le groupe par défaut (Scard$DefaultReaders) est recherché.

nMaxGroupNames

Nombre maximal d’octets (version ANSI) ou de caractères (version Unicode ) dans la chaîne lpstrGroupNames .

lpstrCardNames

Pointeur vers une mémoire tampon qui contient des chaînes de nom de carte terminées par null. La dernière chaîne de la mémoire tampon doit être terminée par deux caractères null. Chaque chaîne est le nom d’un carte qui doit être localisé.

nMaxCardNames

Nombre maximal d’octets (version ANSI) ou de caractères (version Unicode ) dans la chaîne lpstrCardNames .

rgguidInterfaces

Réservé pour un usage futur. Défini sur NULL. Tableau de GUID qui identifient les interfaces requises.

cguidInterfaces

Réservé à une utilisation à terme. Défini sur NULL. Nombre d’interfaces dans le tableau rgguidInterfaces .

lpstrRdr

Si le carte se trouve, la mémoire tampon lpstrRdr contient le nom du lecteur qui contient le carte situé. La mémoire tampon doit comporter au moins 256 caractères.

nMaxRdr

Taille, en octets (version ANSI) ou caractères (version Unicode ), de la mémoire tampon pointée vers lpstrRdr. Si la mémoire tampon est trop petite pour contenir les informations du lecteur, GetOpenCardName retourne SCARD_E_NO_MEMORY et la taille requise de la mémoire tampon pointée vers lpstrRdr.

lpstrCard

Si le carte se trouve, la mémoire tampon lpstrCard contient le nom du carte situé. La mémoire tampon doit comporter au moins 256 caractères.

nMaxCard

Taille, en octets (version ANSI) ou caractères (version Unicode ), de la mémoire tampon pointée vers lpstrCard. Si la mémoire tampon est trop petite pour contenir les informations carte, GetOpenCardName retourne SCARD_E_NO_MEMORY et la taille requise de la mémoire tampon dans nMaxCard.

lpstrTitle

Pointeur vers une chaîne à placer dans la barre de titre de la boîte de dialogue. Si ce membre a la valeur NULL, le système utilise le titre par défaut « Sélectionner la carte : ».

dwFlags

Ensemble d’indicateurs de bits que vous pouvez utiliser pour initialiser la boîte de dialogue. Lorsque la boîte de dialogue retourne, elle définit ces indicateurs pour indiquer l’entrée de l’utilisateur. Ce membre peut être une combinaison des indicateurs suivants.

Valeur	Signification
SC_DLG_MINIMAL_UI	Affiche la boîte de dialogue uniquement si le carte recherché par l’application appelante ne se trouve pas et peut être utilisé dans un lecteur. Cela permet de trouver le carte, de se connecter (via le mécanisme de boîte de dialogue interne ou les fonctions de rappel utilisateur) et de retourner à l’application appelante.
SC_DLG_NO_UI	Ne pas afficher l’interface utilisateursélectionner une carte, quel que soit le résultat de la recherche.
SC_DLG_FORCE_UI	Forcer l’affichage de l’interface utilisateur Sélectionner une carte , quel que soit le résultat de la recherche.

pvUserData

Pointeur void vers les données utilisateur. Ce pointeur est renvoyé à l’appelant sur les routines Se connecter, Vérifier et Déconnecter.

dwShareMode

Si lpfnConnect n’a pas la valeur NULL, les membres dwShareMode et dwPreferredProtocols sont ignorés.

Si lpfnConnect a la valeur NULL et que dwShareMode est différent de zéro, un appel interne est effectué à SCardConnect qui utilise dwShareMode et dwPreferredProtocols comme paramètres dwShareMode et dwPreferredProtocols . Si la connexion réussit, hCardHandle est défini sur le handle retourné par hSCardConnect.

Si lpfnConnect a la valeur NULL et que dwShareMode a la valeur zéro, la boîte de dialogue renvoie hCardHandle comme NULL.

dwPreferredProtocols

Utilisé pour la connexion interne comme décrit dans dwShareMode.

dwActiveProtocol

Retourne le protocole réel utilisé lorsque la boîte de dialogue établit une connexion à un carte.

lpfnConnect

Pointeur vers la routine de connexion carte de l’appelant. Si l’appelant doit effectuer un traitement supplémentaire pour se connecter au carte, ce pointeur de fonction est défini sur la fonction de connexion pour l’utilisateur. Si la fonction de connexion réussit, le carte reste connecté et initialisé, et le carte handle est retourné.

Le prototype de la routine de connexion est le suivant.

Connect(
  hSCardContext, // the card context passed in the parameter block
  szReader,      // the name of the reader
  mszCards,      // multiple string that contains the 
                 //    possible card names in the reader
  pvUserData     // pointer to user data passed in parameter block
);

lpfnCheck

Pointeur vers le carte routine de vérification de l’appelant. Si aucune vérification carte spéciale n’est requise, ce pointeur a la valeur NULL.

Si le carte est rejeté par la routine de vérification, FALSE est retourné et le carte est déconnecté, comme indiqué par lpfnDisconnect.

Si le carte est accepté par la routine de vérification, TRUE est retourné. Lorsque l’utilisateur accepte le carte, toutes les autres cartes actuellement connectées sont déconnectées, comme indiqué par lpfnDisconnect, et cette carte est retournée en tant que carte située. Le carte situé reste connecté.

Le prototype de la routine case activée est le suivant.

Check(
  hSCardContext, // the card context passed in the parameter block
  hCard,         // card handle
  pvUserData     // pointer to user data passed in the parameter block
);

lpfnDisconnect

Pointeur vers la carte routine de déconnexion de l’appelant.

Le prototype de la routine de déconnexion est le suivant.

Disconnect(
  hSCardContext, // the card context passed in the parameter block
  hCard,         // card handle
  pvUserData     // pointer to user data passed in the parameter block
);

Note Lorsque vous utilisez lpfnConnect, lpfnCheck et lpfnDisconnect, les trois procédures de rappel doivent être présentes. L’utilisation de ces rappels permet de vérifier davantage que l’application appelante a trouvé le carte approprié. Il s’agit de la meilleure façon de vous assurer que le carte approprié est sélectionné.

hCardHandle

Handle du carte connecté (via une connexion de boîte de dialogue interne ou un rappel lpfnConnect).

Remarques

Notes

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

Voir aussi

GetOpenCardName

SCardConnect

SCardEstablishContext

SCardReleaseContext

SCardUIDlgSelectCard

Partager via