structure OPENCARD_SEARCH_CRITERIAW (winscard.h)

Article
11/20/2024

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;
  LPWSTR         lpstrGroupNames;
  DWORD          nMaxGroupNames;
  LPCGUID        rgguidInterfaces;
  DWORD          cguidInterfaces;
  LPWSTR         lpstrCardNames;
  DWORD          nMaxCardNames;
  LPOCNCHKPROC   lpfnCheck;
  LPOCNCONNPROCW lpfnConnect;
  LPOCNDSCPROC   lpfnDisconnect;
  LPVOID         pvUserData;
  DWORD          dwShareMode;
  DWORD          dwPreferredProtocols;
} OPENCARD_SEARCH_CRITERIAW, *POPENCARD_SEARCH_CRITERIAW, *LPOPENCARD_SEARCH_CRITERIAW;

Membres

dwStructSize

Longueur, en octets, de la structure. Ne doit pas être 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 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.

rgguidInterfaces

Réservé pour une utilisation ultérieure. Tableau de GUID qui identifie les interfaces requises. Définissez ce membre sur NULL.

cguidInterfaces

Réservé pour une utilisation ultérieure. 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 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 caractères (version Unicode) dans la chaîne lpstrGroupNames.

lpfnCheck

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

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

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

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 effectué à SCardConnect qui utilise dwShareMode et dwPreferredProtocols comme paramètre.

dwPreferredProtocols

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

Remarques

Note

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

OPENCARDNAME_EX

SCardUIDlgSelectCard

Partager via