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 dapat berupa handel jendela yang valid, atau dapat berupa 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 |
|---|---|
|
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. |
|
Paksa tidak ada tampilan antarmuka pengguna (UI) Pilih Kartu, terlepas dari hasil pencarian. |
|
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
);
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
| Klien minimum yang didukung | Windows XP [hanya aplikasi desktop] |
| Server minimum yang didukung | Windows Server 2003 [hanya aplikasi desktop] |
| Header | winscard.h |