Funzione SCardConnectA (winscard.h)

Articolo
03/08/2023

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

Sintassi

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

Parametri

[in] hContext

Handle che identifica il contesto di Resource Manager. 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 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 fino a quando non viene inviata una direttiva di controllo IOCTL_SMARTCARD_SET_PROTOCOL con SCardControl.

[out] phCard

Handle che identifica la connessione alla 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 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
Success	SCARD_S_SUCCESS.
Operazioni non riuscite	Codice di errore. Per altre informazioni, vedere Valori restituiti della smart card.
SCARD_E_NOT_READY	Il lettore non è riuscito a connettersi alla scheda.

Commenti

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

Esempio

Nell'esempio seguente viene creata una connessione a un lettore. L'esempio presuppone che hContext sia un handle valido di tipo 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 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]
Piattaforma di destinazione	Windows
Intestazione	winscard.h
Libreria	Winscard.lib
DLL	Winscard.dll

Vedi anche

SCardControl

SCardDisconnect

SCardEstablishContext

SCardReconnect

Condividi tramite