Funzione SCardStatusA (winscard.h)

Articolo
11/20/2024

La funzione SCardStatus fornisce lo stato corrente di un smart card in un lettore . È possibile chiamarlo in qualsiasi momento dopo una chiamata riuscita a SCardConnect e prima di una chiamata corretta a SCardDisconnect. Non influisce sullo stato del lettore o del driver lettore .

Sintassi

LONG SCardStatusA(
  [in]                SCARDHANDLE hCard,
  [out]               LPSTR       mszReaderNames,
  [in, out, optional] LPDWORD     pcchReaderLen,
  [out, optional]     LPDWORD     pdwState,
  [out, optional]     LPDWORD     pdwProtocol,
  [out]               LPBYTE      pbAtr,
  [in, out, optional] LPDWORD     pcbAtrLen
);

Parametri

[in] hCard

Valore di riferimento restituito da SCardConnect.

[out] mszReaderNames

Elenco di nomi visualizzati (più stringhe) in base ai quali è noto il lettore attualmente connesso.

[in, out, optional] pcchReaderLen

In caso di input, fornisce la lunghezza del buffer szReaderName.

Nell'output, riceve la lunghezza effettiva (in caratteri) dell'elenco dei nomi del lettore, incluso il carattere NULL finale. Se questa lunghezza del buffer viene specificata come SCARD_AUTOALLOCATE, szReaderName viene convertita in un puntatore a un puntatore a byte e riceve l'indirizzo di un blocco di memoria contenente la struttura a più stringhe.

[out, optional] pdwState

Stato corrente della smart card nel lettore. In caso di esito positivo, riceve uno degli indicatori di stato seguenti.

Valore	Significato
SCARD_ABSENT	Non c'è scheda nel lettore.
SCARD_PRESENT	C'è una scheda nel lettore, ma non è stata spostata in posizione per l'uso.
SCARD_SWALLOWED	C'è una scheda nel lettore in posizione per l'uso. La scheda non è alimentato.
SCARD_POWERED	L'alimentazione viene fornita alla scheda, ma il driver del lettore non è a conoscenza della modalità della scheda.
SCARD_NEGOTIABLE	La scheda è stata reimpostata ed è in attesa della negoziazione PTS.
SCARD_SPECIFIC	La scheda è stata reimpostata e sono stati stabiliti protocolli di comunicazione specifici .

[out, optional] pdwProtocol

Protocollo corrente, se presente. Il valore restituito è significativo solo se il valore restituito di pdwState è SCARD_SPECIFICMODE.

Valore	Significato
SCARD_PROTOCOL_RAW	Il protocollo di trasferimento non elaborato è in uso.
SCARD_PROTOCOL_T0	Il protocollo ISO 7816/3 T=0 è in uso.
SCARD_PROTOCOL_T1	Il protocollo ISO 7816/3 T=1 è in uso.

[out] pbAtr

Puntatore a un buffer a 32 byte che riceve la stringa ATR dalla scheda attualmente inserita, se disponibile.

[in, out, optional] pcbAtrLen

In caso di input, fornisce la lunghezza del buffer di pbAtr. Nell'output riceve il numero di byte nella stringa ATR (massimo 32 byte). Se questa lunghezza del buffer viene specificata come SCARD_AUTOALLOCATE, pbAtr viene convertita in un puntatore a un puntatore a byte e riceve l'indirizzo di un blocco di memoria contenente la struttura a più stringhe.

Valore restituito

Se la funzione fornisce correttamente lo stato corrente di una smart card in un lettore , il valore restituito è SCARD_S_SUCCESS.

Se la funzione ha esito negativo, restituisce un codice di errore. Per altre informazioni, vedere valori restituiti della smart card.

Osservazioni

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

Esempi

Nell'esempio seguente viene illustrato come determinare lo stato della smart card.

WCHAR           szReader[200];
DWORD           cch = 200;
BYTE            bAttr[32];
DWORD           cByte = 32;
DWORD           dwState, dwProtocol;
LONG            lReturn;

// Determine the status.
// hCardHandle was set by an earlier call to SCardConnect.
lReturn = SCardStatus(hCardHandle,
                      szReader,
                      &cch,
                      &dwState,
                      &dwProtocol,
                      (LPBYTE)&bAttr,
                      &cByte); 

if ( SCARD_S_SUCCESS != lReturn )
{
    printf("Failed SCardStatus\n");
    exit(1);     // or other appropriate action
}

// Examine retrieved status elements.
// Look at the reader name and card state.
printf("%S\n", szReader );
switch ( dwState )
{
    case SCARD_ABSENT:
        printf("Card absent.\n");
        break;
    case SCARD_PRESENT:
        printf("Card present.\n");
        break;
    case SCARD_SWALLOWED:
        printf("Card swallowed.\n");
        break;
    case SCARD_POWERED:
        printf("Card has power.\n");
        break;
    case SCARD_NEGOTIABLE:
        printf("Card reset and waiting PTS negotiation.\n");
        break;
    case SCARD_SPECIFIC:
        printf("Card has specific communication protocols set.\n");
        break;
    default:
        printf("Unknown or unexpected card state.\n");
        break;
}

Nota

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

SCardConnect

SCardDisconnect

Condividi tramite