Funzione SCardStatusA (winscard.h)

  • Articolo

La funzione SCardStatus fornisce lo stato corrente di una smart card in un lettore. È possibile chiamarlo in qualsiasi momento dopo una chiamata riuscita a SCardConnect e prima di una chiamata riuscita a SCardDisconnect. Non influisce sullo stato del driver lettore o 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 al quale è noto il lettore attualmente connesso.

[in, out, optional] pcchReaderLen

In input, specifica la lunghezza del buffer szReaderName .

Nell'output riceve la lunghezza effettiva (in caratteri) dell'elenco dei nomi 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 di 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. Al termine dell'operazione, 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 lettore non è a conoscenza della modalità della scheda.
SCARD_NEGOTIABLE
 La scheda è stata reimpostata ed è in attesa di negoziazione PTS.
SCARD_SPECIFIC
 La scheda è stata reimpostata e sono stati stabiliti protocolli di comunicazione specifici.

[out, optional] pdwProtocol

Protocollo corrente, se disponibile. 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 input, specifica la lunghezza del buffer 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 convertito in un puntatore a un puntatore di 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 non viene completata, restituisce un codice di errore. Per altre informazioni, vedere Valori restituiti smart card.

Commenti

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

Esempio

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 preprocessore UNICODE. La combinazione dell'utilizzo dell'alias di codifica neutrale con il codice che non è neutrale dalla codifica può causare errori di corrispondenza che causano errori di compilazione o runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzione.

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

SCardConnect

SCardDisconnect