Funzione SCardConnectW (winscard.h)

Articolo
11/20/2024

La funzione di SCardConnect stabilisce una connessione (usando un contesto specifico resource manager) tra l'applicazione chiamante e un smart card contenuto da un lettore specifico. Se nel lettore specificato non esiste alcuna scheda, viene restituito un errore.

Sintassi

LONG SCardConnectW(
  [in]  SCARDCONTEXT  hContext,
  [in]  LPCWSTR       szReader,
  [in]  DWORD         dwShareMode,
  [in]  DWORD         dwPreferredProtocols,
  [out] LPSCARDHANDLE phCard,
  [out] LPDWORD       pdwActiveProtocol
);

Parametri

[in] hContext

Handle che identifica il contesto di gestione risorse . Il contesto di Resource Manager viene impostato da una chiamata precedente a SCardEstablishContext.

[in] szReader

Nome del lettore che contiene la scheda di destinazione.

[in] dwShareMode

Flag che indica se altre applicazioni possono formare connessioni alla scheda.

Valore	Significato
SCARD_SHARE_SHARED	Questa applicazione è disposta a condividere la scheda con altre applicazioni.
SCARD_SHARE_EXCLUSIVE	Questa applicazione non è disposta a condividere la scheda con altre applicazioni.
SCARD_SHARE_DIRECT	Questa applicazione alloca il lettore per l'uso privato e lo controlla direttamente. Nessun'altra applicazione è autorizzata ad accedervi.

[in] dwPreferredProtocols

Maschera di bit di protocolli accettabili per la connessione. I valori possibili possono essere combinati con l'operazione di OR.

Valore	Significato
SCARD_PROTOCOL_T0	T=0 è un protocollo accettabile.
SCARD_PROTOCOL_T1	T=1 è un protocollo accettabile.
0	Questo parametro può essere zero solo se dwShareMode è impostato su SCARD_SHARE_DIRECT. In questo caso, nessuna negoziazione del protocollo verrà eseguita dai driver finché non viene inviata una direttiva di controllo IOCTL_SMARTCARD_SET_PROTOCOL con SCardControl.

[out] phCard

Handle che identifica la connessione al smart card nel lettore designato.

[out] pdwActiveProtocol

Flag che indica il protocollo attivo stabilito.

Valore	Significato
SCARD_PROTOCOL_T0	T=0 è il protocollo attivo.
SCARD_PROTOCOL_T1	T=1 è il protocollo attivo.
SCARD_PROTOCOL_UNDEFINED	SCARD_SHARE_DIRECT è stato specificato, in modo che non si sia verificata alcuna negoziazione del protocollo. È possibile che non vi sia alcuna scheda nel lettore.

Valore restituito

Questa funzione restituisce valori diversi a seconda che abbia esito positivo o negativo.

Codice restituito	Descrizione
esito positivo	SCARD_S_SUCCESS.
errore	Codice di errore. Per altre informazioni, vedere valori restituiti della smart card.
SCARD_E_NOT_READY	Il lettore non è riuscito a connettersi alla scheda.

Osservazioni

La funzione SCardConnect è una smart card e lettore funzione di accesso. Per altre informazioni su altre funzioni di accesso, vedere funzioni di accesso tramite smart card e lettore.

Esempi

Nell'esempio seguente viene creata una connessione a un lettore. Nell'esempio si presuppone che hContext sia un handle di tipo valido SCARDCONTEXT ricevuto da una chiamata precedente a SCardEstablishContext.

SCARDHANDLE     hCardHandle;
LONG            lReturn;
DWORD           dwAP;

lReturn = SCardConnect( hContext, 
                        (LPCTSTR)"Rainbow Technologies SCR3531 0",
                        SCARD_SHARE_SHARED,
                        SCARD_PROTOCOL_T0 | SCARD_PROTOCOL_T1,
                        &hCardHandle,
                        &dwAP );
if ( SCARD_S_SUCCESS != lReturn )
{
    printf("Failed SCardConnect\n");
    exit(1);  // Or other appropriate action.
}

// Use the connection.
// Display the active protocol.
switch ( dwAP )
{
    case SCARD_PROTOCOL_T0:
        printf("Active protocol T0\n"); 
        break;

    case SCARD_PROTOCOL_T1:
        printf("Active protocol T1\n"); 
        break;

    case SCARD_PROTOCOL_UNDEFINED:
    default:
        printf("Active protocol unnegotiated or unknown\n"); 
        break;
}

// Remember to disconnect (by calling SCardDisconnect).
// ...

Nota

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

Fabbisogno

Requisito	Valore
client minimo supportato	Windows XP [solo app desktop]
server minimo supportato	Windows Server 2003 [solo app desktop]
piattaforma di destinazione	Finestre
intestazione	winscard.h
libreria	Winscard.lib
dll	Winscard.dll

Vedere anche

SCardControl

SCardDisconnect

SCardEstablishContext

SCardReconnect

Condividi tramite