struttura OPENCARD_SEARCH_CRITERIAA (winscard.h)

Articolo
03/04/2024

La struttura OPENCARD_SEARCH_CRITERIA viene utilizzata dalla funzione SCardUIDlgSelectCard per riconoscere le schede che soddisfano i requisiti stabiliti dal chiamante. È tuttavia possibile chiamare SCardUIDlgSelectCard senza usare questa struttura.

Sintassi

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;

Members

dwStructSize

Lunghezza, in byte, della struttura. Non deve essere NULL.

lpstrGroupNames

Puntatore a un buffer contenente stringhe di nomi di gruppo con terminazione Null. L'ultima stringa nel buffer deve essere terminata da due caratteri Null. Ogni stringa è il nome di un gruppo di schede da includere nella ricerca. Se lpstrGroupNames è NULL, viene eseguita la ricerca del gruppo predefinito (Scard$DefaultReaders).

nMaxGroupNames

Numero massimo di byte (versione ANSI) o caratteri (versione Unicode ) nella stringa lpstrGroupNames .

rgguidInterfaces

Riservato per utilizzi futuri. Matrice di GUID che identifica le interfacce necessarie. Impostare questo membro su NULL.

cguidInterfaces

Riservato per utilizzi futuri. Numero di interfacce nella matrice rgguidInterfaces . Impostare questo membro su NULL.

lpstrCardNames

Puntatore a un buffer che contiene stringhe di nomi di schede con terminazione Null. L'ultima stringa nel buffer deve essere terminata da due caratteri Null. Ogni stringa è il nome di una scheda da individuare.

nMaxCardNames

Numero massimo di byte (versione ANSI) o caratteri (versione Unicode) nella stringa lpstrGroupNames .

lpfnCheck

Puntatore alla routine di verifica della scheda del chiamante. Se non è necessaria alcuna verifica della scheda speciale, questo puntatore è NULL. Se la scheda viene rifiutata dalla routine di verifica, viene restituito FALSE e la scheda verrà disconnessa. Se la scheda viene accettata dalla routine di verifica, viene restituito TRUE .

Il prototipo per la routine di controllo è il seguente.

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

Puntatore alla routine di connessione della scheda del chiamante. Se il chiamante deve eseguire un'elaborazione aggiuntiva per connettersi alla scheda, questo puntatore a funzione viene impostato sulla funzione di connessione dell'utente. Se la funzione di connessione ha esito positivo, la scheda viene lasciata connessa e inizializzata e viene restituito l'handle della scheda.

Il prototipo per la routine di connessione è il seguente.

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

Puntatore alla routine di disconnessione della scheda del chiamante.

Il prototipo per la routine di disconnessione è il seguente.

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

Nota Quando si usa lpfnConnect, lpfnCheck e lpfnDisconnect, devono essere presenti tutte e tre le routine di callback. L'uso di questi callback consente di verificare ulteriormente che l'applicazione chiamante abbia trovato la scheda appropriata. Questo è il modo migliore per assicurarsi che sia selezionata la scheda appropriata. Tuttavia, quando si usa un valore diverso da NULL per lpfnCheck, sia lpfnConnect che lpfnDisconnect non devono essere NULL (e deve essere specificato anche pvUserData ) oppure è necessario impostare entrambi dwShareMode e dwPreferredProtocols .

pvUserData

Puntatore void ai dati utente. Questo puntatore viene passato al chiamante nelle routine Connect, Check e Disconnect.

dwShareMode

Se lpfnConnect non è NULL, i membri dwShareMode e dwPreferredProtocols vengono ignorati . Se lpfnConnect è NULL e dwShareMode è diverso da zero, viene effettuata una chiamata interna a SCardConnect che usa dwShareMode e dwPreferredProtocols come parametro.

dwPreferredProtocols

Usato per la connessione interna come descritto in dwShareMode.

Commenti

Nota

L'intestazione winscard.h definisce OPENCARD_SEARCH_CRITERIA come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [solo app desktop]
Server minimo supportato	Windows Server 2003 [solo app desktop]
Intestazione	winscard.h

Vedi anche

OPENCARDNAME_EX

SCardUIDlgSelectCard

Condividi tramite