Fungsi SCardStatusA (winscard.h)

Fungsi SCardStatus menyediakan status kartu pintar saat ini dalam pembaca. Anda dapat memanggilnya kapan saja setelah panggilan berhasil ke SCardConnect dan sebelum panggilan berhasil ke SCardDisconnect. Ini tidak mempengaruhi statuspembaca atau driver pembaca.

Sintaks

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

Parameter

[in] hCard

Nilai referensi yang dikembalikan dari SCardConnect.

[out] mszReaderNames

Daftar nama tampilan (beberapa string) yang diketahui pembaca yang saat ini tersambung.

[in, out, optional] pcchReaderLen

Pada input, memasok panjang buffer szReaderName .

Pada output, menerima panjang aktual (dalam karakter) dari daftar nama pembaca, termasuk karakter NULL berikutnya. Jika panjang buffer ini ditentukan sebagai SCARD_AUTOALLOCATE, maka szReaderName dikonversi ke penunjuk ke penunjuk byte, dan menerima alamat blok memori yang berisi struktur multi-string.

[out, optional] pdwState

Status kartu pintar saat ini di pembaca. Setelah berhasil, ia menerima salah satu indikator status berikut.

Nilai	Makna
SCARD_ABSENT	Tidak ada kartu di pembaca.
SCARD_PRESENT	Ada kartu di pembaca, tetapi belum dipindahkan ke posisi untuk digunakan.
SCARD_SWALLOWED	Ada kartu di pembaca dalam posisi untuk digunakan. Kartu tidak bertenaga.
SCARD_POWERED	Daya sedang diberikan ke kartu, tetapi driver pembaca tidak menyadari mode kartu.
SCARD_NEGOTIABLE	Kartu telah direset dan sedang menunggu negosiasi PTS.
SCARD_SPECIFIC	Kartu telah direset dan protokol komunikasi tertentu telah dibuat.

[out, optional] pdwProtocol

Protokol saat ini, jika ada. Nilai yang dikembalikan hanya bermakna jika nilai pdwState yang dikembalikan SCARD_SPECIFICMODE.

Nilai	Makna
SCARD_PROTOCOL_RAW	Protokol Transfer Mentah sedang digunakan.
SCARD_PROTOCOL_T0	Protokol ISO 7816/3 T=0 sedang digunakan.
SCARD_PROTOCOL_T1	Protokol ISO 7816/3 T=1 sedang digunakan.

[out] pbAtr

Arahkan ke buffer 32 byte yang menerima string ATR dari kartu yang saat ini dimasukkan, jika tersedia.

[in, out, optional] pcbAtrLen

Pada input, memasok panjang buffer pbAtr . Pada output, menerima jumlah byte dalam string ATR (maksimum 32 byte). Jika panjang buffer ini ditentukan sebagai SCARD_AUTOALLOCATE, maka pbAtr dikonversi ke penunjuk ke penunjuk byte, dan menerima alamat blok memori yang berisi struktur multi-string.

Nilai kembali

Jika fungsi berhasil memberikan status kartu pintar saat ini dalam pembaca, nilai yang dikembalikan SCARD_S_SUCCESS.

Jika fungsi gagal, fungsi akan mengembalikan kode kesalahan. Untuk informasi selengkapnya, lihat Nilai Pengembalian Kartu Pintar.

Keterangan

Fungsi SCardStatus adalah kartu pintar dan fungsi akses pembaca . Untuk informasi tentang fungsi akses lainnya, lihat Kartu Pintar dan Fungsi Akses Pembaca.

Contoh

Contoh berikut menunjukkan cara menentukan status kartu pintar.

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

Catatan

Header winscard.h mendefinisikan SCardStatus sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta pra-prosesor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows XP [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2003 [hanya aplikasi desktop]
Target Platform	Windows
Header	winscard.h
Pustaka	Winscard.lib
DLL	Winscard.dll

Lihat juga

SCardConnect

SCardDisconnect