structure OPENCARD_SEARCH_CRITERIAA (winscard.h)

Article
08/27/2023

La structure OPENCARD_SEARCH_CRITERIA est utilisée par la fonction SCardUIDlgSelectCard afin de reconnaître les cartes qui répondent aux exigences définies par l’appelant. Vous pouvez toutefois appeler SCardUIDlgSelectCard sans utiliser cette structure.

Syntaxe

typedef struct {
  DWORD          dwStructSize;
  LPSTR          lpstrGroupNames;
  DWORD          nMaxGroupNames;
  LPCGUID        rgguidInterfaces;
  DWORD          cguidInterfaces;
  LPSTR          lpstrCardNames;
  DWORD          nMaxCardNames;
  LPOCNCHKPROC   lpfnCheck;
  LPOCNCONNPROCA lpfnConnect;
  LPOCNDSCPROC   lpfnDisconnect;
  LPVOID         pvUserData;
  DWORD          dwShareMode;
  DWORD          dwPreferredProtocols;
} OPENCARD_SEARCH_CRITERIAA, *POPENCARD_SEARCH_CRITERIAA, *LPOPENCARD_SEARCH_CRITERIAA;

Membres

dwStructSize

Longueur, en octets, de la structure. Ne doit pas avoir la valeur NULL.

lpstrGroupNames

Pointeur vers une mémoire tampon contenant 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 .

rgguidInterfaces

Réservé pour un usage futur. Tableau de GUID qui identifie les interfaces requises. Définissez ce membre sur NULL.

cguidInterfaces

Réservé pour un usage futur. Nombre d’interfaces dans le tableau rgguidInterfaces . Définissez ce membre sur NULL.

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 lpstrGroupNames .

lpfnCheck

Pointeur vers la routine de vérification carte 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é. Si le carte est accepté par la routine de vérification, TRUE est retourné.

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

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

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 de 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
);

lpfnDisconnect

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

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é. Toutefois, lors de l’utilisation d’une valeur qui n’est pas NULL pour lpfnCheck, lpfnConnect et lpfnDisconnect ne doivent pas avoir la valeur NULL (et pvUserData doivent également être fournis), soit dwShareMode et dwPreferredProtocols doivent être définis.

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ètre.

dwPreferredProtocols

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

Remarques

Notes

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

OPENCARDNAME_EX

SCardUIDlgSelectCard

Partager via