struttura OPENCARDNAME_EXA (winscard.h)

Articolo
03/09/2024

La struttura OPENCARDNAME_EX contiene le informazioni utilizzate dalla funzione SCardUIDlgSelectCard per inizializzare una finestra di dialogo Seleziona scheda smart card .

Sintassi

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;

Members

dwStructSize

Lunghezza, in byte, della struttura. Il valore di questo membro non deve essere NULL.

hSCardContext

Contesto usato per la comunicazione con lo strumento di gestione risorse della smart card. Chiamare SCardEstablishContext per impostare il contesto di Resource Manager e SCardReleaseContext per rilasciarlo. Il valore di questo membro non deve essere NULL.

hwndOwner

Finestra proprietaria della finestra di dialogo. Questo membro può essere qualsiasi handle di finestra valido o può essere NULL per il desktop predefinito.

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 uno dei flag seguenti.

Valore	Significato
SC_DLG_MINIMAL_UI	Visualizzare 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 dell'interfaccia utenteSeleziona scheda, indipendentemente dal risultato della ricerca.
SC_DLG_FORCE_UI	Forzare la visualizzazione dell'interfaccia utente seleziona scheda , indipendentemente dal risultato della ricerca.

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

lpstrSearchDesc

Puntatore a una stringa da visualizzare all'utente come richiesta di inserire la smart card. Se questo membro è NULL, il sistema utilizza il testo predefinito "Please insert a smart card".

hIcon

Handle a un'icona (32 x 32 pixel). È possibile specificare un'icona specifica del fornitore da visualizzare nella finestra di dialogo. Se questo valore è NULL, viene visualizzata un'icona generica caricata dal lettore di smart card.

pOpenCardSearchCriteria

Puntatore alla struttura OPENCARD_SEARCH_CRITERIA da usare o NULL, se non ne viene utilizzato uno.

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

pvUserData

Puntatore void ai dati utente. Questo puntatore viene passato di nuovo al chiamante nella routine Connect.

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 parametri dwShareMode e dwPreferredProtocols . Se la connessione ha esito positivo, hCardHandle viene impostato sull'handle restituito da SCardConnect. Se lpfnConnect è NULL e dwShareMode è zero, hCardHandle è impostato su NULL.

dwPreferredProtocols

Usato per la connessione interna come descritto in dwShareMode.

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, SCardUIDlgSelectCard 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, SCardUIDlgSelectCard restituisce SCARD_E_NO_MEMORY e le dimensioni necessarie del buffer in nMaxCard.

dwActiveProtocol

Protocollo effettivo in uso quando la finestra di dialogo stabilisce una connessione a una scheda.

hCardHandle

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

Commenti

Nota

L'intestazione winscard.h definisce OPENCARDNAME_EX 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.