structure OPENCARDNAME_EXA (winscard.h)

Article
07/16/2024

La structure OPENCARDNAME_EX contient les informations que la fonction SCardUIDlgSelect Card utilise pour initialiser une carte à puce boîte de dialogue Sélectionner une carte.

Syntaxe

typedef struct {
  DWORD                      dwStructSize;
  SCARDCONTEXT               hSCardContext;
  HWND                       hwndOwner;
  DWORD                      dwFlags;
  LPCSTR                     lpstrTitle;
  LPCSTR                     lpstrSearchDesc;
  HICON                      hIcon;
  POPENCARD_SEARCH_CRITERIAA pOpenCardSearchCriteria;
  LPOCNCONNPROCA             lpfnConnect;
  LPVOID                     pvUserData;
  DWORD                      dwShareMode;
  DWORD                      dwPreferredProtocols;
  LPSTR                      lpstrRdr;
  DWORD                      nMaxRdr;
  LPSTR                      lpstrCard;
  DWORD                      nMaxCard;
  DWORD                      dwActiveProtocol;
  SCARDHANDLE                hCardHandle;
} OPENCARDNAME_EXA, *POPENCARDNAME_EXA, *LPOPENCARDNAME_EXA;

Membres

dwStructSize

Longueur, en octets, de la structure. La valeur de ce membre ne doit pas être NULL .

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. La valeur de 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.

dwFlags

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

Valeur	Signification
SC_DLG_MINIMAL_UI	Affichez 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.

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 : ».

lpstrSearchDesc

Pointeur vers une chaîne à afficher à l’utilisateur en tant qu’invite pour insérer la carte à puce . Si ce membre est NULL, le système utilise le texte par défaut « Veuillez insérer une carte à puce ».

hIcon

Handle vers une icône (32 x 32 pixels). Vous pouvez spécifier une icône spécifique au fournisseur à afficher dans la boîte de dialogue. Si cette valeur est NULL, une icône générique de lecteur de carte à puce chargée s’affiche.

pOpenCardSearchCriteria

Pointeur vers la structure OPENCARD_SEARCH_CRITERIA à utiliser, ou NULL, si celle-ci n’est pas utilisée.

lpfnConnect

Pointeur vers la routine de connexion de la 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 de 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
);

pvUserData

Pointeur void vers les données utilisateur. Ce pointeur est repassé à l’appelant sur la routine Connect.

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 effectué pour SCardConnect qui utilise dwShareMode et dwPreferredProtocols comme dwShareMode et paramètres dwPreferredProtocols. Si la connexion réussit, hCardHandle est défini sur le handle retourné par SCardConnect. Si lpfnConnect est NULL et dwShareMode est égal à zéro, hCardHandle est défini sur NULL.

dwPreferredProtocols

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

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 de lecteur, SCardUIDlgSelectCard 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, SCardUIDlgSelectCard retourne SCARD_E_NO_MEMORY et la taille requise de la mémoire tampon dans nMaxCard.

dwActiveProtocol

Protocole réel en cours d’utilisation lorsque la boîte de dialogue établit une connexion à une carte.

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_EX en tant qu’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

SCardConnect

SCardEstablishContext

SCardReleaseContext

SCardUIDlgSelectCard

valeurs de retour de carte à puce

Partager via