Fungsi SCardIntroduceCardTypeA (winscard.h)

Artikel
03/08/2023

Fungsi SCardIntroduceCardType memperkenalkan kartu pintar ke subsistem kartu pintar (untuk pengguna aktif) dengan menambahkannya ke database kartu pintar.

Sintaks

LONG SCardIntroduceCardTypeA(
  [in]           SCARDCONTEXT hContext,
  [in]           LPCSTR       szCardName,
  [in, optional] LPCGUID      pguidPrimaryProvider,
  [in, optional] LPCGUID      rgguidInterfaces,
  [in]           DWORD        dwInterfaceCount,
  [in]           LPCBYTE      pbAtr,
  [in]           LPCBYTE      pbAtrMask,
  [in]           DWORD        cbAtrLen
);

Parameter

[in] hContext

Menangani yang mengidentifikasi konteks resource manager. Konteks resource manager diatur oleh panggilan sebelumnya ke SCardEstablishContext. Parameter ini tidak boleh NULL.

[in] szCardName

Nama tempat pengguna dapat mengenali kartu.

[in, optional] pguidPrimaryProvider

Arahkan ke pengidentifikasi (GUID) untuk penyedia layanan utama kartu pintar.

[in, optional] rgguidInterfaces

Array pengidentifikasi (GUID) yang mengidentifikasi antarmuka yang didukung oleh kartu pintar.

[in] dwInterfaceCount

Jumlah pengidentifikasi dalam array rgguidInterfaces .

[in] pbAtr

String ATR yang dapat digunakan untuk tujuan pencocokan saat mengkueri database kartu pintar (untuk informasi selengkapnya, lihat SCardListCards). Panjang string ini ditentukan oleh penguraian ATR normal.

[in] pbAtrMask

Bitmask opsional untuk digunakan saat membandingkan ATR kartu pintar dengan ATR yang disediakan dalam pbAtr. Jika nilai ini bukan NULL, nilai harus menunjuk ke string byte dengan panjang yang sama dengan string ATR yang disediakan dalam pbAtr. Ketika string ATR yang diberikan A dibandingkan dengan ATR yang disediakan dalam pbAtr, itu cocok jika dan hanya jika A & M = pbAtr, di mana M adalah masker yang disediakan, dan & mewakili BITWISE AND.

[in] cbAtrLen

Panjang ATR dan masker ATR opsional. Jika nilai ini nol, panjang ATR ditentukan oleh penguraian ATR normal. Nilai ini tidak boleh nol jika nilai pbAtr disediakan.

Nilai kembali

Fungsi ini mengembalikan nilai yang berbeda tergantung pada apakah berhasil atau gagal.

Menampilkan kode	Deskripsi
Berhasil	SCARD_S_SUCCESS.
Kegagalan	Kode kesalahan. Untuk informasi selengkapnya, lihat Nilai Pengembalian Kartu Pintar.

Keterangan

Fungsi ini tidak dialihkan, tetapi memanggil fungsi ketika berada di dalam sesi Desktop Jauh tidak akan mengakibatkan kesalahan. Ini hanya berarti bahwa hasilnya akan berasal dari komputer jarak jauh alih-alih komputer lokal.

Fungsi SCardIntroduceCardType adalah fungsi manajemen database. Untuk informasi selengkapnya tentang fungsi manajemen database lainnya, lihat Fungsi Manajemen Database Kartu Pintar.

Untuk menghapus kartu pintar, gunakan SCardForgetCardType.

Contoh

Contoh berikut menunjukkan cara memperkenalkan jenis kartu. Contoh mengasumsikan bahwa hContext adalah handel valid yang diperoleh dari panggilan sebelumnya ke fungsi SCardEstablishContext .

GUID  MyGuid = { 0xABCDEF00,
                 0xABCD,
                 0xABCD,
                 0xAA, 0xBB, 0xCC, 0xDD,
                 0xAA, 0xBB, 0xCC, 0xDD };

static const BYTE MyATR[] =     { 0xaa, 0xbb, 0xcc, 0x00, 0xdd };
static const BYTE MyATRMask[] = { 0xff, 0xff, 0xff, 0x00, 0xff};

LONG            lReturn;

lReturn = SCardIntroduceCardType(hContext, 
                                 L"MyCardName",
                                 &MyGuid,
                                 NULL,    // No interface array
                                 0,       // Interface count = 0
                                 MyATR,
                                 MyATRMask,
                                 sizeof(MyATR));
if ( SCARD_S_SUCCESS != lReturn )
    printf("Failed SCardIntroduceCardType\n");

Catatan

Header winscard.h mendefinisikan SCardIntroduceCardType sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta praprosedur 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


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