Struktur OPENCARDNAMEW (winscard.h)

Struktur OPENCARDNAME berisi informasi yang digunakan fungsi GetOpenCardName untuk menginisialisasi kotak dialog Pilih Kartu pintar. Memanggil SCardUIDlgSelectCard dengan OPENCARDNAME_EX disarankan daripada memanggil GetOpenCardName dengan OPENCARDNAME. OPENCARDNAME disediakan untuk kompatibilitas mundur.

Sintaks

typedef struct {
  DWORD          dwStructSize;
  HWND           hwndOwner;
  SCARDCONTEXT   hSCardContext;
  LPWSTR         lpstrGroupNames;
  DWORD          nMaxGroupNames;
  LPWSTR         lpstrCardNames;
  DWORD          nMaxCardNames;
  LPCGUID        rgguidInterfaces;
  DWORD          cguidInterfaces;
  LPWSTR         lpstrRdr;
  DWORD          nMaxRdr;
  LPWSTR         lpstrCard;
  DWORD          nMaxCard;
  LPCWSTR        lpstrTitle;
  DWORD          dwFlags;
  LPVOID         pvUserData;
  DWORD          dwShareMode;
  DWORD          dwPreferredProtocols;
  DWORD          dwActiveProtocol;
  LPOCNCONNPROCW lpfnConnect;
  LPOCNCHKPROC   lpfnCheck;
  LPOCNDSCPROC   lpfnDisconnect;
  SCARDHANDLE    hCardHandle;
} OPENCARDNAMEW, *POPENCARDNAMEW, *LPOPENCARDNAMEW;

Anggota

dwStructSize

Menentukan panjang, dalam byte, dari struktur. Anggota ini tidak boleh NULL.

hwndOwner

Jendela yang memiliki kotak dialog. Anggota ini bisa menjadi handel jendela yang valid, atau bisa NULL untuk default desktop.

hSCardContext

Konteks yang digunakan untuk komunikasi dengan manajer sumber dayakartu pintar. Panggil SCardEstablishContext untuk mengatur konteks manajer sumber daya dan SCardReleaseContext untuk merilisnya. Anggota ini tidak boleh NULL.

lpstrGroupNames

Penunjuk ke buffer yang berisi string nama grup yang dihentikan null. String terakhir dalam buffer harus dihentikan oleh dua karakter null. Setiap string adalah nama grup kartu yang akan disertakan dalam pencarian. Jika lpstrGroupNamesADALAH NULL, grup default (Scard$DefaultReaders) akan dicari.

nMaxGroupNames

Jumlah maksimum byte (versi ANSI) atau karakter (versi Unicode ) dalam string lpstrGroupNames .

lpstrCardNames

Penunjuk ke buffer yang berisi string nama kartu yang dihentikan null. String terakhir dalam buffer harus dihentikan oleh dua karakter null. Setiap string adalah nama kartu yang akan ditemukan.

nMaxCardNames

Jumlah maksimum byte (versi ANSI) atau karakter (versi Unicode ) dalam string lpstrCardNames .

rgguidInterfaces

Disiapkan untuk penggunaan masa mendatang. Atur ke NULL. Array GUID yang mengidentifikasi antarmuka yang diperlukan.

cguidInterfaces

Dicadangkan untuk penggunaan berjangka. Atur ke NULL. Jumlah antarmuka dalam array rgguidInterfaces .

lpstrRdr

Jika kartu berada, buffer lpstrRdr berisi nama pembaca yang berisi kartu yang terletak. Panjang buffer harus minimal 256 karakter.

nMaxRdr

Ukuran, dalam byte (versi ANSI) atau karakter (versi Unicode ), dari buffer yang diacu oleh lpstrRdr. Jika buffer terlalu kecil untuk berisi informasi pembaca, GetOpenCardName mengembalikan SCARD_E_NO_MEMORY dan ukuran buffer yang diperlukan yang ditunjukkan oleh lpstrRdr.

lpstrCard

Jika kartu berada, buffer lpstrCard berisi nama kartu yang terletak. Panjang buffer harus minimal 256 karakter.

nMaxCard

Ukuran, dalam byte (versi ANSI) atau karakter (versi Unicode ), dari buffer yang diacu oleh lpstrCard. Jika buffer terlalu kecil untuk memuat informasi kartu, GetOpenCardName mengembalikan SCARD_E_NO_MEMORY dan ukuran buffer yang diperlukan di nMaxCard.

lpstrTitle

Penunjuk ke string yang akan ditempatkan di bilah judul kotak dialog. Jika anggota ini NULL, sistem menggunakan judul default "Pilih Kartu:".

dwFlags

Sekumpulan bendera bit yang bisa Anda gunakan untuk menginisialisasi kotak dialog. Saat kotak dialog kembali, kotak dialog mengatur bendera ini untuk menunjukkan input pengguna. Anggota ini bisa menjadi kombinasi dari bendera berikut.

Nilai Makna
SC_DLG_MINIMAL_UI
Menampilkan kotak dialog hanya jika kartu yang sedang dicari oleh aplikasi panggilan tidak ditemukan dan tersedia untuk digunakan dalam pembaca. Ini memungkinkan kartu ditemukan, terhubung (baik melalui mekanisme kotak dialog internal atau fungsi panggilan balik pengguna), dan dikembalikan ke aplikasi panggilan.
SC_DLG_NO_UI
Paksa tidak ada tampilan antarmuka pengguna (UI) Pilih Kartu, terlepas dari hasil pencarian.
SC_DLG_FORCE_UI
Tampilan paksa UI Pilih Kartu , terlepas dari hasil pencarian.

pvUserData

Penunjuk ke data pengguna yang batal. Penunjuk ini diteruskan kembali ke pemanggil pada rutinitas Sambungkan, Periksa, dan Putuskan sambungan.

dwShareMode

Jika lpfnConnect bukan NULL, anggota dwShareMode dan dwPreferredProtocols diabaikan.

Jika lpfnConnect adalah NULL dan dwShareMode bukan nol, maka panggilan internal dilakukan ke SCardConnect yang menggunakan dwShareMode dan dwPreferredProtocols sebagai parameter dwShareMode dan dwPreferredProtocols . Jika koneksi berhasil, hCardHandle diatur ke handel yang dikembalikan oleh hSCardConnect.

Jika lpfnConnect adalah NULL dan dwShareMode adalah nol, kotak dialog mengembalikan hCardHandle sebagai NULL.

dwPreferredProtocols

Digunakan untuk koneksi internal seperti yang dijelaskan dalam dwShareMode.

dwActiveProtocol

Mengembalikan protokol aktual yang digunakan saat kotak dialog membuat koneksi ke kartu.

lpfnConnect

Penunjuk ke kartu menghubungkan rutinitas pemanggil. Jika pemanggil perlu melakukan pemrosesan tambahan untuk menyambungkan ke kartu, penunjuk fungsi ini diatur ke fungsi sambungkan untuk pengguna. Jika fungsi sambungkan berhasil, kartu dibiarkan tersambung dan diinisialisasi, dan handel kartu dikembalikan.

Prototipe untuk rutinitas sambungkan adalah sebagai berikut.

Connect(
  hSCardContext, // the card context passed in the parameter block
  szReader,      // the name of the reader
  mszCards,      // multiple string that contains the 
                 //    possible card names in the reader
  pvUserData     // pointer to user data passed in parameter block
);

lpfnCheck

Penunjuk ke kartu memverifikasi rutinitas pemanggil. Jika tidak ada verifikasi kartu khusus yang diperlukan, pointer ini ADALAH NULL.

Jika kartu ditolak oleh rutinitas verifikasi, FALSE dikembalikan dan kartu terputus, seperti yang ditunjukkan oleh lpfnDisconnect.

Jika kartu diterima oleh rutinitas verifikasi, TRUE dikembalikan. Ketika pengguna menerima kartu, semua kartu lain yang saat ini terhubung akan terputus, seperti yang ditunjukkan oleh lpfnDisconnect, dan kartu ini akan dikembalikan sebagai kartu yang terletak. Kartu yang terletak akan tetap tersambung.

Prototipe untuk rutinitas pemeriksaan adalah sebagai berikut.

Check(
  hSCardContext, // the card context passed in the parameter block
  hCard,         // card handle
  pvUserData     // pointer to user data passed in the parameter block
);

lpfnDisconnect

Penunjuk ke kartu memutuskan rutinitas pemanggil.

Prototipe untuk rutinitas pemutusan sambungan adalah sebagai berikut.

Disconnect(
  hSCardContext, // the card context passed in the parameter block
  hCard,         // card handle
  pvUserData     // pointer to user data passed in the parameter block
);

Catatan Saat menggunakan lpfnConnect, lpfnCheck, dan lpfnDisconnect, ketiga prosedur panggilan balik harus ada. Menggunakan panggilan balik ini memungkinkan verifikasi lebih lanjut bahwa aplikasi panggilan telah menemukan kartu yang sesuai. Ini adalah cara terbaik untuk memastikan kartu yang sesuai dipilih.
 

hCardHandle

Handel kartu yang tersambung (baik melalui kotak dialog internal sambungkan atau panggilan balik lpfnConnect ).

Keterangan

Catatan

Header winscard.h mendefinisikan OPENCARDNAME 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]
Header winscard.h

Lihat juga

GetOpenCardName

SCardConnect

SCardEstablishContext

SCardReleaseContext

SCardUIDlgSelectCard