fungsi lineConfigDialogEdit (tapi.h)

Artikel
03/08/2023

Fungsi lineConfigDialogEdit menyebabkan penyedia perangkat baris yang ditentukan menampilkan kotak dialog (dilampirkan ke hwndOwner aplikasi) untuk memungkinkan pengguna mengonfigurasi parameter yang terkait dengan perangkat baris.

Sintaks

LONG lineConfigDialogEdit(
  DWORD        dwDeviceID,
  HWND         hwndOwner,
  LPCSTR       lpszDeviceClass,
  LPVOID const lpDeviceConfigIn,
  DWORD        dwSize,
  LPVARSTRING  lpDeviceConfigOut
);

Parameter

dwDeviceID

Pengidentifikasi perangkat baris yang akan dikonfigurasi.

hwndOwner

Tangani ke jendela tempat kotak dialog akan dilampirkan. Dapat berupa NULL untuk menunjukkan bahwa setiap jendela yang dibuat selama fungsi seharusnya tidak memiliki jendela pemilik.

lpszDeviceClass

Penunjuk ke string yang dihentikan null yang mengidentifikasi nama kelas perangkat. Kelas perangkat ini memungkinkan aplikasi untuk memilih sub-layar tertentu dari informasi konfigurasi yang berlaku untuk kelas perangkat tersebut. Parameter ini bersifat opsional dan dapat dibiarkan NULL atau kosong, dalam hal ini konfigurasi tingkat tertinggi dipilih.

lpDeviceConfigIn

Penunjuk ke struktur data konfigurasi buram yang dikembalikan oleh lineGetDevConfig (atau pemanggilan lineConfigDialogEdit sebelumnya) dalam bagian variabel struktur VARSTRING .

dwSize

Jumlah byte dalam struktur yang diacu oleh lpDeviceConfigIn. Nilai ini dikembalikan dalam anggota dwStringSize dalam struktur VARSTRING yang dikembalikan oleh lineGetDevConfig atau pemanggilan lineConfigDialogEdit sebelumnya.

lpDeviceConfigOut

Arahkan ke lokasi memori jenis VARSTRING tempat struktur konfigurasi perangkat dikembalikan. Setelah berhasil menyelesaikan permintaan, lokasi ini diisi dengan konfigurasi perangkat. Anggota dwStringFormat dalam struktur VARSTRING diatur ke STRINGFORMAT_BINARY. Sebelum memanggil lineGetDevConfig (atau pemanggilan lineConfigDialogEdit di masa mendatang), aplikasi harus mengatur anggota dwTotalSize dari struktur ini untuk menunjukkan jumlah memori yang tersedia untuk TAPI untuk mengembalikan informasi.

Mengembalikan nilai

Mengembalikan nol jika permintaan berhasil atau angka kesalahan negatif jika terjadi kesalahan. Nilai yang mungkin dikembalikan adalah:

LINEERR_BADDEVICEID, LINEERR_OPERATIONFAILED, LINEERR_INVALDEVICECLASS, LINEERR_RESOURCEUNAVAIL, LINEERR_INVALPARAM, LINEERR_STRUCTURETOOSMALL, LINEERR_INVALPOINTER, LINEERR_UNINITIALIZED, LINEERR_NODRIVER, LINEERR_OPERATIONUNAVAIL, LINEERR_NOMEM, LINEERR_NODEVICE.

Keterangan

Jika LINEERR_STRUCTURETOOSMALL dikembalikan, anggota dwTotalSize dari struktur VARSTRING yang diarahkan oleh lpDeviceConfigOut tidak menentukan memori yang cukup untuk berisi seluruh struktur konfigurasi. Anggota dwNeededSize telah diatur ke jumlah yang diperlukan. Sejauh entri pengguna tercermin dalam informasi yang tidak dapat dikembalikan karena ruang yang tidak cukup, pengeditan tersebut hilang; oleh karena itu, aplikasi harus mengalokasikan jumlah maksimum ruang yang mungkin diperlukan oleh kelas perangkat untuk mengembalikan struktur konfigurasinya (untuk informasi selengkapnya, lihat Kelas Perangkat TAPI).

Fungsi lineConfigDialogEdit menyebabkan penyedia layanan menampilkan kotak dialog modal (dilampirkan ke hwndOwner aplikasi) untuk memungkinkan pengguna mengonfigurasi parameter yang terkait dengan baris yang ditentukan oleh dwDeviceID.

Parameter lpszDeviceClass memungkinkan aplikasi untuk memilih sub-layar tertentu dari informasi konfigurasi yang berlaku untuk kelas perangkat tempat pengguna tertarik; string yang diizinkan sama dengan untuk lineGetID. Misalnya, jika baris mendukung Comm API, meneruskan "COMM" sebagai lpszDeviceClass menyebabkan penyedia menampilkan parameter yang terkait khusus untuk Comm (atau, setidaknya, mulai dari titik yang sesuai dalam rantai kotak dialog konfigurasi multilevel, sehingga pengguna tidak perlu "menggali" untuk menemukan parameter yang menarik).

Parameter lpszDeviceClass adalah "tapi/line" , "", atau NULL menyebabkan penyedia menampilkan konfigurasi tingkat tertinggi untuk baris.

Perbedaan antara fungsi ini dan lineConfigDialog adalah sumber parameter untuk diedit dan hasil pengeditan. Dalam lineConfigDialog, parameter yang diedit adalah parameter yang saat ini digunakan pada perangkat (atau diatur untuk digunakan pada panggilan berikutnya), dan setiap perubahan yang dilakukan memiliki (sejauh mungkin) dampak langsung pada koneksi aktif apa pun; selain itu, aplikasi harus menggunakan lineGetDevConfig untuk mengambil hasil perubahan parameter dari lineConfigDialog. Dengan lineConfigDialogEdit, parameter yang akan diedit diteruskan dari aplikasi, dan hasilnya dikembalikan ke aplikasi, tanpa dampak pada koneksi aktif; hasil pengeditan dikembalikan dengan fungsi ini, dan aplikasi tidak perlu memanggil lineGetDevConfig. Dengan demikian, lineConfigDialogEdit mengizinkan aplikasi untuk memberikan kemampuan bagi pengguna untuk menyiapkan parameter untuk panggilan di masa mendatang tanpa berdampak pada panggilan aktif apa pun. Namun, output fungsi ini dapat diteruskan ke lineSetDevConfig untuk memengaruhi panggilan saat ini atau panggilan berikutnya.