Partager via


STRUCTURE OPENCARDNAMEA (winscard.h)

La structure OPENCARDNAME contient les informations que la fonction GetOpenCardName utilise pour initialiser une carte à puce boîte de dialogue Sélectionner une carte. L’appel SCardUIDlgSelectCard avec OPENCARDNAME_EX est recommandé pour appeler GetOpenCardName avec OPENCARDNAME. OPENCARDNAME est fourni pour la compatibilité descendante.

Syntaxe

typedef struct {
  DWORD          dwStructSize;
  HWND           hwndOwner;
  SCARDCONTEXT   hSCardContext;
  LPSTR          lpstrGroupNames;
  DWORD          nMaxGroupNames;
  LPSTR          lpstrCardNames;
  DWORD          nMaxCardNames;
  LPCGUID        rgguidInterfaces;
  DWORD          cguidInterfaces;
  LPSTR          lpstrRdr;
  DWORD          nMaxRdr;
  LPSTR          lpstrCard;
  DWORD          nMaxCard;
  LPCSTR         lpstrTitle;
  DWORD          dwFlags;
  LPVOID         pvUserData;
  DWORD          dwShareMode;
  DWORD          dwPreferredProtocols;
  DWORD          dwActiveProtocol;
  LPOCNCONNPROCA lpfnConnect;
  LPOCNCHKPROC   lpfnCheck;
  LPOCNDSCPROC   lpfnDisconnect;
  SCARDHANDLE    hCardHandle;
} OPENCARDNAMEA, *POPENCARDNAMEA, *LPOPENCARDNAMEA;

Membres

dwStructSize

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

hwndOwner

Fenêtre propriétaire 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 la carte à puce Resource Manager. Appelez SCardEstablishContext pour définir le contexte du gestionnaire de ressources et SCardReleaseContext le libérer. Ce membre ne doit pas être 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 arrêtée par deux caractères Null. Chaque chaîne est le nom d’un groupe de cartes à inclure dans la recherche. Si lpstrGroupNames est 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 arrêtée par deux caractères Null. Chaque chaîne est le nom d’une carte à localiser.

nMaxCardNames

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

rgguidInterfaces

Réservé pour une utilisation ultérieure. Défini sur NULL . Tableau de GUID qui identifient les interfaces requises.

cguidInterfaces

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

lpstrRdr

Si la carte se trouve, la mémoire tampon lpstrRdr contient le nom du lecteur qui contient la carte située. 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 par 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 par lpstrRdr.

lpstrCard

Si la carte se trouve, la mémoire tampon lpstrCard contient le nom de la carte située. 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 par lpstrCard. Si la mémoire tampon est trop petite pour contenir les informations de 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 est NULL, le système utilise le titre par défaut « Sélectionner une 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 la carte recherchée par l’application appelante n’est pas située et disponible pour une utilisation dans un lecteur. Cela permet de trouver la carte, de se connecter (via le mécanisme de boîte de dialogue interne ou les fonctions de rappel utilisateur) et renvoyées à l’application appelante.
SC_DLG_NO_UI
Forcez l’affichage de la Sélectionner une carteinterface utilisateur (interface utilisateur), quel que soit le résultat de la recherche.
SC_DLG_FORCE_UI
Forcer l’affichage de la Sélectionner une carte interface utilisateur, quel que soit le résultat de la recherche.

pvUserData

Pointeur void vers les données utilisateur. Ce pointeur est repassé à l’appelant sur les routines Connexion, Vérification et Déconnexion.

dwShareMode

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

Si lpfnConnect est NULL et dwShareMode n’est pas zéro, un appel interne est ensuite effectué pour SCardConnect qui utilise dwShareMode et dwPreferredProtocols en tant que dwShareMode et paramètres dwPreferredProtocols. Si la connexion réussit, hCardHandle est défini sur le handle retourné par hSCardConnect.

Si lpfnConnect est NULL et dwShareMode est 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 en cours d’utilisation lorsque la boîte de dialogue établit une connexion à une carte.

lpfnConnect

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

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 la carte vérifie la routine de l’appelant. Si aucune vérification de carte spéciale n’est requise, ce pointeur est NULL.

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

Si la carte est acceptée par la routine de vérification, TRUE est retournée. Lorsque l’utilisateur accepte la 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. La carte située reste connectée.

Le prototype de la routine de vérification 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 routine de déconnexion de la carte 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
);

Remarque Lors de l’utilisation lpfnConnect, lpfnChecket lpfnDisconnect, les trois procédures de rappel doivent être présentes. L’utilisation de ces rappels permet une vérification supplémentaire que l’application appelante a trouvé la carte appropriée. Il s’agit du meilleur moyen de s’assurer que la carte appropriée est sélectionnée.
 

hCardHandle

Handle de la carte connectée (via une boîte de dialogue interne se connecter ou un rappel lpfnConnect).

Remarques

Note

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

Voir aussi

GetOpenCardName

SCardConnect

SCardEstablishContext

SCardReleaseContext

SCardUIDlgSelectCard