Struttura OPENCARDNAMEA (winscard.h)

Articolo
07/16/2024

La struttura OPENCARDNAME contiene le informazioni utilizzate dalla funzione GetOpenCardName per inizializzare una smart card finestra di dialogo Seleziona scheda. È consigliabile chiamare SCardUIDlgSelectCard con OPENCARDNAME_EX chiamando GetOpenCardName con OPENCARDNAME. OPENCARDNAME è disponibile per la compatibilità con le versioni precedenti.

Sintassi

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;

Membri

dwStructSize

Specifica la lunghezza, espressa in byte, della struttura. Questo membro non deve essere NULL.

hwndOwner

Finestra proprietaria della finestra di dialogo. Questo membro può essere qualsiasi handle di finestra valido oppure può essere null per impostazione predefinita desktop.

hSCardContext

Contesto usato per la comunicazione con la smart card resource manager. Chiamare SCardEstablishContext per impostare il del contesto di gestione risorse e SCardReleaseContext per rilasciarlo. Questo membro non deve essere NULL.

lpstrGroupNames

Puntatore a un buffer che contiene 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 lpstrGroupName s.

lpstrCardNames

Puntatore a un buffer che contiene stringhe di nomi di scheda 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 lpstrCardNames.

rgguidInterfaces

Riservato per uso futuro. Impostare su NULL. Matrice di GUID che identificano le interfacce necessarie.

cguidInterfaces

Riservato per futures use. Impostare su NULL. Numero di interfacce nella matrice rgguidInterfaces.

lpstrRdr

Se la scheda si trova, il buffer lpstrRdr contiene il nome del lettore che contiene la scheda individuata. Il buffer deve contenere almeno 256 caratteri.

nMaxRdr

Dimensioni, in byte (versione ANSI) o caratteri (versione unicode), del buffer a cui punta lpstrRdr. Se il buffer è troppo piccolo per contenere le informazioni sul lettore, GetOpenCardName restituisce SCARD_E_NO_MEMORY e le dimensioni necessarie del buffer a cui punta lpstrRdr.

lpstrCard

Se la scheda si trova, il buffer lpstrCard contiene il nome della scheda individuata. Il buffer deve contenere almeno 256 caratteri.

nMaxCard

Dimensioni, in byte (versione ANSI) o caratteri (versione unicode), del buffer a cui punta lpstrCard. Se il buffer è troppo piccolo per contenere le informazioni sulla scheda, GetOpenCardName restituisce SCARD_E_NO_MEMORY e le dimensioni necessarie del buffer in nMaxCard.

lpstrTitle

Puntatore a una stringa da inserire nella barra del titolo della finestra di dialogo. Se questo membro è NULL, il sistema usa il titolo predefinito "Select Card:".

dwFlags

Set di flag di bit che è possibile usare per inizializzare la finestra di dialogo. Quando la finestra di dialogo viene restituita, imposta questi flag per indicare l'input dell'utente. Questo membro può essere una combinazione dei flag seguenti.

Valore	Significato
SC_DLG_MINIMAL_UI	Visualizza la finestra di dialogo solo se la scheda cercata dall'applicazione chiamante non si trova e è disponibile per l'uso in un lettore. In questo modo la scheda può essere trovata, connessa (tramite il meccanismo interno della finestra di dialogo o le funzioni di callback dell'utente) e restituita all'applicazione chiamante.
SC_DLG_NO_UI	Forzare nessuna visualizzazione del Selezionare schedainterfaccia utente (UI), indipendentemente dal risultato della ricerca.
SC_DLG_FORCE_UI	Forzare la visualizzazione dell'interfaccia utente di Seleziona scheda, indipendentemente dal risultato della ricerca.

pvUserData

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

dwShareMode

Se lpfnConnect non è NULL, i membri dwShareMode e dwPreferredProtocols.

Se lpfnConnect è NULL e dwShareMode è diverso da zero, viene quindi effettuata una chiamata interna per SCardConnect che usa dwShareMode e dwPreferredProtocols come parametro dwShareMod e e dwPreferredProtocols. Se la connessione ha esito positivo, hCardHandle viene impostata sull'handle restituito da hSCardConnect.

Se lpfnConnect è NULL e dwShareMode è zero, la finestra di dialogo restituisce hCardHandle come NULL.

dwPreferredProtocols

Usato per la connessione interna come descritto in dwShareMode.

dwActiveProtocol

Restituisce il protocollo effettivo in uso quando la finestra di dialogo stabilisce una connessione a una scheda.

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 per l'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
);

lpfnCheck

Puntatore alla routine di verifica della scheda del chiamante. Se non è necessaria alcuna verifica della scheda speciale, questo puntatore viene NULL.

Se la scheda viene rifiutata dalla routine di verifica, viene restituita FALSE e la scheda viene disconnessa, come indicato da lpfnDisconnect.

Se la scheda viene accettata dalla routine di verifica, viene restituita true. Quando l'utente accetta la scheda, tutte le altre schede attualmente connesse verranno disconnesse, come indicato da lpfnDisconnecte questa scheda verrà restituita come scheda individuata. La scheda individuata rimarrà connessa.

Il prototipo della routine di controllo è il seguente.

Check(
  hSCardContext, // the card context passed in the parameter block
  hCard,         // card handle
  pvUserData     // pointer to user data passed in the 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, lpfnChecke lpfnDisconnect, devono essere presenti tutte e tre le procedure 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 la scheda appropriata sia selezionata.

hCardHandle

Handle della scheda connessa (tramite una finestra di dialogo interna connetti o un lpfnConnect callback).

Osservazioni

Nota

L'intestazione winscard.h definisce OPENCARDNAME 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 non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.